{"openapi":"3.0.3","info":{"title":"Can You Just Assigned-worker API","version":"1.0","description":"Assigned-resource operations only. HTTPS Bearer credentials belong in server-side/agent secret storage, never browser bundles. No general CORS or worker OAuth grant. Planning dates are London wall time; *Utc values are UTC instants. Task ETags use a workspace version; Incoming uses a distinct revision. Current ownership/scope authorisation applies to writes and replays. External side effects are not guaranteed exactly-once."},"servers":[{"url":"/api/v1"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Identity"},{"name":"Tasks"},{"name":"Claims"},{"name":"Assistance"},{"name":"Incoming"}],"paths":{"/identity":{"get":{"operationId":"getAgentIdentity","tags":["Identity"],"summary":"getAgentIdentity","description":"Authenticated identity inspection. resource is null for an identity-only client. Administrator-managed rotation/revocation; no automatic expiry. Active sponsor, organisation and mapped agent checks apply.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"},"example":{"clientId":1,"clientName":"Fictional example","organisation":{"id":1,"name":"Fictional example"},"resource":null,"scopes":[]}}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}}},"/tasks/available":{"get":{"operationId":"getAvailableWork","tags":["Tasks"],"summary":"getAvailableWork","description":"Required scope: tasks:read. Owned, unfinished, unblocked, unclaimed work with a current scheduler allocation (or zero-estimate reconciliation). Linked sources are refreshed before offering work. Unpaginated, ordered by project priority, project ID, sequence, task ID. Empty is []; no duplicate tasks. Notes in lists are []. Assigned-worker use only, not bulk reporting.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"example":[{"id":1,"title":"Fictional example","description":null,"status":"Ready","sequence":1,"estimatedMinutes":1,"remainingMinutes":1,"actualMinutes":1,"actualIntervals":[],"startedAt":null,"completedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","project":{"id":1,"name":"Fictional example","priority":0,"priorityName":"critical","targetDate":null,"hardDeadline":null,"deadlineReason":null,"isActive":true},"assignees":[],"dependencies":[],"requiresAttention":true,"externalContext":[],"externalChanges":[],"sourceActivations":[],"responsesAwaitingEvaluation":[],"blocked":true,"blockingReasons":[],"humanRequests":[],"notes":[],"etag":"\"task-1-plan-1\""}]}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}}},"/tasks/waiting":{"get":{"operationId":"getWaitingWork","tags":["Tasks"],"summary":"getWaitingWork","description":"Required scope: tasks:read. Owned blocked unfinished work; poll for responses requiring evaluation. Unpaginated, ordered by project priority, project ID, sequence, task ID. Empty is []; no duplicate tasks. Notes in lists are []. Assigned-worker use only, not bulk reporting.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"example":[{"id":1,"title":"Fictional example","description":null,"status":"Ready","sequence":1,"estimatedMinutes":1,"remainingMinutes":1,"actualMinutes":1,"actualIntervals":[],"startedAt":null,"completedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","project":{"id":1,"name":"Fictional example","priority":0,"priorityName":"critical","targetDate":null,"hardDeadline":null,"deadlineReason":null,"isActive":true},"assignees":[],"dependencies":[],"requiresAttention":true,"externalContext":[],"externalChanges":[],"sourceActivations":[],"responsesAwaitingEvaluation":[],"blocked":true,"blockingReasons":[],"humanRequests":[],"notes":[],"etag":"\"task-1-plan-1\""}]}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}}},"/tasks/{id}":{"get":{"operationId":"getAgentTask","tags":["Tasks"],"summary":"getAgentTask","description":"Required scope: tasks:read. Owned task. Assistance/reply data needs human-requests:read; tasks:read includes readable notes, tasks:notes permits appending. Only explicit source business facts are exposed, never connection/claim correlations or raw provider metadata.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"example":{"id":1,"title":"Fictional example","description":null,"status":"Ready","sequence":1,"estimatedMinutes":1,"remainingMinutes":1,"actualMinutes":1,"actualIntervals":[],"startedAt":null,"completedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","project":{"id":1,"name":"Fictional example","priority":0,"priorityName":"critical","targetDate":null,"hardDeadline":null,"deadlineReason":null,"isActive":true},"assignees":[],"dependencies":[],"requiresAttention":true,"externalContext":[],"externalChanges":[],"sourceActivations":[],"responsesAwaitingEvaluation":[],"blocked":true,"blockingReasons":[],"humanRequests":[],"notes":[],"etag":"\"task-1-plan-1\""}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Quoted task-{id}-plan-{workspaceVersion}; use as If-Match."}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}},"patch":{"operationId":"updateAgentTask","tags":["Tasks"],"summary":"updateAgentTask","description":"Required scope: tasks:update. Omission preserves fields; null clears optional fields. Project and assignment changes are forbidden. actualIntervals additionally requires tasks:time. Estimated Duration is total planned duration, not independent remaining.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"204":{"description":"Success, no response body.","headers":{"Warning":{"schema":{"type":"string"},"description":"299 CanYouJust when remainingMinutes compatibility input is used."}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskPatch"},"example":{"title":"Fictional example","description":null,"status":"Ready","sequence":0,"estimatedMinutes":0,"remainingMinutes":0,"startedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","dependencyIds":[],"actualIntervals":[]}}}}}},"/tasks/{id}/actual-effort":{"put":{"operationId":"replaceActualEffort","tags":["Tasks"],"summary":"replaceActualEffort","description":"Required scope: tasks:time. Replace own factual intervals, never increment. Other contributors' actuals cannot be changed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActualEffort"},"example":{"actualIntervals":[]}}}}}},"/tasks/{id}/notes":{"post":{"operationId":"addProgressNote","tags":["Tasks"],"summary":"addProgressNote","description":"Required scope: tasks:notes. Append a note without replacing description.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteCreate"},"example":{"text":"Fictional example"}}}}}},"/tasks/{id}/claim":{"post":{"operationId":"acquireTaskClaim","tags":["Claims"],"summary":"acquireTaskClaim","description":"Required scope: tasks:update. Acquire a 15-minute UTC lease for runnable work; does not mark InProgress. Source failure creates no claim. Replay returns the original lease, which may since have expired; inspect expiresUtc before execution.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"},"example":{"token":"11111111-1111-4111-8111-111111111111","expiresUtc":"2026-10-19T09:00:00Z"}}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyRequest"},"example":{}}}}}},"/tasks/{id}/claim/renew":{"post":{"operationId":"renewTaskClaim","tags":["Claims"],"summary":"renewTaskClaim","description":"Required scope: tasks:update. Renew an unexpired matching lease by 15 minutes. Missing/null/zero/malformed token is 400; unknown/expired/wrong lease is 409.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"},"example":{"token":"11111111-1111-4111-8111-111111111111","expiresUtc":"2026-10-19T09:00:00Z"}}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"},"example":{"token":"11111111-1111-4111-8111-111111111111"}}}}}},"/tasks/{id}/claim/release":{"post":{"operationId":"releaseTaskClaim","tags":["Claims"],"summary":"releaseTaskClaim","description":"Required scope: tasks:update. Terminate the matching lease. releasedUtc is termination time, not a future expiry; no token is returned. Keyed replay returns the original outcome.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRelease"},"example":{"released":true,"releasedUtc":"2026-10-19T09:00:00Z"}}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"},"example":{"token":"11111111-1111-4111-8111-111111111111"}}}}}},"/tasks/{id}/human-requests":{"post":{"operationId":"createHumanAssistance","tags":["Assistance"],"summary":"createHumanAssistance","description":"Required scope: human-requests:create. Create floating Incoming for an active human, with no capacity until acceptance. Returned id/Location identify the assistance stage; read incomingId from detail for Incoming actions. Source publishing uses existing sponsor credentials and may be delayed while the local request remains valid.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedRequest"},"example":{"id":1,"originatingTaskId":1}}},"headers":{"Location":{"schema":{"type":"string"},"description":"/api/v1/human-requests/{assistanceStageId}"}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistanceCreate"},"example":{"humanAssigneeId":1,"title":"Fictional example","details":null,"estimatedMinutes":1,"priority":"critical","isBlocking":true,"assistanceKind":"Question","publishExternally":true}}}}}},"/human-requests/{id}":{"get":{"operationId":"getHumanAssistance","tags":["Assistance"],"summary":"getHumanAssistance","description":"Required scope: human-requests:read. Assistance originating from work still owned by the resource. Stage ID and Incoming ID are distinct.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Assistance-stage ID returned by creation, not incomingId."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanRequest"},"example":{"stageId":1,"requestedForStageId":1,"incomingId":null,"requestedByApiClientId":1,"requestedByStaffMemberId":1,"assignedHumanId":1,"assignedHumanName":"Fictional example","requestedByName":"Fictional example","originTitle":"Fictional example","title":"Fictional example","details":null,"estimatedMinutes":1,"remainingMinutes":1,"status":"Ready","isBlocking":true,"isOutstandingBlocker":true,"response":null,"createdUtc":"2026-10-19T09:00:00Z","completedUtc":null,"lifecycle":"floating","priorityName":null,"responseState":"open","actualStartUtc":null,"actualEffortMinutes":null,"incomingRevision":null,"respondedAtUtc":null,"assistanceKind":"Question"}}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}}},"/tasks/{id}/external-evaluation":{"post":{"operationId":"evaluateExternalContext","tags":["Assistance"],"summary":"evaluateExternalContext","description":"Required scope: tasks:update. Use exactly one decision variant. acknowledge targets a source event; resolve/keepwaiting/followup target an owned responded Incoming revision. A reply alone does not resolve a blocker; followup requires a new question.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Owned CYJ stage/task ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Exact quoted task-{id}-plan-{workspaceVersion} ETag. Unrelated planning edits may invalidate it. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."},{"name":"X-Task-Claim","in":"header","required":false,"schema":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"description":"Required for mutations under a live task lease. Never reuse expired tokens. Acquisition requires no previous lease; renewal/release use body token."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalEvaluation"},"example":{"decision":"acknowledge","eventId":1}}}}}},"/incoming":{"get":{"operationId":"getIncomingRequests","tags":["Incoming"],"summary":"getIncomingRequests","description":"Required scope: tasks:read. Mapped recipient only; floating by default, all lifecycle states when includeAccepted=true. Ordered by priority, requestedAtUtc, ID. Unpaginated; empty is []; suggestions may be null and reserve no capacity.","parameters":[{"name":"includeAccepted","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Incoming"}},"example":[{"id":1,"title":"Fictional example","details":null,"estimatedMinutes":1,"priority":"critical","requester":"Fictional example","requestedAtUtc":"2026-10-19T09:00:00Z","status":"floating","suggestedStart":null,"suggestionReason":null,"plannedStart":null,"response":null,"responseState":"open","actualStartUtc":null,"actualEffortMinutes":null,"etag":"\"11111111-1111-4111-8111-111111111111\""}]}}},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}}}},"/incoming/{id}/start":{"post":{"operationId":"incomingstart","tags":["Incoming"],"summary":"incomingstart","description":"Required scope: tasks:update. Commit/start now. No request fields or inferred actual effort.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Incoming ID; distinct from assistance-stage ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted Incoming revision UUID. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyRequest"},"example":{}}}}}},"/incoming/{id}/plan":{"post":{"operationId":"incomingplan","tags":["Incoming"],"summary":"incomingplan","description":"Required scope: tasks:update. Commit at explicit plannedStart without creating actuals.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Incoming ID; distinct from assistance-stage ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted Incoming revision UUID. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingPlan"},"example":{"plannedStart":"2026-10-19T10:00:00"}}}}}},"/incoming/{id}/reassign":{"post":{"operationId":"incomingreassign","tags":["Incoming"],"summary":"incomingreassign","description":"Required scope: tasks:update. Reassign floating work to assigneeId.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Incoming ID; distinct from assistance-stage ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted Incoming revision UUID. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingReassign"},"example":{"assigneeId":1}}}}}},"/incoming/{id}/complete":{"post":{"operationId":"incomingcomplete","tags":["Incoming"],"summary":"incomingcomplete","description":"Required scope: tasks:update. Record an optional response/outcome without inferring actual start/effort.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Incoming ID; distinct from assistance-stage ID."},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"Quoted Incoming revision UUID. Missing is 428; malformed/stale is 412."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-zA-Z0-9._:-]+$"},"description":"24-hour successful receipt scoped to organisation/client/key. Object property order is ignored recursively; arrays, scalar types and meaningful strings are preserved. Equivalent retry needs current authorisation and a parseable If-Match. Changed operations/bodies with the same key return 409."}],"responses":{"204":{"description":"Success, no response body."},"400":{"description":"validation_failed: JSON shape, binding, duplicate, required field or typed contract validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":400,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"401":{"description":"authentication_failed: missing/invalid/revoked credential or inactive sponsor/organisation/resource.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":401,"code":"authentication_failed","traceId":"fictional-request-trace"}}},"headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer"}}},"403":{"description":"permission_denied or task_not_owned: scope or assignment denial.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":403,"code":"permission_denied","traceId":"fictional-request-trace"}}}},"404":{"description":"route_not_found, task_not_found, request_not_found or incoming_not_found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":404,"code":"route_not_found","traceId":"fictional-request-trace"}}}},"405":{"description":"method_not_allowed: unsupported HTTP method; Allow lists supported methods.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":405,"code":"method_not_allowed","traceId":"fictional-request-trace"}}},"headers":{"Allow":{"schema":{"type":"string"}}}},"409":{"description":"Business conflict: task_blocked, task_completed, task_not_runnable, request_completed, dependency_conflict, idempotency_conflict, task_claimed, claim_expired, incoming_state_conflict or source_context_changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":409,"code":"task_blocked","traceId":"fictional-request-trace"}}}},"412":{"description":"stale_update: malformed/stale task ETag or Incoming revision.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":412,"code":"stale_update","traceId":"fictional-request-trace"}}}},"413":{"description":"request_too_large: maximum JSON body is 131072 bytes.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":413,"code":"request_too_large","traceId":"fictional-request-trace"}}}},"415":{"description":"unsupported_media_type: use application/json (or application/*+json).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":415,"code":"unsupported_media_type","traceId":"fictional-request-trace"}}}},"422":{"description":"validation_failed, invalid_field, human_assignee_invalid or idempotency_key_required: valid JSON violates task/domain fields or retry-key constraints.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":422,"code":"validation_failed","traceId":"fictional-request-trace"}}}},"428":{"description":"precondition_required: If-Match is missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":428,"code":"precondition_required","traceId":"fictional-request-trace"}}}},"429":{"description":"rate_limited: process-local fixed-window protection, currently 120 requests/client/minute, no queue. This is not a commercial SLA.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":429,"code":"rate_limited","traceId":"fictional-request-trace"}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Conservative whole seconds from limiter metadata; fallback 60 seconds."}}},"500":{"description":"internal_error: sanitized failure, traceId only; no internal diagnostics.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":500,"code":"internal_error","traceId":"fictional-request-trace"}}}},"503":{"description":"source_unavailable or temporarily_unavailable: retry later or select other work.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"The request could not be completed.","status":503,"code":"source_unavailable","traceId":"fictional-request-trace"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingComplete"},"example":{"response":null}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Administrator-issued CYJ credential, displayed once. Client scopes and active sponsor/organisation/agent checks apply."}},"schemas":{"Identity":{"type":"object","additionalProperties":false,"properties":{"clientId":{"type":"integer","format":"int32"},"clientName":{"type":"string"},"organisation":{"$ref":"#/components/schemas/NamedEntity"},"resource":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string"}},"required":["id","name"],"nullable":true},"scopes":{"type":"array","items":{"type":"string"}}},"required":["clientId","clientName","organisation","resource","scopes"],"example":{"clientId":1,"clientName":"Fictional example","organisation":{"id":1,"name":"Fictional example"},"resource":null,"scopes":[]}},"NamedEntity":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string"}},"required":["id","name"],"example":{"id":1,"name":"Fictional example"}},"Task":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Ready","InProgress","Done"]},"sequence":{"type":"integer","format":"int32"},"estimatedMinutes":{"type":"integer","format":"int32"},"remainingMinutes":{"type":"integer","format":"int32"},"actualMinutes":{"type":"number"},"actualIntervals":{"type":"array","items":{"$ref":"#/components/schemas/ActualInterval"}},"startedAt":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"completedAt":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"earliestStart":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"isWaiting":{"type":"boolean"},"releaseDate":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"resourceMode":{"type":"string","enum":["Independent","Collaboration"]},"project":{"$ref":"#/components/schemas/Project"},"assignees":{"type":"array","items":{"$ref":"#/components/schemas/Assignment"}},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/Dependency"}},"requiresAttention":{"type":"boolean"},"externalContext":{"type":"array","items":{"$ref":"#/components/schemas/SourceContext"}},"externalChanges":{"type":"array","items":{"$ref":"#/components/schemas/SourceChange"}},"sourceActivations":{"type":"array","items":{"$ref":"#/components/schemas/SourceActivation"}},"responsesAwaitingEvaluation":{"type":"array","items":{"$ref":"#/components/schemas/AwaitingEvaluation"}},"blocked":{"type":"boolean"},"blockingReasons":{"type":"array","items":{"type":"string"}},"humanRequests":{"type":"array","items":{"$ref":"#/components/schemas/HumanRequest"}},"notes":{"type":"array","items":{"$ref":"#/components/schemas/Note"}},"etag":{"type":"string","example":"\"task-1-plan-1\""}},"required":["id","title","description","status","sequence","estimatedMinutes","remainingMinutes","actualMinutes","actualIntervals","startedAt","completedAt","earliestStart","isWaiting","releaseDate","resourceMode","project","assignees","dependencies","requiresAttention","externalContext","externalChanges","sourceActivations","responsesAwaitingEvaluation","blocked","blockingReasons","humanRequests","notes","etag"],"example":{"id":1,"title":"Fictional example","description":null,"status":"Ready","sequence":1,"estimatedMinutes":1,"remainingMinutes":1,"actualMinutes":1,"actualIntervals":[],"startedAt":null,"completedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","project":{"id":1,"name":"Fictional example","priority":0,"priorityName":"critical","targetDate":null,"hardDeadline":null,"deadlineReason":null,"isActive":true},"assignees":[],"dependencies":[],"requiresAttention":true,"externalContext":[],"externalChanges":[],"sourceActivations":[],"responsesAwaitingEvaluation":[],"blocked":true,"blockingReasons":[],"humanRequests":[],"notes":[],"etag":"\"task-1-plan-1\""}},"Project":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string"},"priority":{"type":"integer","format":"int32","deprecated":true,"enum":[0,50,100,101],"description":"Deprecated read-only numeric compatibility value. Prefer priorityName.","readOnly":true},"priorityName":{"type":"string","enum":["critical","high","normal","low"],"readOnly":true},"targetDate":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"hardDeadline":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"deadlineReason":{"type":"string","nullable":true},"isActive":{"type":"boolean"}},"required":["id","name","priority","priorityName","targetDate","hardDeadline","deadlineReason","isActive"],"example":{"id":1,"name":"Fictional example","priority":0,"priorityName":"critical","targetDate":null,"hardDeadline":null,"deadlineReason":null,"isActive":true}},"Assignment":{"type":"object","additionalProperties":false,"properties":{"staffMemberId":{"type":"integer","format":"int32"},"name":{"type":"string"},"remainingMinutes":{"type":"integer","format":"int32","nullable":true},"estimatedMinutes":{"type":"integer","format":"int32","nullable":true}},"required":["staffMemberId","name","remainingMinutes","estimatedMinutes"],"example":{"staffMemberId":1,"name":"Fictional example","remainingMinutes":null,"estimatedMinutes":null}},"Dependency":{"type":"object","additionalProperties":false,"properties":{"taskId":{"type":"integer","format":"int32"},"status":{"type":"string","enum":["Ready","InProgress","Done"]}},"required":["taskId","status"],"example":{"taskId":1,"status":"Ready"}},"ActualInterval":{"type":"object","additionalProperties":false,"properties":{"staffMemberId":{"type":"integer","format":"int32"},"start":{"type":"string","format":"local-date-time","nullable":false,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"end":{"type":"string","format":"local-date-time","nullable":false,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."}},"required":["staffMemberId","start","end"],"example":{"staffMemberId":1,"start":"2026-10-19T10:00:00","end":"2026-10-19T10:00:00"}},"Note":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int64"},"text":{"type":"string"},"createdUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"clientName":{"type":"string"},"staffName":{"type":"string"}},"required":["id","text","createdUtc","clientName","staffName"],"example":{"id":1,"text":"Fictional example","createdUtc":"2026-10-19T09:00:00Z","clientName":"Fictional example","staffName":"Fictional example"}},"HumanRequest":{"type":"object","additionalProperties":false,"properties":{"stageId":{"type":"integer","format":"int32","description":"Assistance-stage ID, used by /human-requests/{id}; not incomingId."},"requestedForStageId":{"type":"integer","format":"int32"},"incomingId":{"type":"integer","format":"int32","nullable":true,"description":"Distinct Incoming ID used by /incoming/{id}/...; null for legacy assistance."},"requestedByApiClientId":{"type":"integer","format":"int32"},"requestedByStaffMemberId":{"type":"integer","format":"int32"},"assignedHumanId":{"type":"integer","format":"int32"},"assignedHumanName":{"type":"string"},"requestedByName":{"type":"string"},"originTitle":{"type":"string"},"title":{"type":"string"},"details":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","format":"int32"},"remainingMinutes":{"type":"integer","format":"int32"},"status":{"type":"string","enum":["Ready","InProgress","Done"]},"isBlocking":{"type":"boolean"},"isOutstandingBlocker":{"type":"boolean"},"response":{"type":"string","nullable":true},"createdUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"completedUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"lifecycle":{"type":"string","enum":["floating","planned","inprogress","completed"]},"priorityName":{"type":"string","enum":["critical","high","normal","low"],"nullable":true},"responseState":{"type":"string","enum":["open","responded","resolved"]},"actualStartUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"actualEffortMinutes":{"type":"integer","format":"int32","nullable":true},"incomingRevision":{"type":"string","format":"uuid","nullable":true},"respondedAtUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"assistanceKind":{"type":"string","enum":["Question","Review","Approval","Action"]}},"required":["stageId","requestedForStageId","incomingId","requestedByApiClientId","requestedByStaffMemberId","assignedHumanId","assignedHumanName","requestedByName","originTitle","title","details","estimatedMinutes","remainingMinutes","status","isBlocking","isOutstandingBlocker","response","createdUtc","completedUtc","lifecycle","priorityName","responseState","actualStartUtc","actualEffortMinutes","incomingRevision","respondedAtUtc","assistanceKind"],"example":{"stageId":1,"requestedForStageId":1,"incomingId":null,"requestedByApiClientId":1,"requestedByStaffMemberId":1,"assignedHumanId":1,"assignedHumanName":"Fictional example","requestedByName":"Fictional example","originTitle":"Fictional example","title":"Fictional example","details":null,"estimatedMinutes":1,"remainingMinutes":1,"status":"Ready","isBlocking":true,"isOutstandingBlocker":true,"response":null,"createdUtc":"2026-10-19T09:00:00Z","completedUtc":null,"lifecycle":"floating","priorityName":null,"responseState":"open","actualStartUtc":null,"actualEffortMinutes":null,"incomingRevision":null,"respondedAtUtc":null,"assistanceKind":"Question"}},"SourceFacts":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"businessStatus":{"type":"string","nullable":true}},"required":["title","description","businessStatus"],"example":{"title":"Fictional example","description":null,"businessStatus":null}},"SourceContext":{"type":"object","additionalProperties":false,"properties":{"providerKey":{"type":"string"},"itemId":{"type":"string"},"facts":{"$ref":"#/components/schemas/SourceFacts"},"lastSuccessUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"isAvailable":{"type":"boolean"}},"required":["providerKey","itemId","facts","lastSuccessUtc","isAvailable"],"example":{"providerKey":"Fictional example","itemId":"Fictional example","facts":{"title":"Fictional example","description":null,"businessStatus":null},"lastSuccessUtc":null,"isAvailable":true}},"SourceChange":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int64"},"incomingId":{"type":"integer","format":"int32","nullable":true},"kind":{"type":"string","enum":["source","reply"]},"before":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"businessStatus":{"type":"string","nullable":true}},"required":["title","description","businessStatus"],"nullable":true},"after":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"businessStatus":{"type":"string","nullable":true}},"required":["title","description","businessStatus"],"nullable":true},"response":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"occurredUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"receivedUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"acknowledgedUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true}},"required":["id","incomingId","kind","before","after","response","author","occurredUtc","receivedUtc","acknowledgedUtc"],"example":{"id":1,"incomingId":null,"kind":"source","before":null,"after":null,"response":null,"author":null,"occurredUtc":"2026-10-19T09:00:00Z","receivedUtc":"2026-10-19T09:00:00Z","acknowledgedUtc":null}},"SourceActivation":{"type":"object","additionalProperties":false,"properties":{"activatedUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceFacts"}}},"required":["activatedUtc","sources"],"example":{"activatedUtc":"2026-10-19T09:00:00Z","sources":[]}},"AwaitingEvaluation":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"assistanceStageId":{"type":"integer","format":"int32","nullable":true},"assistanceKind":{"type":"string","enum":["Question","Review","Approval","Action"]},"response":{"type":"string","nullable":true},"respondedAtUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"revision":{"type":"string","format":"uuid"}},"required":["id","assistanceStageId","assistanceKind","response","respondedAtUtc","revision"],"example":{"id":1,"assistanceStageId":null,"assistanceKind":"Question","response":null,"respondedAtUtc":null,"revision":"11111111-1111-4111-8111-111111111111"}},"Incoming":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"title":{"type":"string"},"details":{"type":"string","nullable":true},"estimatedMinutes":{"type":"integer","format":"int32"},"priority":{"type":"string","enum":["critical","high","normal","low"]},"requester":{"type":"string"},"requestedAtUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."},"status":{"type":"string","enum":["floating","planned","inprogress","completed"]},"suggestedStart":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"suggestionReason":{"type":"string","nullable":true},"plannedStart":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"response":{"type":"string","nullable":true},"responseState":{"type":"string","enum":["open","responded","resolved"]},"actualStartUtc":{"type":"string","format":"date-time","description":"UTC instant with Z.","nullable":true},"actualEffortMinutes":{"type":"integer","format":"int32","nullable":true},"etag":{"type":"string","example":"\"11111111-1111-4111-8111-111111111111\""}},"required":["id","title","details","estimatedMinutes","priority","requester","requestedAtUtc","status","suggestedStart","suggestionReason","plannedStart","response","responseState","actualStartUtc","actualEffortMinutes","etag"],"example":{"id":1,"title":"Fictional example","details":null,"estimatedMinutes":1,"priority":"critical","requester":"Fictional example","requestedAtUtc":"2026-10-19T09:00:00Z","status":"floating","suggestedStart":null,"suggestionReason":null,"plannedStart":null,"response":null,"responseState":"open","actualStartUtc":null,"actualEffortMinutes":null,"etag":"\"11111111-1111-4111-8111-111111111111\""}},"Claim":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","format":"uuid"},"expiresUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."}},"required":["token","expiresUtc"],"example":{"token":"11111111-1111-4111-8111-111111111111","expiresUtc":"2026-10-19T09:00:00Z"}},"ClaimRelease":{"type":"object","additionalProperties":false,"properties":{"released":{"type":"boolean"},"releasedUtc":{"type":"string","format":"date-time","description":"UTC instant with Z."}},"required":["released","releasedUtc"],"example":{"released":true,"releasedUtc":"2026-10-19T09:00:00Z"}},"CreatedRequest":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"integer","format":"int32"},"originatingTaskId":{"type":"integer","format":"int32"}},"required":["id","originatingTaskId"],"example":{"id":1,"originatingTaskId":1}},"Error":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["about:blank"]},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"code":{"type":"string"},"traceId":{"type":"string"}},"required":["type","title","status","code","traceId"],"example":{"type":"about:blank","title":"Fictional example","status":400,"code":"Fictional example","traceId":"Fictional example"}},"EmptyRequest":{"type":"object","additionalProperties":false,"properties":{},"example":{}},"ClaimRequest":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"}},"required":["token"],"example":{"token":"11111111-1111-4111-8111-111111111111"}},"ActualIntervalInput":{"type":"object","additionalProperties":false,"properties":{"staffMemberId":{"type":"integer","minimum":1},"start":{"type":"string","format":"local-date-time","nullable":false,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"end":{"type":"string","format":"local-date-time","nullable":false,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."}},"required":["staffMemberId","start","end"],"example":{"staffMemberId":1,"start":"2026-10-19T10:00:00","end":"2026-10-19T10:00:00"}},"TaskPatch":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":20000,"nullable":true},"status":{"type":"string","enum":["Ready","InProgress","Done"]},"sequence":{"type":"integer","minimum":0,"maximum":100000},"estimatedMinutes":{"type":"integer","minimum":0,"maximum":1000000},"remainingMinutes":{"type":"integer","minimum":0,"maximum":1000000,"deprecated":true,"description":"Compatibility: elapsed planned duration plus remainingMinutes becomes estimatedMinutes. estimatedMinutes wins when both are supplied. Response remaining is calculated; Warning 299 accompanies this input."},"startedAt":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"earliestStart":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"isWaiting":{"type":"boolean"},"releaseDate":{"type":"string","format":"local-date-time","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."},"resourceMode":{"type":"string","enum":["Independent","Collaboration"]},"dependencyIds":{"type":"array","items":{"type":"integer","minimum":1},"maxItems":1000},"actualIntervals":{"type":"array","items":{"$ref":"#/components/schemas/ActualIntervalInput"},"maxItems":1000}},"example":{"title":"Fictional example","description":null,"status":"Ready","sequence":0,"estimatedMinutes":0,"remainingMinutes":0,"startedAt":null,"earliestStart":null,"isWaiting":true,"releaseDate":null,"resourceMode":"Independent","dependencyIds":[],"actualIntervals":[]}},"ActualEffort":{"type":"object","additionalProperties":false,"properties":{"actualIntervals":{"type":"array","items":{"$ref":"#/components/schemas/ActualIntervalInput"},"maxItems":1000}},"required":["actualIntervals"],"example":{"actualIntervals":[]}},"NoteCreate":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["text"],"example":{"text":"Fictional example"}},"AssistanceCreate":{"type":"object","additionalProperties":false,"properties":{"humanAssigneeId":{"type":"integer","minimum":1},"title":{"type":"string","minLength":1,"maxLength":200},"details":{"type":"string","maxLength":20000,"nullable":true},"estimatedMinutes":{"type":"integer","minimum":1,"maximum":1000000},"priority":{"type":"string","enum":["critical","high","normal","low"],"default":"normal"},"isBlocking":{"type":"boolean","default":true},"assistanceKind":{"type":"string","enum":["Question","Review","Approval","Action"],"default":"Question"},"publishExternally":{"type":"boolean","default":true}},"required":["humanAssigneeId","title","estimatedMinutes"],"example":{"humanAssigneeId":1,"title":"Fictional example","details":null,"estimatedMinutes":1,"priority":"critical","isBlocking":true,"assistanceKind":"Question","publishExternally":true}},"IncomingPlan":{"type":"object","additionalProperties":false,"properties":{"plannedStart":{"type":"string","format":"local-date-time","nullable":false,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,7})?(?:Z|[+-]\\d{2}:\\d{2})?$","description":"Europe/London planning wall time. Output has no offset. Input may also use an offset/Z instant, converted to London. Nonexistent spring wall times are rejected; ambiguous bare autumn times remain wall times without identifying an instant."}},"required":["plannedStart"],"example":{"plannedStart":"2026-10-19T10:00:00"}},"IncomingReassign":{"type":"object","additionalProperties":false,"properties":{"assigneeId":{"type":"integer","minimum":1}},"required":["assigneeId"],"example":{"assigneeId":1}},"IncomingComplete":{"type":"object","additionalProperties":false,"properties":{"response":{"type":"string","maxLength":20000,"nullable":true}},"example":{"response":null}},"ExternalEvaluation":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"decision":{"type":"string","enum":["acknowledge"]},"eventId":{"type":"integer","format":"int64","minimum":1}},"required":["decision","eventId"]},{"type":"object","additionalProperties":false,"properties":{"decision":{"type":"string","enum":["resolve"]},"incomingId":{"type":"integer","minimum":1},"revision":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"}},"required":["decision","incomingId","revision"]},{"type":"object","additionalProperties":false,"properties":{"decision":{"type":"string","enum":["keepwaiting"]},"incomingId":{"type":"integer","minimum":1},"revision":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"}},"required":["decision","incomingId","revision"]},{"type":"object","additionalProperties":false,"properties":{"decision":{"type":"string","enum":["followup"]},"incomingId":{"type":"integer","minimum":1},"revision":{"type":"string","format":"uuid","pattern":"^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"message":{"type":"string","minLength":1,"maxLength":5000}},"required":["decision","incomingId","revision","message"]}],"example":{"decision":"acknowledge","eventId":1}}}}}