Skip to main content
POST
Claim, release, decline or withdraw 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

Does what the Forge Console My Work actions do to one human task, as the Personal key’s owner: The answer is { humanTaskId, verb, outcome }, where outcome is claimed, released, declined or withdrawn.

Who may act

Only the owner’s own place on the task decides: someone the task asks may claim, release or decline it, and the person who asked may withdraw it. The route therefore declares no role permission, but the key’s scopes must reach approvals:approve; otherwise the call is 403 naming approvals:approve. 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 MCP tool forge_act_on_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

Claim, release, decline or withdraw one human task. reason is required to decline (otherwise 400 "reason is required to decline").

verb
enum<string>
required

claim or release an exclusive claim, decline (not mine, with a reason) or withdraw a task you asked.

Available options:
claim,
release,
decline,
withdraw
reason
string

Why; required to decline.

Minimum string length: 1

Response

Claim, release, decline or withdraw a human task

data
object
required

What the verb did: claimed, released, declined or withdrawn. A claim of your own claim, or a release of an unclaimed task, changes nothing and still answers its outcome.

meta
object
required