Collections

Manage collections in Directus

Collections are the database tables in your project. The Collections API allows you to manage collections and their metadata.

List Collections

Retrieve all collections.

GET /collections

Example:

curl "https://your-directus-instance.com/collections" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": [
    {
      "collection": "articles",
      "meta": {
        "collection": "articles",
        "icon": "article",
        "note": "Blog articles",
        "display_template": "{{title}}",
        "hidden": false,
        "singleton": false,
        "translations": null,
        "archive_field": "status",
        "archive_value": "archived",
        "unarchive_value": "draft",
        "sort_field": "sort"
      },
      "schema": {
        "name": "articles",
        "comment": null
      }
    }
  ]
}

Get Collection

Retrieve a single collection.

GET /collections/:collection

Example:

curl "https://your-directus-instance.com/collections/articles" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Collection

Create a new collection.

POST /collections

This creates a new database table. Use with caution in production.

Request Body:

{
  "collection": "posts",
  "meta": {
    "icon": "article",
    "note": "Blog posts collection"
  },
  "schema": {
    "name": "posts"
  },
  "fields": [
    {
      "field": "id",
      "type": "integer",
      "meta": {
        "hidden": true,
        "interface": "input",
        "readonly": true
      },
      "schema": {
        "is_primary_key": true,
        "has_auto_increment": true
      }
    },
    {
      "field": "title",
      "type": "string",
      "meta": {
        "interface": "input",
        "required": true
      },
      "schema": {
        "max_length": 255
      }
    }
  ]
}

Update Collection

Update collection metadata.

PATCH /collections/:collection

Request Body:

{
  "meta": {
    "icon": "article",
    "color": "#6644FF",
    "note": "Updated description"
  }
}

Delete Collection

Delete a collection and all its items.

DELETE /collections/:collection

This permanently deletes the database table and all data. This action cannot be undone.

Example:

curl -X DELETE "https://your-directus-instance.com/collections/posts" \
  -H "Authorization: Bearer YOUR_TOKEN"

Collection Metadata

collection · string

The collection name (table name)

meta.icon · string

Material icon name for the collection

meta.color · string

Hex color code for the collection

meta.note · string

Description of the collection

meta.display_template · string

Template for displaying items (e.g., {{title}})

meta.hidden · boolean

Hide collection from the app navigation

meta.singleton · boolean

Collection contains only one item

meta.archive_field · string

Field name used for archiving (e.g., status)

meta.archive_value · string

Value for archived items (e.g., archived)

meta.unarchive_value · string

Value for active items (e.g., draft)

meta.sort_field · string

Field used for manual sorting

System Collections

Directus includes built-in system collections:

• directus_activity - Activity logs
• directus_collections - Collection metadata
• directus_fields - Field metadata
• directus_files - File uploads
• directus_folders - File folders
• directus_permissions - Permissions rules
• directus_roles - User roles
• directus_users - Users
• directus_settings - Project settings
• directus_flows - Automation flows
• directus_operations - Flow operations
• directus_dashboards - Insights dashboards
• directus_panels - Dashboard panels

System collections cannot be deleted or have their structure modified.

Next Steps

Fields

Manage collection fields

Items

Work with collection items