Claim next work item

Atomically reserves the highest-priority claimable work item in one project under a time-bound lease, so two concurrent agents are never handed the same item. The candidate pool is not_started and ready items only — never blocked — ordered critical, high, medium, low, then oldest first. A claim is a transient agent reservation, not an assignment: it never sets or clears assignee_user_id. An expired lease is automatically reclaimable, so a crashed agent’s item returns to the pool without operator intervention. This endpoint is deliberately NOT idempotent — two claims should return two different items, so an Idempotency-Key here would be a bug.

POST/api/v1/work-items/claim

Authorization

work-items:assignapi key scoperequired

Required scope when calling with an API key.

Request body

project_idstringrequired

Project whose queue is dequeued

claim_ownerstringrequired

Agent or session identifier holding the lease, 200 characters or fewer

lease_secondsnumberoptional

Lease duration in seconds; defaults to 900, maximum 3600

Example request

{
  "project_id": "proj_01k2...",
  "claim_owner": "agent-7f3c",
  "lease_seconds": 900
}

Request

POST /api/v1/work-items/claim

curl -X POST "https://www.digitalstack360.com/api/v1/work-items/claim" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"proj_01k2...","claim_owner":"agent-7f3c","lease_seconds":900}'

Examples use a placeholder key from your environment. Store your key in $DS_API_KEY — never commit it.

Response

200 OK

{
  "data": {
    "claimed": {
      "id": "work_01k2...",
      "key": "4210",
      "title": "Implement board projection API",
      "status": "ready",
      "priority": "high",
      "projectId": "proj_01k2...",
      "claimOwner": "agent-7f3c",
      "claimedAt": "2026-07-28T09:12:04Z",
      "claimExpiresAt": "2026-07-28T09:27:04Z"
    }
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

403

scope_insufficient

Key lacks work-items:assign scope

400

invalid_request

project_id or claim_owner is missing, claim_owner exceeds 200 characters, or lease_seconds is not a positive number of 3600 or fewer

404

not_found

Project does not exist, or is outside the key account — the two are deliberately indistinguishable so the response cannot be used to discover other tenants’ project IDs