DEVELOPER DOCUMENTATION / API v1

External context

Read source facts and freshness, inspect changes and explicitly evaluate source events or human responses through API v1.

Business facts from linked work

A task may originate from or remain linked to an external work source. Task detail exposes public provider/item identity, typed title, description and business status, availability and the last successful source check. Source changes expose typed before/after facts and public event metadata. Activation snapshots retain business facts at activation time.

Read these facts through CYJ rather than treating provider-specific capabilities as a general task write-back API. A connector’s supported authored message operation does not imply generic forecast-date, assignment or status write-back. Read the integration overview for product boundaries.

Freshness before execution

CYJ checks required linked source context before offering available work and again at claim acquisition. A source outage can omit a candidate or return 503 source_unavailable with no claim created. A context race can return 409 source_context_changed or 412 stale_update. Cached detail can remain useful while fresh activation is unavailable.

Task requiresAttention, externalChanges, sourceActivations and authorised responsesAwaitingEvaluation help the worker decide what needs review. Assistance, reply events and awaiting-evaluation content require human-requests:read. A changed source or a human reply does not itself authorise a new external side effect.

Evaluate deliberately #

POST /api/v1/tasks/42/external-evaluation requires tasks:update, current task If-Match, a required Idempotency-Key and X-Task-Claim under a live task lease. Success is 204. Supply exactly one decision variant:

decision	Required contextual fields	Meaning
acknowledge	Positive eventId	Acknowledge a source event, such as event 501.
resolve	Positive incomingId, nonzero revision UUID	Resolve an owned responded assistance request and clear that blocker.
keepwaiting	Positive incomingId, nonzero revision UUID	Record evaluation while keeping the issue/blocker.
followup	incomingId, revision, nonblank message up to 5,000 characters	Ask a new question and reopen response interest.

Here event 501 belongs to task 42, while responded assistance Incoming 91 has assistance stage 73. Obtain the current response revision from authorised task/assistance detail. These decision bodies are alternatives, each using current state and a distinct logical key. Irrelevant fields, including explicitly null irrelevant fields, are rejected.

Acknowledge source event 501 · curl request

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/external-evaluation' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-acknowledge-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"decision":"acknowledge","eventId":501}'

Resolve responded assistance 91 · curl request

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/external-evaluation' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-resolve-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"decision":"resolve","incomingId":91,"revision":"11111111-1111-4111-8111-111111111111"}'

Keep the assistance blocker · curl request

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/external-evaluation' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-keepwaiting-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"decision":"keepwaiting","incomingId":91,"revision":"11111111-1111-4111-8111-111111111111"}'

Ask a follow-up question · curl request

curl -i -X POST 'https://cyj.example/api/v1/tasks/42/external-evaluation' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "task-42-plan-7"' \
  -H 'Idempotency-Key: example-followup-001' \
  -H 'X-Task-Claim: 22222222-2222-4222-8222-222222222222' \
  -H 'Content-Type: application/json' \
  --data-raw '{"decision":"followup","incomingId":91,"revision":"11111111-1111-4111-8111-111111111111","message":"Should the summary mention the migration?"}'

Important

A reply records a response; it does not automatically resolve the human blocker. Resolve only when the response is sufficient. Followup preserves durable history while the current request awaits a new response.

See human assistance, task and Incoming revisions, safe retries and the evaluation reference.