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
Name
Default
full
none
sort
none
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
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)
Key
Required
Default
ids
optional 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.
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)
Key
Required
Default
actor_label
optional or conditional
none
content
optional or conditional
none
folder_id
optional or conditional
none
kind
optional or conditional
none
template
optional or conditional
none
title
optional 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.
``{"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)
Key
Required
Default
convert
optional or conditional
true
file_id
optional or conditional
none
id
optional 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
200data 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).
``{"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)
Key
Required
Default
drive_file_id
optional or conditional
none
folder_id
optional or conditional
none
id
optional 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.
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)
Key
Required
Default
action
optional or conditional
none
folder_id
optional or conditional
none
id
optional or conditional
none
ids
optional or conditional
none
name
optional or conditional
none
title
optional 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.
``{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
Name
Default
file_id
none
Body keys (JSON)
Key
Required
Default
content_type
optional or conditional
none
data_b64
optional or conditional
none
name
optional 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
200data 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).
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
Name
Default
file_id
none
Body keys (JSON)
Key
Required
Default
base_version
optional or conditional
none
force
optional or conditional
none
model
optional or conditional
none
summary
optional 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.
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/
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)
Key
Required
Default
content_type
optional or conditional
none
file_size
optional or conditional
0
filename
optional or conditional
none
folder_id
optional or conditional
none
kind
optional or conditional
none
source_app
optional or conditional
none
source_context
optional or conditional
{}
storage_path
optional or conditional
none
title
optional 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.
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)
Key
Required
Default
file_ids
optional or conditional
none
folder_ids
optional or conditional
none
k
optional or conditional
none
q
optional or conditional
none
query
optional 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.
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)
Key
Required
Default
content_type
optional or conditional
none
filename
optional or conditional
none
path
optional 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
200non-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).
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)
Key
Required
Default
action
optional or conditional
none
enabled
optional or conditional
true
expires_at
optional or conditional
none
file_id
optional or conditional
none
folder_id
optional or conditional
none
principal_id
optional or conditional
none
principal_type
optional or conditional
none
role
optional or conditional
none
rotate
optional or conditional
none
share_id
optional 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.
``{"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)
Key
Required
Default
filename
optional or conditional
none
folder_id
optional or conditional
none
storage_path
optional or conditional
none
title
optional or conditional
none
upload_id
optional 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.
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)
Key
Required
Default
content_type
optional or conditional
none
file_size
optional or conditional
none
filename
optional 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.
``{"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)
Key
Required
Default
content_type
optional or conditional
none
file_size
optional or conditional
none
filename
optional or conditional
none
folder_id
optional 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.
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/
``{"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)
Key
Required
Default
action
optional or conditional
none
file_id
optional or conditional
none
id
optional or conditional
none
name
optional or conditional
none
number
optional 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.
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/
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
Name
Type
file_id
str
Body keys (JSON)
Key
Required
Default
actor_label
optional or conditional
none
agent_name
optional or conditional
none
base_version
optional or conditional
none
ops
optional 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.
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/
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/
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.