Menu
GET files/ User APIService tier

List the caller's files with filtering, sorting and paging.

Query params: - folder_id: a folder's id, or root for files in no folder - kind: upload, doc, sheet, slide (comma-separated allowed) - q / search: title or filename contains - starred, trashed, shared_with_me, mine: 1 to switch the view - modified_after: ISO datetime, date, or 7d / 24h - source_app, content_type (MIME prefix), uploaded_by (user id or email) - sort: name, modified, size, created, kind (prefix - for descending) - limit (default 25, max 500), offset; full=1 for storage details Answers {data: {files}, meta} and keeps files / total at the top level.

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

URL

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

Query parameters

NameDefault
fullnone
sortnone

Pagination

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

Responses

200 data and meta envelope

{
  "data": {
    "files": [
      {
        "id": "...",
        "organization_id": "...",
        "filename": "...",
        "title": "...",
        "kind": "...",
        "folder_id": "...",
        "file_size": "...",
        "content_type": "...",
        "uploaded_by_user_id": "...",
        "uploaded_by_email": "...",
        "source_app": "...",
        "source_context": "...",
        "gcs_uri": "...",
        "visibility": "...",
        "is_public": true,
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "modified_by_user_id": "...",
        "trashed_at": "2026-01-01T00:00:00Z",
        "version": "...",
        "is_deleted": true,
        "role": "...",
        "starred": true,
        "editable": "...",
        "editor_path": "...",
        "editor_url": "...",
        "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
400X-Internal-Org-Id header required message
400invalid_sort
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/?full=...&sort=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_list)

POST files/bulk-metadata/ User APIService tier

Batch metadata lookup by file IDs.

POST body: {"ids": ["abc123", "def456", ...]}

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/bulk-metadata/
  • Service tierhttps://platform.mattering.io/api/internal/files/bulk-metadata/

Body keys (JSON)

KeyRequiredDefault
idsoptional or conditional[]

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 bare JSON object (no envelope)

{
  "ok": true,
  "files": {},
  "data": {
    "files": {}
  }
}

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

Errors

StatusCode
400ids must be a list of up to 200 IDs message
400invalid JSON body message
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/bulk-metadata/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": []
}'

Source: files/views.py (views.file_bulk_metadata)

POST files/create/ User APIService tier

Create a blank Doc, Sheet or Slides file from a seed template.

Body: {"kind": "doc"|"sheet"|"slide", "title"?, "folder_id"?, "template"?, "content"?} (template: letter|a4 for doc and sheet, widescreen|standard for slide; content: initial text for a doc, rows or CSV for a sheet, slides for a deck, applied as edit operations on the blank seed, design F4). Answers the new file row plus editor_path.

This read is not paginated. It returns at most 120 rows and does not report a total, so a result of exactly 120 may be truncated.

URL

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

Body keys (JSON)

KeyRequiredDefault
actor_labeloptional or conditionalnone
contentoptional or conditionalnone
folder_idoptional or conditionalnone
kindoptional or conditionalnone
templateoptional or conditionalnone
titleoptional 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

201 data and meta envelope

{
  "data": {
    "files": [
      {
        "id": "...",
        "organization_id": "...",
        "filename": "...",
        "title": "...",
        "kind": "...",
        "folder_id": "...",
        "file_size": "...",
        "content_type": "...",
        "uploaded_by_user_id": "...",
        "uploaded_by_email": "...",
        "source_app": "...",
        "source_context": "...",
        "gcs_uri": "...",
        "visibility": "...",
        "is_public": true,
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "modified_by_user_id": "...",
        "trashed_at": "2026-01-01T00:00:00Z",
        "version": "...",
        "is_deleted": true,
        "role": "...",
        "starred": true,
        "editable": "...",
        "editor_path": "...",
        "editor_url": "...",
        "link": "..."
      }
    ],
    "editor_path": "...",
    "content_summary": []
  }
}

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

Errors

StatusCode
400invalid_json
400invalid_kind
400invalid_template
400org_required
401unauthorized
403editors_disabled

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/create/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "actor_label": "...",
  "content": "...",
  "folder_id": "...",
  "kind": "...",
  "template": "...",
  "title": "..."
}'

Source: files/editors/views.py (views.create_document)

GET files/google/ User APIService tier

Docs, Sheets and Slides the person's Google Drive connector can see.

This read is not paginated. It returns at most 100 rows and does not report a total, so a result of exactly 100 may be truncated.

URL

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

Query parameters

NameDefault
page_tokennone
qnone

Responses

200 data and meta envelope

{
  "data": "...",
  "meta": {
    "total": 0
  }
}

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

Errors

StatusCode
400identity_required
401unauthorized
403editors_disabled

Example

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

Source: files/editors/views.py (views.google_files)

POST files/google/export/ User APIService tier

``{"file_id", "convert"?: true}``: upload a native file to the person's Google Drive, converted to a Google Doc, Sheet or Slides by default.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/google/export/
  • Service tierhttps://platform.mattering.io/api/internal/files/google/export/

Body keys (JSON)

KeyRequiredDefault
convertoptional or conditionaltrue
file_idoptional or conditionalnone
idoptional 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": {
    "google": "...",
    "file_id": "..."
  }
}

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

Errors

StatusCode
400identity_required
400invalid_json
400unsupported
401unauthorized
403editors_disabled
413too_large

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/google/export/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "convert": true,
  "file_id": "...",
  "id": "..."
}'

Source: files/editors/views.py (views.google_export)

POST files/google/import/ User APIService tier

``{"drive_file_id", "folder_id"?}``: export the Google file to OOXML and register it as a native Doc, Sheet or Slides file.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/google/import/
  • Service tierhttps://platform.mattering.io/api/internal/files/google/import/

Body keys (JSON)

KeyRequiredDefault
drive_file_idoptional or conditionalnone
folder_idoptional or conditionalnone
idoptional 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

201 data and meta envelope

{
  "data": {
    "files": [
      {
        "id": "...",
        "organization_id": "...",
        "filename": "...",
        "title": "...",
        "kind": "...",
        "folder_id": "...",
        "file_size": "...",
        "content_type": "...",
        "uploaded_by_user_id": "...",
        "uploaded_by_email": "...",
        "source_app": "...",
        "source_context": "...",
        "gcs_uri": "...",
        "visibility": "...",
        "is_public": true,
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "modified_by_user_id": "...",
        "trashed_at": "2026-01-01T00:00:00Z",
        "version": "...",
        "is_deleted": true,
        "role": "...",
        "starred": true,
        "editable": "...",
        "editor_path": "...",
        "editor_url": "...",
        "link": "..."
      }
    ],
    "editor_path": "..."
  }
}

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

Errors

StatusCode
400identity_required
400invalid_json
400missing_field
401unauthorized
403editors_disabled

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/google/import/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "drive_file_id": "...",
  "folder_id": "...",
  "id": "..."
}'

Source: files/editors/views.py (views.google_import)

POST files/manage/ User APIService tier

Rename, move, copy, star, trash, restore or delete files.

Body: {"action": "rename", "id", "title"}, ``{"action": "move", "ids", "folder_id"} (root for no folder), {"action": "copy", "ids", "folder_id"?, "title"?} (see _copy_files), {"action": "star"|"unstar"| "trash"|"restore"|"delete", "ids"}. delete`` soft-deletes (the registry's existing delete). Returns the affected files under data.files.

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/files/manage/
  • Service tierhttps://platform.mattering.io/api/internal/files/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
folder_idoptional or conditionalnone
idoptional or conditionalnone
idsoptional or conditionalnone
nameoptional or conditionalnone
titleoptional 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": {
    "files": [
      {
        "id": "...",
        "organization_id": "...",
        "filename": "...",
        "title": "...",
        "kind": "...",
        "folder_id": "...",
        "file_size": "...",
        "content_type": "...",
        "uploaded_by_user_id": "...",
        "uploaded_by_email": "...",
        "source_app": "...",
        "source_context": "...",
        "gcs_uri": "...",
        "visibility": "...",
        "is_public": true,
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "modified_by_user_id": "...",
        "trashed_at": "2026-01-01T00:00:00Z",
        "version": "...",
        "is_deleted": true,
        "role": "...",
        "starred": true,
        "editable": "...",
        "editor_path": "...",
        "editor_url": "...",
        "link": "..."
      }
    ]
  }
}

201 data and meta envelope

{
  "data": {
    "files": [
      {
        "id": "...",
        "organization_id": "...",
        "filename": "...",
        "title": "...",
        "kind": "...",
        "folder_id": "...",
        "file_size": "...",
        "content_type": "...",
        "uploaded_by_user_id": "...",
        "uploaded_by_email": "...",
        "source_app": "...",
        "source_context": "...",
        "gcs_uri": "...",
        "visibility": "...",
        "is_public": true,
        "created_at": "2026-01-01T00:00:00Z",
        "modified_at": "2026-01-01T00:00:00Z",
        "modified_by_user_id": "...",
        "trashed_at": "2026-01-01T00:00:00Z",
        "version": "...",
        "is_deleted": true,
        "role": "...",
        "starred": true,
        "editable": "...",
        "editor_path": "...",
        "editor_url": "...",
        "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
400missing_field
400org_required
401unauthorized
413too_large
502delete_failed
502storage_unavailable

Example

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

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

POST files/native/image/ User APIService tier

``{file_id, name, content_type, data_b64}``: store an image the editor inserted as a platform file beside the document (My files, same folder) and answer ``{file_id, src}``. The model carries the file id; the converter inlines the bytes on save.

This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/native/image/
  • Service tierhttps://platform.mattering.io/api/internal/files/native/image/

Query parameters

NameDefault
file_idnone

Body keys (JSON)

KeyRequiredDefault
content_typeoptional or conditionalnone
data_b64optional or conditionalnone
nameoptional 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": {
    "file_id": "...",
    "src": "..."
  }
}

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

Errors

StatusCode
400invalid_image
400invalid_json
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/native/image/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "...",
  "data_b64": "...",
  "name": "..."
}'

Source: files/editors/native.py (native.model_image)

GETPOST files/native/model/ User APIService tier

GET ``?file_id=``: the file as a model. POST ``{file_id, model, base_version, force?, summary?}``: write the model back as a new version.

This read is not paginated. It returns at most 500 rows and does not report a total, so a result of exactly 500 may be truncated.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/native/model/
  • Service tierhttps://platform.mattering.io/api/internal/files/native/model/

Query parameters

NameDefault
file_idnone

Body keys (JSON)

KeyRequiredDefault
base_versionoptional or conditionalnone
forceoptional or conditionalnone
modeloptional or conditionalnone
summaryoptional 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": {
    "file_id": "...",
    "kind": "...",
    "title": "...",
    "role": "...",
    "version": "...",
    "generation": "...",
    "model": "...",
    "simplifications": [
      {
        "key": "...",
        "count": 0,
        "label": "..."
      }
    ]
  }
}

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "version": "...",
    "generation": "...",
    "saved_at": "2026-01-01T00:00:00Z",
    "size": 0
  }
}

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

Errors

StatusCode
400invalid_json
400invalid_model
401unauthorized
403editors_disabled
409version_conflict
413too_large
422unreadable
500dump_failed
502storage_unavailable

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/native/model/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "base_version": "...",
  "force": "...",
  "model": "...",
  "summary": "..."
}'

Source: files/editors/native.py (native.model)

GET files/people/ User APIService tier

Members of the caller's active workspace (templates/WORKSPACE_DIRECTORY_TEMPLATE.md) for the share dialog. ``?q=`` filters by name or email; ``?workspace_id=`` overrides the session / token workspace. Agents are flagged ``is_agent``.

This read is not paginated. It returns at most 50 rows and does not report a total, so a result of exactly 50 may be truncated.

URL

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

Query parameters

NameDefault
qnone
workspace_idnone

Responses

200 data and meta envelope

{
  "data": {
    "people": "...",
    "workspace_id": "..."
  },
  "meta": {
    "total": 0
  }
}

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/files/people/?q=...&workspace_id=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

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

POST files/register/ User APIService tier

Register an existing file in the bucket as a ManagedFile: no upload.

Used during migration: the caller already has a file in the shared GCS bucket and just needs Platform to create the ManagedFile record.

POST body::

{
        "storage_path": "task_attachments/org-uuid/filename.pdf",
        "filename": "report.pdf",
        "file_size": 12345,
        "content_type": "application/pdf",
        "source_app": "productivity",
        "source_context": {"task_id": "...", "file_source": "task-att"},
        "folder_id": "...", "title": "...", "kind": "upload"   (optional)
    }

Returns the same {ok, file} dict as file_upload.

Behaviour differs on the user tier (organization-scoped lookups).
Some branches answer 403 internal_only on the user tier.

URL

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

Body keys (JSON)

KeyRequiredDefault
content_typeoptional or conditionalnone
file_sizeoptional or conditional0
filenameoptional or conditionalnone
folder_idoptional or conditionalnone
kindoptional or conditionalnone
source_appoptional or conditionalnone
source_contextoptional or conditional{}
storage_pathoptional or conditionalnone
titleoptional 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

201 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

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

Errors

StatusCode
400X-Internal-Org-Id header required message
400invalid JSON body message
400invalid_org
400storage_path is required message
401unauthorized
403internal_only
404folder_not_found

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/register/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "...",
  "file_size": 0,
  "filename": "...",
  "folder_id": "...",
  "kind": "...",
  "source_app": "...",
  "source_context": {},
  "storage_path": "..."
}'

Source: files/views.py (views.file_register)

POST files/search/ User APIService tier

Hybrid search over files and folders the caller may read (``data.rows``: chunk_id, file_id, location, context, text).

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

URL

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

Body keys (JSON)

KeyRequiredDefault
file_idsoptional or conditionalnone
folder_idsoptional or conditionalnone
koptional or conditionalnone
qoptional or conditionalnone
queryoptional 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": {
    "rows": "...",
    "files": "...",
    "query": "..."
  },
  "meta": {
    "total": 0,
    "k": "...",
    "backend": "...",
    "files_in_scope": 0
  }
}

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

Errors

StatusCode
400invalid_json
400org_required
400query_required
400scope_required
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/search/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_ids": "...",
  "folder_ids": "...",
  "k": "...",
  "q": "...",
  "query": "..."
}'

Source: files/knowledge/views.py (views.files_search)

POST files/serve-by-path/ User APIService tier

Stream a file from the default storage backend by its raw storage path.

Used by consumer apps (Productivity) to serve legacy files that were uploaded directly to GCS before the file service existed. The caller POSTs {"path": "task_attachments/org/file.pdf"} and this endpoint streams the bytes back, exactly like file_serve but keyed on path instead of managed_file_id.

Behaviour differs on the user tier (organization-scoped lookups).
Some branches answer 403 internal_only on the user tier.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/serve-by-path/
  • Service tierhttps://platform.mattering.io/api/internal/files/serve-by-path/

Body keys (JSON)

KeyRequiredDefault
content_typeoptional or conditionalnone
filenameoptional or conditionalnone
pathoptional 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 non-JSON body

binary or text body

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

Errors

StatusCode
400invalid JSON body message
400path is required message
401unauthorized
403internal_only
404not_found

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/serve-by-path/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "...",
  "filename": "...",
  "path": "..."
}'

Source: files/views.py (views.file_serve_by_path)

GET files/shares/ User APIService tier

Shares on a file or folder (``?file_id=`` or ``?folder_id=``), the inherited folder shares, the link state and the caller's own role.

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

URL

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

Responses

200 data and meta envelope

{
  "data": {
    "shares": [
      {
        "id": "...",
        "principal_type": "...",
        "principal_id": "...",
        "role": "...",
        "expires_at": "2026-01-01T00:00:00Z",
        "expired": true,
        "created_at": "2026-01-01T00:00:00Z",
        "created_by_email": "...",
        "inherited_from": null
      }
    ],
    "owner": {
      "email": "...",
      "user_id": "..."
    },
    "role": "...",
    "can_share": "...",
    "link": "..."
  }
}

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/files/shares/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

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

POST files/shares/manage/ User APIService tier

Grant, change or revoke access; switch the public link.

Body: ``{"action": "add", "file_id"|"folder_id", "principal_type": "user|workspace|project", "principal_id", "role": "viewer|commenter|editor", "expires_at"?}, {"action": "update", "share_id", "role"?, "expires_at"?}``, {"action": "remove", "share_id"}, ``{"action": "link", "file_id", "enabled": true|false, "role"?, "expires_at"?, "rotate"?: true}``. Sharing needs editor access on the target; a person is keyed by email.

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

URL

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

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
enabledoptional or conditionaltrue
expires_atoptional or conditionalnone
file_idoptional or conditionalnone
folder_idoptional or conditionalnone
principal_idoptional or conditionalnone
principal_typeoptional or conditionalnone
roleoptional or conditionalnone
rotateoptional or conditionalnone
share_idoptional 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": {
    "link": "...",
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

200 data and meta envelope

{
  "data": {
    "removed": 0
  }
}

200 data and meta envelope

{
  "data": {
    "share": {
      "id": "...",
      "principal_type": "...",
      "principal_id": "...",
      "role": "...",
      "expires_at": "2026-01-01T00:00:00Z",
      "expired": true,
      "created_at": "2026-01-01T00:00:00Z",
      "created_by_email": "...",
      "inherited_from": null
    }
  }
}

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

Errors

StatusCode
400invalid_action
400invalid_expires_at
400invalid_json
400invalid_principal
400invalid_role
400missing_field
401unauthorized
404not_found

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/shares/manage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "enabled": true,
  "expires_at": "...",
  "file_id": "...",
  "folder_id": "...",
  "principal_id": "...",
  "principal_type": "...",
  "role": "..."
}'

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

GET files/storage/ User APIService tier

Bytes the organization stores (live files, trash separately) and the plan's storage cap when auth enforces one.

URL

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

Responses

200 data and meta envelope

{
  "data": {
    "used_bytes": 0,
    "trashed_bytes": 0,
    "cap_bytes": "...",
    "file_count": "..."
  }
}

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/files/storage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

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

POST files/upload/ User APIService tier

Upload a file to the managed file service.

Expects multipart form data with: - file: the uploaded file - source_app: originating app slug (required) - source_context: JSON string with app-specific metadata (optional) - folder_id, title, kind: Drive placement (optional)

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

URL

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

Responses

201 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

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

Errors

StatusCode
400No file provided message
400X-Internal-Org-Id header required message
400invalid_org
400source_app is required message
400source_context must be valid JSON message
400validation_error
401unauthorized
403app_scope_mismatch
403forbidden
404folder_not_found
500upload_failed

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/upload/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_upload)

POST files/upload/finish/ User APIService tier

``{"upload_id", "filename"?, "folder_id"?, "title"?}``: register the object ``upload_start`` issued as a file owned by the caller. The id must be one this organization was issued, the object must exist and not be registered yet; folder and plan limits are checked again.

This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/upload/finish/
  • Service tierhttps://platform.mattering.io/api/internal/files/upload/finish/

Body keys (JSON)

KeyRequiredDefault
filenameoptional or conditionalnone
folder_idoptional or conditionalnone
storage_pathoptional or conditionalnone
titleoptional or conditionalnone
upload_idoptional 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

201 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

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

Errors

StatusCode
400invalid_json
400invalid_upload_id
400missing_field
400org_required
401unauthorized
404upload_not_found
409already_registered
501direct_upload_unavailable

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/upload/finish/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "...",
  "folder_id": "...",
  "storage_path": "...",
  "title": "...",
  "upload_id": "..."
}'

Source: files/transfer_views.py (transfer_views.upload_finish)

POST files/upload/session/ User APIService tier

Open a resumable-upload session in the files bucket for one object, so a service can store a file larger than one Cloud Run request (32 MiB) without streaming it through this service.

POST body: {"filename", "file_size", "content_type"}. Answers {ok, mode: "direct", upload_url, storage_path}: the caller PUTs the bytes to upload_url and then registers storage_path with files/register/. mode: "legacy" where the storage is not a bucket (local development): use files/upload/. S2S only, like register.

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/upload/session/
  • Service tierhttps://platform.mattering.io/api/internal/files/upload/session/

Body keys (JSON)

KeyRequiredDefault
content_typeoptional or conditionalnone
file_sizeoptional or conditionalnone
filenameoptional 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": {
    "mode": "direct",
    "upload_url": "...",
    "storage_path": "..."
  }
}

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

Errors

StatusCode
400invalid_json
400invalid_org
400missing_field
401unauthorized
403internal_only

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/upload/session/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "...",
  "file_size": "...",
  "filename": "..."
}'

Source: files/views.py (views.file_upload_session)

POST files/upload/start/ User APIService tier

``{"filename", "file_size", "content_type"?, "folder_id"?}``: answers ``{mode: "direct", upload_url, upload_id, method: "PUT", headers}``. The folder needs edit access; the size is checked against the plan now and again on finish (with the size storage reports).

This read is not paginated. It returns at most 200 rows and does not report a total, so a result of exactly 200 may be truncated.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/upload/start/
  • Service tierhttps://platform.mattering.io/api/internal/files/upload/start/

Body keys (JSON)

KeyRequiredDefault
content_typeoptional or conditionalnone
file_sizeoptional or conditionalnone
filenameoptional or conditionalnone
folder_idoptional 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": {
    "mode": "direct",
    "upload_url": "...",
    "upload_id": "...",
    "method": "PUT",
    "headers": {
      "Content-Type": "..."
    },
    "filename": "...",
    "note": "..."
  }
}

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

Errors

StatusCode
400invalid_file_size
400invalid_json
400missing_field
400org_required
401unauthorized
501direct_upload_unavailable

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/upload/start/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "...",
  "file_size": "...",
  "filename": "...",
  "folder_id": "..."
}'

Source: files/transfer_views.py (transfer_views.upload_start)

GET files/versions/ User APIService tier

Versions of a file, newest first. ``?file_id=`` required; ``for_editor=1`` adds the Document Server history keys and download URLs.

URL

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

Query parameters

NameDefault
file_idnone
for_editornone

Responses

200 data and meta envelope

{
  "data": {
    "versions": [
      {
        "number": "...",
        "name": "...",
        "summary": "...",
        "created_at": "2026-01-01T00:00:00Z",
        "created_by_email": "...",
        "is_current": true,
        "download_path": "...",
        "key": "...",
        "url": "..."
      }
    ],
    "current": "...",
    "file_id": "...",
    "role": "..."
  },
  "meta": {
    "total": 0
  }
}

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/files/versions/?file_id=...&for_editor=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/editors/views.py (views.version_list)

GET files/versions/current/ User APIService tier

What an open editor page asks every few seconds: the current version and whether its session key is still the file's. ``?file_id=&key=``. A key that is no longer pinned (an API write ended the session, or a restore) means the page should reopen; the newest version's author and name let it say who changed what. Database only, no storage calls.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/versions/current/
  • Service tierhttps://platform.mattering.io/api/internal/files/versions/current/

Query parameters

NameDefault
file_idnone
keynone

Responses

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "current": "...",
    "session_live": true,
    "latest": {
      "number": "...",
      "name": "...",
      "summary": "...",
      "by": "...",
      "at": "2026-01-01T00:00:00Z"
    }
  }
}

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/files/versions/current/?file_id=...&key=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/editors/views.py (views.version_current)

POST files/versions/manage/ User APIService tier

``{"action": "restore", "file_id", "number"}`` copies that version's bytes over the current ones and records a new version; ``{"action": "name", "file_id", "number", "name"}`` names a version.

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/files/versions/manage/
  • Service tierhttps://platform.mattering.io/api/internal/files/versions/manage/

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
file_idoptional or conditionalnone
idoptional or conditionalnone
nameoptional or conditionalnone
numberoptional 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": {
    "version": {
      "number": "...",
      "name": "...",
      "summary": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "created_by_email": "...",
      "is_current": true,
      "download_path": "...",
      "key": "...",
      "url": "..."
    },
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

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

Errors

StatusCode
400invalid_action
400invalid_json
400missing_field
401unauthorized
403editors_disabled
404not_found
409conflict
409not_restorable

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/versions/manage/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "file_id": "...",
  "id": "...",
  "name": "...",
  "number": "..."
}'

Source: files/editors/views.py (views.manage_version)

GET files/{file_id}/ User APIService tier

Return metadata for a single managed file (``data.file``; ``file`` kept).

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

URL

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

Path parameters

NameType
file_idstr

Responses

200 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    }
  }
}

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/files/FILE_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_metadata)

GET files/{file_id}/content/ User APIService tier

Read a range of a file's extracted text (``data.text``, ``data.location``, ``data.truncated``, ``data.next``).

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/content/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/content/

Path parameters

NameType
file_idstr

Query parameters

NameDefault
formatnone
max_charsnone
rangenone

Responses

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "title": "...",
    "version": "...",
    "kind": "...",
    "format": "...",
    "range": "...",
    "source": "...",
    "note": "..."
  }
}

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

Errors

StatusCode
400invalid_format
400invalid_range
400not_editable
401unauthorized
422not_extracted
422unreadable

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/FILE_ID/content/?format=...&max_chars=...&range=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/knowledge/views.py (views.file_content)

DELETE files/{file_id}/delete/ User APIService tier

Soft-delete a managed file (needs editor access on the user tiers).

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/delete/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/delete/

Path parameters

NameType
file_idstr

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "data": {
    "deleted": true
  }
}

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 DELETE "https://platform.mattering.io/api/user/v1/files/FILE_ID/delete/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_delete)

GET files/{file_id}/export/ User APIService tier

A short-lived download link (``data.url``). ``format``: omitted or ``original`` for the file as stored (Docs, Sheets and Slides are stored as docx, xlsx and pptx), or pdf / odt / ods / odp / csv where file_pack can convert it. ``ttl`` seconds (60 to 43200); a converted file's link is signed by file_pack, which caps it at its own lifetime (1 hour by default). ``expires_in`` is always the real lifetime. View access is enough.

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/export/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/export/

Path parameters

NameType
file_idstr

Query parameters

NameDefault
formatnone
ttlnone

Responses

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "url": "...",
    "format": "...",
    "filename": "...",
    "content_type": "...",
    "expires_in": "...",
    "expires_at": "...",
    "ttl_note": "..."
  }
}

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "url": "...",
    "expires_in": 0,
    "format": "...",
    "filename": "...",
    "content_type": "...",
    "size": "..."
  }
}

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

Errors

StatusCode
400unsupported_format
401unauthorized
501signing_unavailable

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/FILE_ID/export/?format=...&ttl=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/transfer_views.py (transfer_views.export_link)

GET files/{file_id}/gcs-uri/ User APIService tier

Return the GCS URI for a managed file (worker direct access).

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/gcs-uri/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/gcs-uri/

Path parameters

NameType
file_idstr

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "gcs_uri": "..."
}

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

Errors

StatusCode
401unauthorized
404gcs_not_configured

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/FILE_ID/gcs-uri/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_gcs_uri)

GET files/{file_id}/knowledge/ User APIService tier

The knowledge bundle for one file: row, extract state, capped TOC, summary, and the text when it fits ``inline_max_chars``.

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/knowledge/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/knowledge/

Path parameters

NameType
file_idstr

Query parameters

NameDefault
indexnone
inline_max_charsnone
tocnone
toc_max_charsnone

Responses

200 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    },
    "extract": {
      "status": "...",
      "version": "...",
      "kind": "...",
      "text_chars": "...",
      "approx_tokens": "...",
      "toc_entries": 0,
      "toc_text": "...",
      "summary": "...",
      "indexed": true,
      "chunks": 0,
      "vector_backend": "...",
      "error": "...",
      "toc": "...",
      "note": "This PDF has no text layer (a scan); nothing to read or search."
    },
    "tier": "retrieval",
    "text": "...",
    "text_source": "..."
  }
}

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/files/FILE_ID/knowledge/?index=...&inline_max_chars=...&toc=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/knowledge/views.py (views.file_knowledge)

POST files/{file_id}/ops/ User APIService tier

Apply edit operations (replace_text, insert_blocks, set_cells, add_slide, rename) and write a named version (``data.version``).

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/ops/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/ops/

Path parameters

NameType
file_idstr

Body keys (JSON)

KeyRequiredDefault
actor_labeloptional or conditionalnone
agent_nameoptional or conditionalnone
base_versionoptional or conditionalnone
opsoptional 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": {
    "file": {
      "id": "...",
      "organization_id": "...",
      "filename": "...",
      "title": "...",
      "kind": "...",
      "folder_id": "...",
      "file_size": "...",
      "content_type": "...",
      "uploaded_by_user_id": "...",
      "uploaded_by_email": "...",
      "source_app": "...",
      "source_context": "...",
      "gcs_uri": "...",
      "visibility": "...",
      "is_public": true,
      "created_at": "2026-01-01T00:00:00Z",
      "modified_at": "2026-01-01T00:00:00Z",
      "modified_by_user_id": "...",
      "trashed_at": "2026-01-01T00:00:00Z",
      "version": "...",
      "is_deleted": true,
      "role": "...",
      "starred": true,
      "editable": "...",
      "editor_path": "...",
      "editor_url": "...",
      "link": "..."
    },
    "version": {
      "number": "...",
      "name": "...",
      "summary": "..."
    },
    "extract": {
      "status": "...",
      "version": "...",
      "kind": "...",
      "text_chars": "...",
      "approx_tokens": "...",
      "toc_entries": 0,
      "toc_text": "...",
      "summary": "...",
      "indexed": true,
      "chunks": 0,
      "vector_backend": "...",
      "error": "...",
      "toc": "...",
      "note": "This PDF has no text layer (a scan); nothing to read or search."
    }
  }
}

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

Errors

StatusCode
400invalid_json
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/files/FILE_ID/ops/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "actor_label": "...",
  "agent_name": "...",
  "base_version": "...",
  "ops": "..."
}'

Source: files/knowledge/views.py (views.file_ops)

GET files/{file_id}/preview/ User APIService tier

Render pages of a file as images: ``data.pages`` (signed URLs, 1 hour) and ``data.inline`` (the first requested page as base64 JPEG).

Query params: pages ("1", "1-3", "2,5-7" or "all"; default "1"; at most 50 pages per call), width (pixels, 64..2048, default 1280), format (png | jpeg, default png). Read access is enough. Office documents are converted through LibreOffice first; PDFs and images are drawn as they are.

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/preview/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/preview/

Path parameters

NameType
file_idstr

Query parameters

NameDefault
formatnone
pagesnone
widthnone

Responses

200 data and meta envelope

{
  "data": {
    "file_id": "...",
    "title": "...",
    "kind": "...",
    "version": "...",
    "page_count": 0,
    "format": "...",
    "width": "...",
    "pages": [
      {
        "number": "...",
        "url": "...",
        "width": "...",
        "height": "..."
      }
    ],
    "inline": {
      "number": "...",
      "content_base64": "...",
      "media_type": "...",
      "width": "...",
      "height": "..."
    },
    "expires_at": "..."
  }
}

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

Errors

StatusCode
400invalid_format
400invalid_pages
400invalid_width
401unauthorized
503not_configured

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/FILE_ID/preview/?format=...&pages=...&width=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/editors/preview.py (preview.file_preview)

GET files/{file_id}/serve/ User APIService tier

Stream file bytes to the caller.

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/serve/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/serve/

Path parameters

NameType
file_idstr

Responses

200 non-JSON body

binary or text body

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/files/FILE_ID/serve/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_serve)

GET files/{file_id}/signed-url/ User APIService tier

A short-lived signed link to the file's bytes on Cloud Storage.

Query params: ttl seconds (60 to 43200, default 21600) and download=1 for an attachment disposition. Answers {ok, url, expires_in, content_type}; 501 signing_unavailable where the storage cannot sign (local development). Tenant-scoped and ACL-checked like every by-id route.

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

URL

  • User APIhttps://platform.mattering.io/api/user/v1/files/{file_id}/signed-url/
  • Service tierhttps://platform.mattering.io/api/internal/files/{file_id}/signed-url/

Path parameters

NameType
file_idstr

Query parameters

NameDefault
downloadnone
ttlnone

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "url": "...",
  "expires_in": "...",
  "content_type": "..."
}

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

Errors

StatusCode
401unauthorized
501signing_unavailable

Example

curl -X GET "https://platform.mattering.io/api/user/v1/files/FILE_ID/signed-url/?download=...&ttl=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: files/views.py (views.file_signed_url)

All Platform resources
Start Free Explore our Products