Skip to main content
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. 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 fileIds 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

string
required
Must be one of this invocation’s input fileIds, or a file it wrote. Any other fileId returns 403 CAPABILITY_DENIED.
"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.
string
Required when mode = "sandbox". Absolute path inside the VM where the bytes are written. Ignored by the other modes.

Responses

The body is a JSON object whose shape depends on the requested mode.
string
The requested fileId. Returned in all modes.
string
The file’s mime type. Returned in all modes.
string
Returned for mode = "text". Extracted content based on the file’s mime type.
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.
string
Returned for mode = "bytes" and mode = "stream". The raw file, base64-encoded.
string
Returned for mode = "sandbox". The path written inside the VM.
number
Returned for mode = "sandbox". Byte length written.
Body fails validation. Common causes: a missing fileId, an unknown mode, or mode: "sandbox" without a destPath.
Missing or invalid bearer session token.
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.
The fileId does not resolve to a files row. Either deleted or never persisted.
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.
mode: "text" against a binary type the extractor does not read. Request mode: "bytes" and decode the payload inside the procedure.