Skip to main content
POST
Reassign 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

Reassigns a human workflow step or a pending approval to the people assignee resolves to, as the Personal key’s owner, and records reason on the audit trail. Only people who could act on the task are kept; reassigning it to the owner alone is the Console’s Take over. Name the item by the kind and id of a task’s reassignRef from Get a human task: a step’s node run id (human_node), an approval id (approval), or a review queue’s group task id (human_task). A group task (human_task) is not reassigned: its only assignee is the owner alone, { "type": "user", "userId": <owner> }, which takes over its claim (Take over). The owner must be someone the task asks and hold approvals:approve at the platform scope; any other assignee is 409. assignee is one of: Factory-scoped targets (factoryRole, factoryMember) are refused with 400: no work item carries a factory to bind them to.

Who may reassign

The owner needs approvals:approve at the task’s home, through a key whose scopes reach it, and the task’s kind must be reassignable. A platform key or an External App gets 403 with error.personRequired: true. An item that is not open, or that the owner may not see, is 404. A repeat without an Idempotency-Key reassigns again and writes another audit event. See Deciding through the API.

Example

The answer is { humanTaskId, kind, id }. The MCP tool forge_reassign_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

Body

application/json

Reassign one work item to the people assignee resolves to. Factory-scoped targets (factoryRole, factoryMember) are refused with 400.

kind
enum<string>
required

What id names: a human step, a pending approval, or a review queue's group task (human_task: Take over only).

Available options:
human_node,
approval,
human_task
id
string
required

Its id: a node run id (human_node), an approval id (approval) or a group task id (human_task), from reassignRef.

Minimum string length: 1
assignee
object
required

Who the task should ask instead.

reason
string
required

Why it is being reassigned; recorded on the audit trail.

Minimum string length: 1

Response

Reassign a human task

data
object
required

The reassigned work item and its human task.

meta
object
required