Collections

Collections are the individual collections of items, similar to tables in a database.

Changes to collections will alter the schema of the database.

Endpoints
   GET /:project/collections
   GET /:project/collections/:collection
  POST /:project/collections
 PATCH /:project/collections/:collection
DELETE /:project/collections/:collection

The Collection Object

Attributes

collection string

Unique name of the collection.

note string

A note describing the collection.

hidden boolean

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

single boolean

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

managed boolean

If Directus is tracking and managing this collection currently.

fields string

The fields contained in this collection. See the fields reference for more information.

icon string

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

translation object

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

Collection object
{
  "collection": "customers",
  "note": "Our most valued money makers",
  "hidden": false,
  "single": false,
  "managed": true,
  "fields": { ... },
  "icon": "perm_contact_calendar",
  "translation": {
    "en-US": "Customers",
    "nl-NL": "Klanten"
  }
}

List Collections

Returns a list of the collections available in the project.

Parameters

project required

The project you're targetting.

Query

offset optional

How many items to skip when fetching data. Default is 0. Learn more

single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

An object with a data property that contains an array of available collection objects. This array also contains the Directus system collections and is never empty.

Endpoint
GET /:project/collections
Response
{
  "data": [
  	{
      "collection": "customers",
      "note": "Our most valued money makers",
      "hidden": false,
      "single": false,
      "managed": true,
      "fields": { ... },
      "icon": "perm_contact_calendar",
      "translation": {
        "en-US": "Customers",
        "nl-NL": "Klanten"
      }
    },
    { ... },
    { ... }
  ]
}

Retrieve a Collection

Retrieves the details of a single collection.

Parameters

project required

The project you're targetting.

collection required

The unique name of the collection.

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns a collection object.

Endpoint
GET /:project/collections/:collection
Response
{
  "data": {
    "collection": "customers",
    "note": "Our most valued money makers",
    "hidden": false,
    "single": false,
    "managed": true,
    "fields": { ... },
    "icon": "perm_contact_calendar",
    "translation": {
      "en-US": "Customers",
      "nl-NL": "Klanten"
    }
  }
}

Create a Collection

Create a new collection in Directus.

Parameters

project required

The project you're targetting.

Attributes

collection Required

Unique name of the collection.

fields Required

The fields contained in this collection. See the fields reference for more information.

Each individual field requires field, type, and interface to be provided.

WARNING

Don't forget to create a primary key field in your collection. Without it, Directus won't be able to work correctly.

note optional

A note describing the collection.

hidden optional

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

single optional

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

managed optional

If Directus is tracking and managing this collection currently.

icon optional

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

translation optional

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

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns the newly created collection object.

Endpoint
  POST /:project/collections
Request body
{
  "collection": "my_collection",
  "fields": [
    {
      "field": "id",
      "type": "integer",
      "datatype": "int",
      "length": 11,
      "interface": "numeric",
      "primary_key": true
    }
  ]
}
Response
{
  "data": {
    "collection": "my_collection",
    "managed": true,
    "hidden": false,
    "single": false,
    "icon": null,
    "note": null,
    "translation": null
  }
}

Update a Collection

Update an existing collection.

WARNING

You can't update a collection's name.

Parameters

project required

The project you're targetting.

collection required

The collection you want to update.

Attributes

note optional

A note describing the collection.

hidden optional

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

single optional

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

managed optional

If Directus is tracking and managing this collection currently.

icon optional

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

translation optional

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

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns the collection object for the updated collection.

Endpoint
 PATCH /:project/collections/:collection
Request body
{
  "note": "This is my first collection"
}
Response
{
  "data": {
    "collection": "my_collection",
    "managed": true,
    "hidden": false,
    "single": false,
    "icon": null,
    "note": "This is my first collection",
    "translation": null
  }
}

Delete a Collection

Delete an existing collection.

WARNING

This will delete the whole collection, including the items within. Proceed with caution.

Parameters

project required

The project you're targetting.

collection required

The collection you want to delete.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/collections/:collection