GET
folders/
User API Service 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 API https://platform.mattering.io/api/user/v1/folders/
Service tier https://platform.mattering.io/api/internal/folders/
Query parameters
Name Default
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
Status Code
400 invalid_sort401 unauthorized
Example
User API Service tier
curl -X GET "https://platform.mattering.io/api/user/v1/folders/?mine=...&parent_id=...&q=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://platform.mattering.io/api/internal/folders/?mine=...&parent_id=...&q=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: files/drive_views.py (drive_views.folder_list)
POST
folders/manage/
User API Service 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 API https://platform.mattering.io/api/user/v1/folders/manage/
Service tier https://platform.mattering.io/api/internal/folders/manage/
Body keys (JSON)
Key Required Default
actionoptional or conditional none idoptional or conditional none idsoptional or conditional none nameoptional or conditional none parent_idoptional or conditional none scope_idoptional or conditional none scope_typeoptional or conditional none
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
Status Code
400 identity_required400 invalid_action400 invalid_json400 invalid_move400 invalid_scope400 missing_field400 org_required401 unauthorized409 not_trashed
Example
User API Service tier
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": "..."
}' curl -X POST "https://platform.mattering.io/api/internal/folders/manage/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-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 API Service tier
One folder with its breadcrumb (``data.folder``, ``data.path``).
Behaviour differs on the user tier (organization-scoped lookups).
URL
User API https://platform.mattering.io/api/user/v1/folders/{folder_id} /
Service tier https://platform.mattering.io/api/internal/folders/{folder_id} /
Path parameters
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
Status Code
401 unauthorized
Example
User API Service tier
curl -X GET "https://platform.mattering.io/api/user/v1/folders/FOLDER_ID/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://platform.mattering.io/api/internal/folders/FOLDER_ID/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: files/drive_views.py (drive_views.folder_detail)