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

# Get a file

> Read a file the dispatch has access to from inside a Procedure sandbox. Four modes: text, bytes, stream, sandbox.

> [!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/getFile`

Sandbox-side counterpart to the [agent `getFile` tool](https://docs.gloo.com/forge/architecture/files-and-bindings#getfile-the-reader). A procedure POSTs to this endpoint to read a `fileId` that was threaded onto its dispatch as an input. The Procedure SDKs (`get_file` in Python, `getFile` in Node) call it for you.

## Authentication

Bearer session token. A procedure may read only the `fileId`s passed to its invocation as inputs and the files it wrote itself. An attempt to read any other `fileId` returns `403 CAPABILITY_DENIED`.

## Request body

**fileId** `string` *required*

Must be one of this invocation's input `fileId`s, or a file it wrote. Any other `fileId` returns `403 CAPABILITY_DENIED`.

**mode** `"text" | "bytes" | "stream" | "sandbox"` *required*

`text` extracts content by mime type (UTF-8 text, PDF, XLSX, DOCX, PPTX). `bytes` returns the raw file as base64. `stream` returns the same payload as `bytes`. `sandbox` writes the file into the calling procedure's own VM at `destPath` and returns only its path and size; it is the only mode for files over 10 MB.

**destPath** `string`

Required when `mode = "sandbox"`. Absolute path inside the VM where the bytes are written. Ignored by the other modes.

```json text mode theme={null}
{ "fileId": "k17abcdef0123", "mode": "text" }
```

```json bytes mode theme={null}
{ "fileId": "k17abcdef0123", "mode": "bytes" }
```

```json sandbox mode theme={null}
{ "fileId": "k17abcdef0123", "mode": "sandbox", "destPath": "/work/in/source.csv" }
```

## Responses

The body is a JSON object whose shape depends on the requested `mode`.

**fileId** `string`

The requested `fileId`. Returned in all modes.

**mimeType** `string`

The file's mime type. Returned in all modes.

**content** `string`

Returned for `mode = "text"`. Extracted content based on the file's mime type.

**truncated** `boolean`

Returned for `mode = "text"` only when the extracted content exceeded 10 MB and was cut, with `truncatedAtBytes`. A structured type (JSON, CSV, NDJSON) is never cut: it answers `413 PAYLOAD_TOO_LARGE` instead.

**contentBase64** `string`

Returned for `mode = "bytes"` and `mode = "stream"`. The raw file, base64-encoded.

**path** `string`

Returned for `mode = "sandbox"`. The path written inside the VM.

**bytes** `number`

Returned for `mode = "sandbox"`. Byte length written.

> [accordion] 400 — INVALID\_INPUT
>
> Body fails validation. Common causes: a missing `fileId`, an unknown `mode`, or `mode: "sandbox"` without a `destPath`.

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

> [accordion] 403 — CAPABILITY\_DENIED
>
> The requested `fileId` is not one of this invocation's inputs or its own writes. The body's `decisionId` names the Trust Fabric decision that recorded the refusal.

> [accordion] 404 — NOT\_FOUND
>
> The `fileId` does not resolve to a `files` row. Either deleted or never persisted.

> [accordion] 413 — PAYLOAD\_TOO\_LARGE
>
> A `bytes` or `stream` read of a file over 10 MB, or a `text` read of a structured type whose content exceeds 10 MB. Use `mode: "sandbox"` with a `destPath`.

> [accordion] 502 — SCHEMA\_MISMATCH
>
> `mode: "text"` against a binary type the extractor does not read. Request `mode: "bytes"` and decode the payload inside the procedure.

```json 200 (text) theme={null}
{ "fileId": "k17abcdef0123", "mimeType": "text/csv", "content": "id,name\n1,Acme\n" }
```

```json 200 (bytes) theme={null}
{ "fileId": "k17abcdef0123", "mimeType": "text/csv", "contentBase64": "aWQsbmFtZQoxLEFjbWUK" }
```

```json 200 (sandbox) theme={null}
{ "fileId": "k17abcdef0123", "mimeType": "text/csv", "path": "/work/in/source.csv", "bytes": 482 }
```

```json 403 theme={null}
{ "error": "CAPABILITY_DENIED", "message": "fileId \"k17other\" is not readable by this procedure invocation. Allowed: k17abcdef0123", "decisionId": "k57decision0123" }
```

## Related

* [Files and Bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) — the agent-side surface
* [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.