Skip to main content
POST
Complete a human task
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

Answers one human task with one of its form’s declared actions (form.actions[].id from Get a human task), as the Personal key’s owner: approve or reject a Trust Fabric hold, respond to a workflow step, mark agent setup done, or confirm an Architect plan or a synthesis batch. output holds the form’s field values and is checked against the form; reason is required by an action that declares it. It is the Forge Console’s own completion. A hold’s decision runs the hold’s release rule and its approval policy’s approver limits in the same transaction, exactly as in the Console, and the approval records resolvedVia: "api". The first decision wins: a second one is 409.

How a Personal key is judged

Every check is made on the owner’s grants narrowed to the key’s scopes. A hold whose release rule requires, say, tools:read as well as approvals:approve is refused for a key whose scopes do not reach tools:read, even though the owner holds it through a role. An approval policy’s limits apply as they do in the Console: under approverMustDifferFromRequester the person who asked is refused, and the 403 message names the policy and the limit; a Personal key counts as its owner, a person, under approverMustBePerson. An action that needs a signed-in Forge Console session is 403, and the message gives the task’s Console link. A hold that sends outside Forge (external delivery) is approved only in the Forge Console, so its approve is that 403; its reject is taken. A platform key or an External App gets 403 with error.personRequired: true. A task the owner may not see is 404, and nothing is written. See Deciding through the API.

Example

The answer is { "data": { "outcome": "completed", "humanTaskId": "hir_456", "action": "approve" }, "meta": { "requestId": "…" } }. The MCP tool forge_complete_human_task 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

Path Parameters

humanTaskId
string
required

The human task's id (humanTaskId).

Minimum string length: 1

Body

application/json

Answer one human task with one of its form's declared actions; output holds the form's field values and is checked against the form.

action
string
required

One of the task form's declared action ids (form.actions[].id).

Minimum string length: 1
output
object

The form's field values, checked against the task's form.

reason
string

Why; required by an action that declares it.

Minimum string length: 1

Response

Complete a human task

data
object
required

How the task closed: completed by the action, declined, or canceled (withdrawn).

meta
object
required