Incoming work

Work routed to a recipient

Incoming work is a request routed to a resource before it is committed to that recipient’s capacity. Floating work has no reserved allocation. A suggested start is advice, not acceptance. The mapped worker can read and act only on its own Incoming requests.

curl -i 'https://cyj.example/api/v1/incoming?includeAccepted=true' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

GET /api/v1/incoming requires tasks:read and returns floating work by default. includeAccepted=true also returns owned planned, inprogress and completed requests, enabling later completion of accepted work. Results are unpaginated, ordered by priority, requestedAtUtc, then ID; an empty result is [].

{
  "id": 92,
  "title": "Review release summary",
  "details": null,
  "estimatedMinutes": 15,
  "priority": "normal",
  "requester": "Alice Morgan",
  "requestedAtUtc": "2026-10-19T09:00:00Z",
  "status": "floating",
  "suggestedStart": null,
  "suggestionReason": "No suggestion available",
  "plannedStart": null,
  "response": null,
  "responseState": "open",
  "actualStartUtc": null,
  "actualEffortMinutes": null,
  "etag": "\u002211111111-1111-4111-8111-111111111111\u0022"
}

Use the Incoming revision

Each action requires tasks:update, the item’s quoted revision etag in If-Match and a required Idempotency-Key. This is not the task ETag and does not use a task claim. Re-read the queue after a successful action for the next current revision. Missing preconditions are 428; malformed/stale ones are 412.

Choose one action

All paths use the /api/v1 prefix; all successful actions return 204 without a body. Irrelevant fields are rejected: a start request cannot silently carry a plannedStart or reassignment. Domain/lifecycle conflicts remain 409.

One coherent planned lifecycle

Alice routes fictional Incoming 92, “Review release summary”, to Atlas. Atlas reads the floating request and chooses to plan it for 14:00. The suggestedStart may be null and did not reserve capacity. Planning does not create factual actual start/effort.

curl -i -X POST 'https://cyj.example/api/v1/incoming/92/plan' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "11111111-1111-4111-8111-111111111111"' \
  -H 'Idempotency-Key: example-plan-001' \
  -H 'Content-Type: application/json' \
  --data-raw '{"plannedStart":"2026-10-19T14:00:00"}'

Later, Atlas reads /incoming?includeAccepted=true, obtains the new etag, and completes that same Incoming 92 with the known outcome. Replace the illustrated initial revision below with the current one; use a new key for completion.

curl -i -X POST 'https://cyj.example/api/v1/incoming/92/complete' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "11111111-1111-4111-8111-111111111111"' \
  -H 'Idempotency-Key: example-complete-001' \
  -H 'Content-Type: application/json' \
  --data-raw '{"response":"Summary checked and approved."}'

Alternative choices while floating

Starting now and reassignment are alternatives to planning this request, not additional actions to send blindly after the lifecycle above.

curl -i -X POST 'https://cyj.example/api/v1/incoming/92/start' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "11111111-1111-4111-8111-111111111111"' \
  -H 'Idempotency-Key: example-start-001' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

curl -i -X POST 'https://cyj.example/api/v1/incoming/92/reassign' \
  -H "Authorization: Bearer $CYJ_API_TOKEN" \
  -H 'If-Match: "11111111-1111-4111-8111-111111111111"' \
  -H 'Idempotency-Key: example-reassign-001' \
  -H 'Content-Type: application/json' \
  --data-raw '{"assigneeId":9}'

See concurrency, planning time, safe retries and assistance-stage versus Incoming identity.