Collections

Collections are the individual collections of items, similar to tables in a database. Changes to collections will alter the schema of the database.

List Collections

Returns a list of the collections available in the project.

Query Parameters

offset

integer

How many items to skip when fetching data.

meta

string

What metadata to return in the response.

Responses

Successful request

GET /collections

import { createDirectus, rest, readCollections } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readCollections());

POST /graphql/system

type Query {
    collections: [directus_collections]
}

Response Example

{
  "data": [
    {
      "collection": "messages",
      "meta": {
        "collection": "messages",
        "icon": null,
        "note": null,
        "display_template": null,
        "hidden": false,
        "singleton": false,
        "translations": null,
        "archive_field": null,
        "archive_app_filter": true,
        "archive_value": null,
        "unarchive_value": null,
        "sort_field": null,
        "accountability": "all",
        "color": null,
        "item_duplication_fields": null,
        "sort": null,
        "group": null,
        "collapse": "open",
        "preview_url": null,
        "versioning": false
      },
      "schema": {
        "name": "messages",
        "sql": "CREATE TABLE \"messages\" (`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL, `user_created` char(36) NULL, `date_created` datetime NULL, `content` text null, CONSTRAINT `messages_user_created_foreign` FOREIGN KEY (`user_created`) REFERENCES `directus_users` (`id`))"
      }
    }
  ]
}

Create a new collection in Directus. The `collection` and `schema` properties are required. To create a collection folder that doesn't have an underlying table, you can set `schema` to `null`. You are able to provide an array of `fields` to be created during the creation of the collection. See the fields object for more information on what properties are available in a field.

Query Parameters

meta

string

What metadata to return in the response.

Request Body

collection

string

Unique name of the collection.

fields

array

The fields contained in this collection. See the fields reference for more information. Each individual field requires field, type, and interface to be provided.

icon

string

Name of a Google Material Design Icon that's assigned to this collection.

note

string

A note describing the collection.

display_template

string

Text representation of how items from this collection are shown across the system.

hidden

boolean

Whether or not the collection is hidden from the navigation in the admin app.

singleton

boolean

Whether or not the collection is treated as a single object.

translation

string

Key value pairs of how to show this collection's name in different languages in the admin app.

versioning

boolean

Whether or not Content Versioning is enabled for this collection.

archive_field

string

What field holds the archive value.

archive_app_filter

string

What value to use for "archived" items.

archive_value

string

What value to use to "unarchive" items.

unarchive_value

string

Whether or not to show the "archived" filter.

sort_field

string

The sort field in the collection.

Responses

Successful request

data

object

POST /collections

import { createDirectus, rest, createCollection } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(
    createCollection(collection_object)
);

POST /graphql/system

type Mutation {
    create_collections_item(data: directus_collections): directus_collections
}

Response Example

{
  "data": {
    "collection": "customers",
    "translations": [],
    "item_duplication_fields": []
  }
}

Retrieve a Collection

Retrieves the details of a single collection by its table name.

Query Parameters

string

Unique identifier of the collection.

meta

string

What metadata to return in the response.

Responses

Successful request

data

object

GET /collections/{id}

import { createDirectus, rest, readCollection } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readCollection(collection_name));

POST /graphql/system

type Query {
    collections_by_name(name: String!): directus_collections
}

Response Example

{
  "data": {
    "collection": "customers",
    "translations": [],
    "item_duplication_fields": []
  }
}

Delete a Collection

Delete an existing collection. Warning: This will delete the whole collection, including the items within. Proceed with caution.

Query Parameters

string

Unique identifier of the collection.

Responses

The resource was deleted successfully.

DELETE /collections/{id}

import { createDirectus, rest, deleteCollection } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deleteCollection(collection_name));

POST /graphql/system

type Mutation {
    delete_collections_item(collection: String!): delete_collection
}

Update a Collection

Update the metadata for an existing collection. You can only update the `meta` values of the collection object. Updating the collection name is not supported at this time.

Query Parameters

string

Unique identifier of the collection.

meta

string

What metadata to return in the response.

Request Body

meta

object

Metadata of the collection.

Responses

Successful request

data

object

PATCH /collections/{id}

import { createDirectus, rest, updateCollection } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(updateCollection(collection_name, partial_collection_object));

POST /graphql/system

type Mutation {
    update_collections_item(collection: String!, data: update_directus_collections_input!): directus_collections
}

Response Example

{
  "data": {
    "collection": "customers",
    "translations": [],
    "item_duplication_fields": []
  }
}