Directus Docs

# Collections

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

Changes to collections will alter the schema of the database.

# 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.

# 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.

DANGER

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

← Collection Presets →