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/putFile Sandbox-side counterpart to the agent putFile tool. 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 for the full schema.
object
required
Discriminated by kind. Identifies where the bytes come from.
object
required
Discriminated by kind. Identifies the binding scope for the persisted file.
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.
string
Mime type for downstream extractors (for example application/pdf or text/csv). Inferred when omitted.

Responses

string
ID of the stored file. Use this fileId in downstream tool inputs and structured outputs.
Body fails validation. Check the source and bind shapes above.
Missing or invalid bearer session token.
The session token’s scope does not include file hosting. The body’s decisionId names the Trust Fabric decision that recorded the refusal.
The procedure version the session token names has no stored manifest.
A sandbox source on a dispatch with no sandbox transport. Send the bytes as an inline source instead.
The request exceeds the platform’s argument limit. Write the file in the VM and use a sandbox or uploadUrl source.
Upload or persistence failure. Details in the response message.