> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload raw files and download your uploads and the outputs of runs you may read.

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](#who-can-download-a-file)).

## Permissions required

| Operation | Permission | Scope that narrows to it |
| - | - | - |
| Upload (`POST /api/v3/files`) | `files:write` | `files:write` |
| Download (`GET /api/v3/files/{fileId}/content`) | `files:read` | `files:read` |

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](https://docs.gloo.com/forge/reference/conventions.md#permissions-and-scopes).

> [!WARNING]
>
> 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](#chat-attachments))

## Uploading a file

```bash theme={null}
curl -X POST https://api.forge.gloo.com/api/v3/files \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: text/markdown" \
  -H "X-Filename: metadata.md" \
  --data "# Org Metadata..."
```

Response:

```json theme={null}
{
  "data": {
    "fileId": "k8203czrpfkmma2n...",
    "fileRef": { "provider": "internal", "externalId": "k8203czrpfkmma2n..." },
    "filename": "metadata.md",
    "sizeBytes": 1024,
    "mimeType": "text/markdown"
  }
}
```

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](https://docs.gloo.com/forge/reference/idempotency.md#upload-replay).

### 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:

```bash theme={null}
curl -X POST "https://api.forge.gloo.com/api/v3/files?scopeType=team&scopeEntityId=<orgUnitId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: plan.pdf" \
  --data-binary @plan.pdf
```

* **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](https://docs.gloo.com/forge/reference/http-api/workflows/dispatch.md#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](https://docs.gloo.com/forge/reference/mcp-server.md#approvals-job).

## Downloading a file

The content endpoint accepts a `fileId` (returned by an upload, or listed by [`GET /api/v3/runs/{runId}/artifacts`](https://docs.gloo.com/forge/reference/http-api/runs)) or the raw storage ID of an uploaded file.

```bash theme={null}
# Follow the redirect to download content
curl -L "https://api.forge.gloo.com/api/v3/files/<id>/content" \
  -H "Authorization: Bearer <token>"
```

The endpoint answers a `302` with no body. Its `Location` is the download URL and its `X-Request-Id` the request's ID.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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](https://docs.gloo.com/forge/changelog/entries/2026-05-05.md) for the full migration notice.

> [!NOTE]
>
> **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:

```json theme={null}
{
  "data": {
    "fileId": "files:...",
    "filename": "plan.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 1024,
    "contentBase64": "JVBERi0xLjcg..."
  }
}
```

* **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](https://docs.gloo.com/forge/reference/http-api/workflows) and [Runs](https://docs.gloo.com/forge/reference/http-api/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](https://docs.gloo.com/forge/changelog/entries/2026-05-05.md) for status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.