Permissions required
The key or app must hold the permission through its role grants, and its token or key scopes must include the matching scope. See Permissions and scopes.
Operations
Writes:POST /api/v3/files— upload a raw file; returns afileIdto pass as workflowruntimeArgs
GET /api/v3/files/{fileId}/content— redirect (302) to a bearer download URLPOST /api/v3/files/{fileId}/chat-attachment-content— the bytes of one of a chat channel’s attachments (see Chat attachments)
Uploading a file
fileId as a file-typed input in runtimeArgs when dispatching a workflow.
Request rules
- Raw bytes. The request body is the file itself: not JSON, not base64 and not multipart form data.
--data-binary @file.pdfsends it as is. - Size. The body must not be empty and may be at most 20,971,520 bytes (20 MiB). A larger body answers
413payload_too_large. AContent-Lengthabove the limit is refused before the body is read. - Headers.
Content-Typeis the file’s media type (defaultapplication/octet-stream) andX-Filenameits name (defaultupload.<ext>, the extension chosen from the media type). Either header, when sent, must be 1–255 characters with no control characters, or the request answers400bad_request(Invalid Content-TypeorInvalid X-Filename).
Retrying an upload
Send anIdempotency-Key with every upload. A retry with the same key and the same bytes never stores the file again. It returns the original 201 response, with Idempotency-Replayed: true, while the caller still holds files:write and still acts in the org tree the file was uploaded to; otherwise it answers 409 idempotency_result_unavailable. A retry does not need files:read. Headers are not part of the request’s identity: a retry with a different X-Filename or Content-Type returns the original result, name and type included. Different bytes under the same key answer 422 idempotency_key_reuse. See Idempotency.
Binding an upload to a scope
An upload can also be bound to a knowledge scope, the binding a Console upload makes. Name the scope in the query string:- Parameters.
scopeTypeis one ofpersonal,team,department,company,global,factory,project,direct,group,system,agent,external_apporcustomer.scopeEntityIdnames the scope’s org unit, factory or project (1–255 characters with no control characters).sourceis one ofchat_upload,sandbox_import,agent_output,legacy_documentorapi_uploadand defaults toapi_upload.scopeEntityIdandsourceneed ascopeType, and each parameter may appear once; anything else answers400bad_request. - Permission. A named scope also needs
files:writeat the scope’s home: the named org unit forteam,departmentandcompany, the factory’s or project’s home forfactoryandproject, and the deployment root for every other scope and for an org unit, factory or project that does not exist. Without it the request answers403and nothing is stored. - Bindings. The upload stays bound to the credential’s org unit, so it is downloadable and staged as an upload without a scope is. The scope binding is added beside it. A scope that names a top-level org unit or the deployment root also makes the file downloadable, and usable as a dispatch input, by credentials acting in that org tree, which is why the credential needs
files:writethere. WithoutscopeType, the upload is unchanged. - Retries. The query string is part of the request’s identity: a retry under the same key that names another scope answers
422idempotency_key_reuse.
Staging workflow inputs
A dispatch may reference exactly the uploads its credential could download throughGET /api/v3/files/{fileId}/content, under the same rule: the file is bound to the credential’s org tree (the org unit this upload is bound to) and the credential holds files:read at every company on the file. The dispatch itself then also needs files:read. Isolation is per org tree, not per uploader: any credential in the same org tree with files:read may reference a file uploaded by another. Any other reference answers 422 with Workflow input "<input>" is not an available file. See File inputs.
A staged file no run uses is inert. A run output cannot be passed as a dispatch input, even though you may download it: download it and upload it again.
Uploading through MCP
The Forge MCP server’sforge_upload_file tool (in the workflows tool group, needs files:write) uploads a file passed inline as base64 or text, up to 3 MiB, and returns the same result. It never reads a local path. See MCP server — Approvals job.
Downloading a file
The content endpoint accepts afileId (returned by an upload, or listed by GET /api/v3/runs/{runId}/artifacts) or the raw storage ID of an uploaded file.
302 with no body. Its Location is the download URL and its X-Request-Id the request’s ID.
Who can download a file
A credential holdingfiles:read may download exactly two kinds of file:
- Uploads in its org tree. A file uploaded through
POST /api/v3/filesis bound to the uploading credential’s org tree: an External App’s top-level org-unit ancestor, or the deployment root for a platform API key or a Personal key. Any credential acting in the same org tree may download it; isolation is per org tree, not per uploader. - Outputs of runs it may read. A file a workflow run produced is downloadable when the credential also holds
runs:read, at the run’s home (the run’s org unit, else its workflow’s home) and at every company on the run: the same rule under which it reads the run itself. Withoutruns:readthis kind is not considered.
files:read at every company on the file. Any other file, including a missing one, a chat attachment, or a file whose companies the credential may not read, answers 404 resource_missing “File not found”: the response never says whether the file exists.
Wire-shape change as of 2026-05-05 (Files-and-Bindings PR-8e): the
fileId returned by POST /api/v3/files is now an Id<"files"> rather than the legacy Id<"workerFiles">. The string format differs (different table prefix) and legacy IDs no longer resolve. SDK consumers on @tangogroup/forge-sdk@2.3.0 or later are aligned with the new shape; integrators consuming the REST surface directly should re-upload any in-flight files. See the 2026-05-05 changelog for the full migration notice.Auth boundary tightening as of 2026-05-06 (Files-and-Bindings hardening audit): the prior implementation of
/api/v3/files/{fileId}/content had a fallback that resolved raw _storage IDs without an org check. The fixed handler now reverse-resolves raw storage IDs to their canonical files row and runs the same worker_scope check before issuing a redirect. Legitimate same-org callers see no behavior change; cross-org callers and callers passing storage IDs that lack a files row receive 404.Chat attachments
POST /api/v3/files/{fileId}/chat-attachment-content with { "channelId": "<id>", "fileId": "<id>" } (and optionally orgUnitId) answers one file a chat channel carries, inline:
- Permission. The key needs
chat:readat the channel’s home. An External App is refused with403. - Hidden attachments. These answer
404, as a missing id does: a file the channel never attached; one posted in a restricted session the key did not start; one posted on a message whose companies the key may not read, as the transcript withholds it; one whose own companies the key may not read; and any attachment in a DM, group, personal or builder channel. A Personal key reads as its owner does in the Console: a group’s attachments, and a DM’s when its owner takes part in the DM (and a restricted session its owner started). A personal or builder channel stays hidden from every key. - No download URL. The route answers the bytes, never a URL: the Console’s signed attachment URL is a bearer capability and is not served to machine credentials.
- Size. A file of more than 4,000,000 bytes answers
409conflict; the content is never truncated. - Audit. The read is recorded before any byte is read, under the key (or a Personal key’s owner); a read that cannot be recorded is refused.
Workflow integration
Typical External App flow:- Upload input artifact → get
fileId - Dispatch workflow with the
fileIdin its file input, for exampleruntimeArgs: { report: "<fileId>" }→ getrunId - Poll
GET /api/v3/runs/{runId}untilstatus === "completed" - Extract
data.outputs.reportfrom the completed run - Download via
GET /api/v3/files/{fileId}/content
External App file isolation
External App file isolation is being re-implemented on top of the unified Files-and-Bindings model. As of 2026-05-05, the legacyprincipalExternalApplicationId index on workerFiles is no longer the source of truth — file ownership lineage now lives on fileBindings rows. App-deactivation purges are scheduled but currently no-op until app-isolation is wired onto the new schema. Track the follow-up at Files-and-Bindings unified model for status.
