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

# Put a file

> Persist file bytes produced inside a Procedure sandbox via the unified files/bindings model. Same schema as the agent-side putFile tool.

> [!NOTE]
>
> This is a procedure-sandbox session endpoint, not a Forge Platform API v3 operation. The Procedure SDK calls this `/api/v1/proceduresApi/*` protocol with the invocation's session token.

`POST /api/v1/proceduresApi/putFile`

Sandbox-side counterpart to the [agent `putFile` tool](https://docs.gloo.com/forge/architecture/files-and-bindings#putfile-the-writer). A procedure POSTs to this endpoint to persist file bytes through the platform's `file_hosting` capability and create a `fileBindings` row in the appropriate domain. The body uses the same input schema as the agent tool.

## Authentication

Bearer session token, minted for one procedure invocation. A token whose scope does not include file hosting returns `403 CAPABILITY_DENIED`.

## Request body

The same discriminated `source × bind` shape as the agent tool — see [Files and Bindings · putFile](https://docs.gloo.com/forge/architecture/files-and-bindings.md#putfile-the-writer) for the full schema.

**source** `object` *required*

Discriminated by `kind`. Identifies where the bytes come from.

**source variants**

**kind** `"inline" | "render" | "sandbox" | "uploadUrl"` *required*

Selects the source variant. `inline` carries `content` in the request (`encoding` `utf8` or `base64`). `render` renders structured content server-side (`renderer` `table`, `document` or `workbook`, with its `args`). `sandbox` and `uploadUrl` read bytes already written inside the dispatch VM at `path`; `uploadUrl` uploads them directly and takes an optional `maxBytes`.

**path** `string`

Required when `kind` is `sandbox` or `uploadUrl`. Absolute path inside the VM.

**bind** `object` *required*

Discriminated by `kind`. Identifies the binding scope for the persisted file.

**bind variants**

**kind** `"workflow_output" | "run_scratch" | "worker_scope" | "chat_attachment"` *required*

Selects the binding scope. `workflow_output` takes `outputKey`. `run_scratch` takes no fields. `worker_scope` takes `scopeType` and an optional `scopeEntityId`. `chat_attachment` takes `channelId` and optional `sessionId` and `messageId`.

**filename** `string`

Display filename. Surfaces in the Console attachments UI and in downstream tool calls. When omitted, the name comes from the binding and the mime type, not the source path: the `outputKey` for `workflow_output`, otherwise `scratch`, `file` or `attachment`, plus the mime type's extension. Supply `filename` to keep the source name.

**mimeType** `string`

Mime type for downstream extractors (for example `application/pdf` or `text/csv`). Inferred when omitted.

```bash curl theme={null}
curl -X POST https://forge.example.com/api/v1/proceduresApi/putFile \
  -H "Authorization: Bearer $FORGE_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "kind": "sandbox", "path": "/work/out/report.pdf" },
    "bind": { "kind": "workflow_output", "outputKey": "report" },
    "filename": "report.pdf",
    "mimeType": "application/pdf"
  }'
```

```python Python theme={null}
import os, requests

resp = requests.post(
    f"{os.environ['FORGE_BASE_URL']}/api/v1/proceduresApi/putFile",
    headers={"Authorization": f"Bearer {os.environ['FORGE_SESSION_TOKEN']}"},
    json={
        "source": {"kind": "sandbox", "path": "/work/out/report.pdf"},
        "bind": {"kind": "workflow_output", "outputKey": "report"},
        "filename": "report.pdf",
        "mimeType": "application/pdf",
    },
)
resp.raise_for_status()
file_id = resp.json()["fileId"]
```

```typescript TypeScript theme={null}
const resp = await fetch(`${process.env.FORGE_BASE_URL}/api/v1/proceduresApi/putFile`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORGE_SESSION_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: { kind: "sandbox", path: "/work/out/report.pdf" },
    bind: { kind: "workflow_output", outputKey: "report" },
    filename: "report.pdf",
    mimeType: "application/pdf",
  }),
});
const { fileId } = await resp.json();
```

```json Body theme={null}
{
  "source": { "kind": "sandbox", "path": "/work/out/report.pdf" },
  "bind": { "kind": "workflow_output", "outputKey": "report" },
  "filename": "report.pdf",
  "mimeType": "application/pdf"
}
```

## Responses

**fileId** `string`

ID of the stored file. Use this `fileId` in downstream tool inputs and structured outputs.

> [accordion] 400 — INVALID\_INPUT
>
> Body fails validation. Check the `source` and `bind` shapes above.

> [accordion] 401 — AUTH\_FAILED
>
> Missing or invalid bearer session token.

> [accordion] 403 — CAPABILITY\_DENIED
>
> The session token's scope does not include file hosting. The body's `decisionId` names the Trust Fabric decision that recorded the refusal.

> [accordion] 404 — NOT\_FOUND
>
> The procedure version the session token names has no stored manifest.

> [accordion] 409 — SANDBOX\_UNAVAILABLE
>
> A `sandbox` source on a dispatch with no sandbox transport. Send the bytes as an `inline` source instead.

> [accordion] 413 — PAYLOAD\_TOO\_LARGE
>
> The request exceeds the platform's argument limit. Write the file in the VM and use a `sandbox` or `uploadUrl` source.

> [accordion] 500 — INTERNAL\_ERROR
>
> Upload or persistence failure. Details in the response `message`.

```json 200 theme={null}
{ "fileId": "k17abcdef0123" }
```

## Related

* [Files and Bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — the agent-side surface; the same `source` and `bind` schema
* [Procedures domain index](https://docs.gloo.com/forge/reference/http-api/procedures)


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