Human assistance

When the worker should ask

Atlas has prepared release notes for Customer Portal but should not approve its own publication. A human assistance request asks Alice Morgan to approve the summary before Atlas continues. Assistance kinds are Question, Review, Approval and Action.

Create the request

POST /api/v1/tasks/42/human-requests requires human-requests:create, current task If-Match and X-Task-Claim when leased. A retry key is optional and recommended. Choose an active human in the same organisation, provide a nonblank title (up to 200), optional details (up to 20,000), and estimatedMinutes (1–1,000,000).

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/human-requests' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-ask-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"humanAssigneeId":9,"title":"Approve release summary","details":"Check that the summary is ready to publish.","estimatedMinutes":15,"priority":"normal","assistanceKind":"Approval","isBlocking":true,"publishExternally":false}'

Named priority is critical/high/normal/low, default normal. assistanceKind defaults to Question; isBlocking and publishExternally default true. This example explicitly requests Approval, blocks the origin, and disables external publication. A non-blocking request can collect input without pausing the task.

{
  "id": 73,
  "originatingTaskId": 42
}

Read the response and lifecycle

curl -i 'https://cyj.example/api/v1/human-requests/73' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

GET /api/v1/human-requests/73 requires human-requests:read and continued ownership of the originating task. Detail includes the human assignee, request/response, estimate, lifecycle, priorityName, responseState, assistanceKind, incomingRevision and nullable actual metadata.

{
  "stageId": 73,
  "requestedForStageId": 42,
  "incomingId": 91,
  "requestedByApiClientId": 12,
  "requestedByStaffMemberId": 7,
  "assignedHumanId": 9,
  "assignedHumanName": "Alice Morgan",
  "requestedByName": "Atlas",
  "originTitle": "Prepare release notes",
  "title": "Approve release summary",
  "details": "Check that the summary is ready to publish.",
  "estimatedMinutes": 15,
  "remainingMinutes": 15,
  "status": "Ready",
  "isBlocking": true,
  "isOutstandingBlocker": true,
  "response": null,
  "createdUtc": "2026-10-19T09:00:00Z",
  "completedUtc": null,
  "lifecycle": "floating",
  "priorityName": "normal",
  "responseState": "open",
  "actualStartUtc": null,
  "actualEffortMinutes": null,
  "incomingRevision": "11111111-1111-4111-8111-111111111111",
  "respondedAtUtc": null,
  "assistanceKind": "Approval"
}

Floating work and explicit evaluation

New assistance enters the shared floating Incoming lifecycle; it reserves no recipient capacity until accepted. Multiple blocking requests can pause one originating task. Completing one removes only its blocker. Unknown actual start/effort stays null, and completing a request does not infer actual work.

Supported external publication uses the existing configured authoring policy and may be delayed while the local request remains valid. A source reply is responded, not automatically resolved. Inspect authorised responses awaiting evaluation and explicitly resolve, keep waiting or follow up using external evaluation. Completing the last blocker makes the task eligible subject to its other prerequisites and waiting rules.

CYJ does not wake or execute the worker. Poll responsibly. See scopes, Incoming recipient actions and assistance reference.