Skip to main content
The Files domain lets a platform credential upload input artifacts before dispatching a workflow and download output files after a run completes. Uploads are bound to the credential’s org tree; run outputs follow the run’s readability (see Who can download a file).

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.
The inference file routes (/api/inference/v1/files, /files/confirm, /files/get, /files/delete) are a different door: they require inference:use. A token that carries only files:read or files:write receives 403 there.

Operations

Writes:
  • POST /api/v3/files — upload a raw file; returns a fileId to pass as workflow runtimeArgs
Reads:
  • GET /api/v3/files/{fileId}/content — redirect (302) to a bearer download URL
  • POST /api/v3/files/{fileId}/chat-attachment-content — the bytes of one of a chat channel’s attachments (see Chat attachments)

Uploading a file

Response:
Pass the 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.pdf sends 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 413 payload_too_large. A Content-Length above the limit is refused before the body is read.
  • Headers. Content-Type is the file’s media type (default application/octet-stream) and X-Filename its name (default upload.<ext>, the extension chosen from the media type). Either header, when sent, must be 1–255 characters with no control characters, or the request answers 400 bad_request (Invalid Content-Type or Invalid X-Filename).

Retrying an upload

Send an Idempotency-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. scopeType is one of personal, team, department, company, global, factory, project, direct, group, system, agent, external_app or customer. scopeEntityId names the scope’s org unit, factory or project (1–255 characters with no control characters). source is one of chat_upload, sandbox_import, agent_output, legacy_document or api_upload and defaults to api_upload. scopeEntityId and source need a scopeType, and each parameter may appear once; anything else answers 400 bad_request.
  • Permission. A named scope also needs files:write at the scope’s home: the named org unit for team, department and company, the factory’s or project’s home for factory and project, and the deployment root for every other scope and for an org unit, factory or project that does not exist. Without it the request answers 403 and 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:write there. Without scopeType, 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 422 idempotency_key_reuse.

Staging workflow inputs

A dispatch may reference exactly the uploads its credential could download through GET /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’s forge_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 a fileId (returned by an upload, or listed by GET /api/v3/runs/{runId}/artifacts) or the raw storage ID of an uploaded file.
The endpoint answers a 302 with no body. Its Location is the download URL and its X-Request-Id the request’s ID.
The download URL is a bearer URL. Whoever holds it can download the file, without any credential, and it is not tied to the credential that asked for it. With the internal file-hosting provider it does not expire, and removing the caller’s grants does not revoke it. Fetch it promptly and do not log or share it.

Who can download a file

A credential holding files:read may download exactly two kinds of file:
  1. Uploads in its org tree. A file uploaded through POST /api/v3/files is 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.
  2. 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. Without runs:read this kind is not considered.
Either way, the credential needs 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:read at the channel’s home. An External App is refused with 403.
  • 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 409 conflict; 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:
  1. Upload input artifact → get fileId
  2. Dispatch workflow with the fileId in its file input, for example runtimeArgs: { report: "<fileId>" } → get runId
  3. Poll GET /api/v3/runs/{runId} until status === "completed"
  4. Extract data.outputs.report from the completed run
  5. Download via GET /api/v3/files/{fileId}/content
See Workflows and Runs for dispatch and polling details.

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 legacy principalExternalApplicationId 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.