Collection

The Collection API manages collections in Metabase. Collections are folders that organize dashboards, questions, and other content. This API includes 12 endpoints.

List collections

Get all collections you have access to.

GET /api/collection

curl -X GET \
  https://your-metabase.com/api/collection \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Query parameters

archived

boolean

Show archived collections instead of active ones (default: false)

exclude-other-user-collections

boolean

Hide other users’ personal collections (default: false)

personal-only

boolean

Show only personal collections (default: false)

namespace

string

Filter by namespace (e.g., “snippets”)

Response

[
  {
    "id": 5,
    "name": "Marketing",
    "description": "Marketing analytics",
    "color": "#509EE3",
    "can_write": true,
    "parent_id": null,
    "personal_owner_id": null
  }
]

can_write

boolean

Whether you have write permissions for this collection

Get collection

Get details about a specific collection.

GET /api/collection/{id}

curl -X GET \
  https://your-metabase.com/api/collection/5 \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Parameters

integer

required

Collection ID

Response

integer

Collection ID

name

string

Collection name

description

string

Collection description

color

string

Color hex code for the collection icon

archived

boolean

Whether the collection is archived

parent_id

integer

Parent collection ID (null for top-level collections)

personal_owner_id

integer

User ID if this is a personal collection

authority_level

string

Authority level (“official” or null)

Create collection

Create a new collection.

POST /api/collection

curl -X POST \
  https://your-metabase.com/api/collection \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "New Collection",
    "description": "Collection description",
    "color": "#509EE3"
  }'

Request body

name

string

required

Collection name (minimum 1 character)

description

string

Collection description

color

string

Color hex code (e.g., “#509EE3”)

parent_id

integer

Parent collection ID to create a nested collection

namespace

string

Namespace for special collection types

authority_level

string

Set to “official” to mark as an official collection (requires admin)

Update collection

Update an existing collection.

PUT /api/collection/{id}

curl -X PUT \
  https://your-metabase.com/api/collection/5 \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "Updated Collection Name",
    "description": "Updated description"
  }'

Parameters

integer

required

Collection ID

Request body

All fields are optional.

name

string

Updated collection name

description

string

Updated description

color

string

Updated color

archived

boolean

Archive or unarchive the collection

parent_id

integer

Move to a different parent collection

Delete collection

Permanently delete a collection.

DELETE /api/collection/{id}

curl -X DELETE \
  https://your-metabase.com/api/collection/5 \
  -H 'X-Metabase-Session: SESSION_TOKEN'

This permanently deletes the collection and all its contents. Items in the collection cannot be recovered.

Get collection items

Get all items (dashboards, questions, etc.) in a collection.

GET /api/collection/{id}/items

curl -X GET \
  https://your-metabase.com/api/collection/5/items \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Query parameters

models

array

Filter by model types: card, dashboard, dataset, collection, etc.

archived

boolean

Include archived items (default: false)

pinned_state

string

Filter by pin state: is_pinned, is_not_pinned, or all

sort_column

string

Sort by: name, last_edited_at, last_edited_by, model, or description

sort_direction

string

Sort direction: asc or desc

Response

{
  "data": [
    {
      "id": 1,
      "name": "Sales Dashboard",
      "model": "dashboard",
      "description": "Overview of sales metrics",
      "collection_position": null,
      "display": "dashboard",
      "last_edited_at": "2024-03-01T10:00:00Z",
      "last_edited_by": {
        "id": 1,
        "common_name": "John Doe"
      }
    }
  ],
  "total": 1
}

Root collection

Get root collection

Get the root collection (top-level).

GET /api/collection/root

curl -X GET \
  https://your-metabase.com/api/collection/root \
  -H 'X-Metabase-Session: SESSION_TOKEN'

The root collection is a virtual collection that contains all items not in any other collection.

Get root collection items

Get items in the root collection.

GET /api/collection/root/items

curl -X GET \
  https://your-metabase.com/api/collection/root/items \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Supports the same query parameters as /api/collection/{id}/items.

Collection tree

Get the full collection hierarchy tree.

GET /api/collection/tree

curl -X GET \
  https://your-metabase.com/api/collection/tree \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Response

Returns a nested tree structure of all collections:

[
  {
    "id": "root",
    "name": "Our analytics",
    "children": [
      {
        "id": 5,
        "name": "Marketing",
        "children": [
          {
            "id": 12,
            "name": "Campaigns",
            "children": []
          }
        ]
      }
    ]
  }
]

Collection permissions

Get permissions graph

Get the full collection permissions graph.

GET /api/collection/graph

curl -X GET \
  https://your-metabase.com/api/collection/graph \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Requires admin permissions.

Update permissions graph

Update collection permissions for groups.

PUT /api/collection/graph

curl -X PUT \
  https://your-metabase.com/api/collection/graph \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "groups": {
      "1": {
        "5": "write",
        "root": "read"
      }
    }
  }'

Request body

groups

object

required

Map of group IDs to their collection permissionsPermission values:

"none" - No access
"read" - Read-only access
"write" - Full access

revision

integer

Current revision number (for optimistic locking)

Query parameters

force

boolean

Skip revision check and force update (default: false)

skip-graph

boolean

Only return revision, not full graph (default: false)

Move items

Move multiple cards to a collection.

POST /api/cards/move

See Card API for details.

Trash

Get items in trash (archived collections).

GET /api/collection/trash

curl -X GET \
  https://your-metabase.com/api/collection/trash \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Overview

Core Resources

User Management

Advanced

List collections

Query parameters

Response

Get collection

Parameters

Response

Create collection

Request body

Update collection

Parameters

Request body

Delete collection

Get collection items

Query parameters

Response

Root collection

Get root collection

Get root collection items

Collection tree

Response

Collection permissions

Get permissions graph

Update permissions graph

Request body

Query parameters

Move items

Trash

Overview

Core Resources

User Management

Advanced

Documentation Index

​List collections

​Query parameters

​Response

​Get collection

​Parameters

​Response

​Create collection

​Request body

​Update collection

​Parameters

​Request body

​Delete collection

​Get collection items

​Query parameters

​Response

​Root collection

​Get root collection

​Get root collection items

​Collection tree

​Response

​Collection permissions

​Get permissions graph

​Update permissions graph

​Request body

​Query parameters

​Move items

​Trash

List collections

Query parameters

Response

Get collection

Parameters

Response

Create collection

Request body

Update collection

Parameters

Request body

Delete collection

Get collection items

Query parameters

Response

Root collection

Get root collection

Get root collection items

Collection tree

Response

Collection permissions

Get permissions graph

Update permissions graph

Request body

Query parameters

Move items

Trash