Skip to main content
POST
Attach an output file to a human step
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Hands a file back to a waiting human workflow step: it becomes the next version of one of the step’s declared file or file[] outputs, optionally linked to the step input file it came back from (the run then compares the two workbooks). Earlier versions are kept.
  1. Upload the file with POST /api/v2/files using one of the owner’s Personal keys, and keep its fileId.
  2. Attach it here with the step’s node run id (id), the output’s fieldName, the fileId, and parentFileId when it is an edited copy of one of the step’s input files.
  3. Complete the step with Complete a human task, naming the file id in its output.
Only a file the key’s owner uploaded (with one of their Personal keys, or in the Forge Console) can be attached; any other fileId is 404.

Who may attach

The owner must be asked by the step, or hold approvals:approve at the platform through a key whose scopes reach it — the same rule as List a step’s input files. The key’s scopes must also reach approvals:approve. A platform key or an External App gets 403 with error.personRequired: true. A repeat without an Idempotency-Key attaches another version. See Deciding through the API.

Example

The answer is { fileId, humanTaskId, version }. The MCP tool forge_attach_human_task_output_file takes the same fields and an optional idempotencyKey.

Authorizations

Authorization
string
header
required

A Personal key (fmcp_…), bound to the person who created it, or an interactive MCP sign-in that resolves to one. Pass as Authorization: Bearer <key>. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json

Attach a file the key's owner uploaded as the next version of one of a human step's declared file outputs, optionally linked to the input file it came back from.

id
string
required

The human step's node run id.

Minimum string length: 1
fieldName
string
required

A file or file[] output the step declares.

Minimum string length: 1
fileId
string
required

The fileId of a file the key's owner uploaded, with POST /api/v2/files and their Personal key or in the Console.

Minimum string length: 1
parentFileId
string

The step input file this one came back from (one of its input files).

Minimum string length: 1

Response

Attach an output file to a human step

data
object
required

The attached file, the step's human task, and the output's new version (each attach is the next version; the earlier ones are kept).

meta
object
required