DEVELOPER DOCUMENTATION / API v1
Core concepts
Understand API clients, worker resources, tasks, claims, Incoming work and human assistance in Can You Just API v1.
Identity and ownership
- Organisation
- The workspace boundary containing people, projects and API clients.
- API client
- The authenticated software identity used to call CYJ.
- Credential
- A revocable Bearer secret that authenticates a client; a client may have overlapping credentials during rotation.
- Worker resource
- The CYJ scheduling resource represented by a mapped client. Atlas is the fictional worker in these examples.
- Scope
- A permission for an operation family, independent of ownership and assignment.
- Credential authenticates client
- Client may represent resource
- Resource owns assigned tasks
Work in the plan
| Term | Meaning in API v1 |
|---|---|
| Project | A grouping of planned work, with human-managed priority and deadlines. |
| Task / stage | An assigned unit of project work. API task IDs identify CYJ stages. |
| Assignment | The relationship between a task and a resource; it determines worker ownership. |
| Dependency | A prerequisite that must actually complete before dependent execution becomes eligible. |
| Available task | Unfinished, unblocked, unclaimed owned work eligible under the current scheduler; zero-estimate reconciliation remains discoverable. |
| Waiting task | Unfinished owned work with blocking reasons, not a generic status filter. |
| Claim | A temporary 15-minute UTC execution lease; it neither starts a task nor changes permanent assignment. |
| Actual effort | Factual recorded intervals, distinct from estimates or elapsed forecast time. |
| Note | An appended progress explanation, separate from the task description. |
Handoffs and source context
A human assistance request asks an active human a question or requests a review, approval or action for an owned task. New requests enter Incoming work as floating requests: suggestions do not reserve capacity. A recipient may accept/start, plan, reassign or complete Incoming work. A worker can itself be an Incoming recipient.
An external source is linked business work maintained outside CYJ. External context provides safe public facts about that work. Source freshness means checking the relevant source before offering or activating externally linked work. CYJ retains local planning control; a connector’s message capability is not generic date/status write-back.
Four different coordination values
A task ETag identifies a task plus the workspace planning version. An Incoming revision identifies the current request revision. A claim token proves possession of a live execution lease. An Idempotency-Key identifies a retryable logical operation for a successful 24-hour receipt. None substitutes for the others.
Continue with tasks, human assistance, Incoming work and the coordination comparison.