Menu

Folders

3 endpoints in the Mattering Platform API.

GET folders/ User APIService tier

List folders the caller can see.

Query params: parent_id (a folder id, root for top-level folders, omitted for every folder), q (name contains), starred, trashed, shared_with_me, mine, scope_type, scope_id, sort (name, modified, created; - for descending), limit / offset.

Behaviour differs on the user tier (organization-scoped lookups).

URL

  • User APIhttps://platform.mattering.io/api/user/v1/folders/
  • Service tierhttps://platform.mattering.io/api/internal/folders/

Query parameters

NameDefault
minenone
parent_idnone
qnone
scope_idnone
scope_typenone
shared_with_menone
sortnone
starrednone
trashednone

Pagination

Accepts limit and offset. The response meta carries total, limit and offset.

Responses

200 data and meta envelope

{
  "data": {
    "folders": [
      {
        "id": "...",
        "name": "...",
        "parent_id": "...",
        "owner_user_id": "...",
        "owner_email": "...",
        "scope_type": "...",
        "scope_id": "...",
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "trashed_at": "2026-01-01T00:00:00Z",
        "link": "..."
      }
    ]
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_sort
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/folders/?mine=...&parent_id=...&q=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/drive_views.py (drive_views.folder_list)

POST folders/manage/ User APIService tier

Create, rename, move, star, trash, restore or delete folders.

Body: {"action": "create", "name", "parent_id"?, "scope_type"?, "scope_id"?}, {"action": "rename", "id", "name"}, {"action": "move", "ids", "parent_id"} (root moves to the top level), {"action": "star"|"unstar"|"trash"|"restore"|"delete", "ids"}. delete is permanent and only accepts trashed folders; files inside go to the registry root. Returns the affected folders under data.folders.

Behaviour differs on the user tier (organization-scoped lookups).
This read is not paginated. It returns at most 255 rows and does not report a total, so a result of exactly 255 may be truncated.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/folders/manage/
  • Service tierhttps://platform.mattering.io/api/internal/folders/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
idoptional or conditionalnone
idsoptional or conditionalnone
nameoptional or conditionalnone
parent_idoptional or conditionalnone
scope_idoptional or conditionalnone
scope_typeoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "deleted": [
      "..."
    ]
  }
}

200 data and meta envelope

{
  "data": {
    "folders": [
      {
        "id": "...",
        "name": "...",
        "parent_id": "...",
        "owner_user_id": "...",
        "owner_email": "...",
        "scope_type": "...",
        "scope_id": "...",
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "trashed_at": "2026-01-01T00:00:00Z",
        "link": "..."
      }
    ]
  }
}

201 data and meta envelope

{
  "data": {
    "folders": [
      {
        "id": "...",
        "name": "...",
        "parent_id": "...",
        "owner_user_id": "...",
        "owner_email": "...",
        "scope_type": "...",
        "scope_id": "...",
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "trashed_at": "2026-01-01T00:00:00Z",
        "link": "..."
      }
    ]
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400identity_required
400invalid_action
400invalid_json
400invalid_move
400invalid_scope
400missing_field
400org_required
401unauthorized
409not_trashed

Example

curl -X POST "https://platform.mattering.io/api/user/v1/folders/manage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "id": "...",
  "ids": "...",
  "name": "...",
  "parent_id": "...",
  "scope_id": "...",
  "scope_type": "..."
}'

Source: files/drive_views.py (drive_views.manage_folder)

GET folders/{folder_id}/ User APIService tier

One folder with its breadcrumb (``data.folder``, ``data.path``).

Behaviour differs on the user tier (organization-scoped lookups).

URL

  • User APIhttps://platform.mattering.io/api/user/v1/folders/{folder_id}/
  • Service tierhttps://platform.mattering.io/api/internal/folders/{folder_id}/

Path parameters

NameType
folder_idstr

Responses

200 data and meta envelope

{
  "data": {
    "folder": {
      "id": "...",
      "name": "...",
      "parent_id": "...",
      "owner_user_id": "...",
      "owner_email": "...",
      "scope_type": "...",
      "scope_id": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "trashed_at": "2026-01-01T00:00:00Z",
      "link": "..."
    },
    "path": [
      {
        "id": "...",
        "name": "..."
      }
    ]
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/folders/FOLDER_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/drive_views.py (drive_views.folder_detail)

All Platform resources
Start Free Explore our Products