DEVELOPER DOCUMENTATION / API v1

Discovering tasks

Find available and waiting tasks, inspect assigned work and understand source freshness, ordering and task detail responses.

Discover execution state

GET /api/v1/tasks/available offers unfinished owned work that is unblocked, without a live claim, and currently runnable under the scheduler. Unfinished zero-estimate work remains discoverable for reconciliation. Linked source facts are refreshed before candidates are offered; a source failure can omit that candidate.

GET /api/v1/tasks/waiting lists unfinished owned work with blocking reasons, such as unmet prerequisites, human assistance or external waiting. These endpoints are not generic status filters: Ready does not itself prove runnable work.

curl -i 'https://cyj.example/api/v1/tasks/waiting' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

Ownership, ordering and empty results

All three task reads require tasks:read and current assignment to the mapped resource. Other organisations’ task IDs are not found; a task assigned only to another resource is forbidden. Scopes never widen ownership.

Available/waiting lists order by project priority, project ID, sequence, then task ID. Empty collections are [], with no duplicate tasks. Lists have no pagination, no hard result cap and no silent truncation. They are assigned-worker views, not bulk schedule exports. Avoid excessive polling of large queues.

Inspect before executing

curl -i 'https://cyj.example/api/v1/tasks/42' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

GET /api/v1/tasks/42 returns task fields, project context/deadlines, assignments, dependencies, blocking reasons, factual effort, notes and authorised assistance/source information. Retain its ETag response header, for example "task-42-plan-7". The JSON etag field carries the same value. Lists use notes: []; detail reads provide notes. Assistance and reply content additionally require human-requests:read.

Complete fictional task response

Task detail · complete fictional representation · JSON response

{
  "id": 42,
  "title": "Prepare release notes",
  "description": "Summarise the Customer Portal changes.",
  "status": "Ready",
  "sequence": 1,
  "estimatedMinutes": 60,
  "remainingMinutes": 60,
  "actualMinutes": 0,
  "actualIntervals": [],
  "startedAt": null,
  "completedAt": null,
  "earliestStart": null,
  "isWaiting": false,
  "releaseDate": null,
  "resourceMode": "Independent",
  "project": {
    "id": 20,
    "name": "Customer Portal",
    "priority": 100,
    "priorityName": "normal",
    "targetDate": null,
    "hardDeadline": null,
    "deadlineReason": null,
    "isActive": true
  },
  "assignees": [
    {
      "staffMemberId": 7,
      "name": "Atlas",
      "remainingMinutes": 60,
      "estimatedMinutes": 60
    }
  ],
  "dependencies": [],
  "requiresAttention": false,
  "externalContext": [],
  "externalChanges": [],
  "sourceActivations": [],
  "responsesAwaitingEvaluation": [],
  "blocked": false,
  "blockingReasons": [],
  "humanRequests": [],
  "notes": [],
  "etag": "\u0022task-42-plan-7\u0022"
}

Important

A task detail read is context, not a lease. Claim the task and confirm usable expiry before active work. Source freshness and planning can change between discovery and claim.

Next read claims, external context and the task reference. Project priority and deadlines are returned as context; workers cannot edit project properties or assignments.