DEVELOPER DOCUMENTATION / API v1
Concurrency
Use exact task ETags and distinct Incoming revisions, handle 412 and 428, and reconcile workspace-wide planning changes.
Task If-Match #
A task ETag combines task identity with a workspace-wide planning version: "task-42-plan-7". Read the task’s ETag header and send that exact quoted string in If-Match on the write. Weak tags, wildcards and numeric formatting variants are not substitutes.
If-Match: "task-42-plan-7"A planning change elsewhere in the workspace can make a task ETag stale even if that particular task appears unchanged. This is intentional API v1 behaviour. Compare/reconcile the new state rather than merely obtaining a fresh tag and blindly repeating a decision.
428 and 412
428 precondition_required means the required If-Match is absent. 412 stale_update means it is malformed or no longer current. Re-read, inspect the current task or Incoming item, recompute the intended change, and use the current precondition. A successful write can invalidate the tag for the next write.
Incoming uses its own revision
An Incoming item carries an etag containing a quoted revision UUID. Use that value for /incoming/{id}/start, plan, reassign or complete. Do not use a task ETag for an Incoming action. For an assistance response evaluation, supply the Incoming revision in the JSON body and the originating task’s ETag in If-Match; those protect different state.
Do not interchange these values
| Value | Purpose | Where supplied |
|---|---|---|
| Task ETag | Task/workspace planning precondition | If-Match on task mutations |
| Incoming revision | Recipient request revision | Quoted If-Match for Incoming actions; revision body field for assistance evaluation |
| Claim token | Possession of a live execution lease | X-Task-Claim on protected writes; token body for renewal/release |
| Idempotency-Key | Identity of one retryable logical operation | Idempotency-Key request header |
Re-read, reconcile, then retry
When a response is lost, first follow the same-key receipt recovery rules. A successful receipt can replay before checking a now-stale planning version, but the precondition still must parse and authorization/ownership must remain current. If no successful receipt is recoverable, inspect existing work before issuing a new logical operation.
See claims, Incoming actions and stale-update recovery.