Agent resources and credentials
Administrators open Settings → Agents & API. Create a client, select an existing agent resource (or explicitly confirm a seven-day full-day resource as an agent), choose permissions, then generate a credential. Agents have continuous 24-hour availability, including weekends and organisation closures. Human calendars continue to apply normally. See Agents & API administration for one-time copying, revocation and overlapping rotation.
Create a credential mapped to that agent and select its permissions. Copy the secret once and keep it in the client's secret store. Credentials use Bearer authentication over HTTPS. Revoke them from the same page. A credential also becomes unusable if its creating administrator's membership or the mapped agent becomes inactive. An unmapped credential can only inspect its identity.
Human assistance
Agents can create ordinary human stages linked to their assigned task. CYJ schedules these using human working hours; the agent cannot choose a timeline position. Blocking is the default; multiple requests can block one task. Non-blocking requests do not pause it.
Open a request's stage editor to see who requested it and the originating task. Save the response in the dedicated response field, then complete the stage normally, recording actual work as usual. The originating stage shows linked requests and responses. It becomes eligible to resume after all blocking requests complete, subject to its existing dependencies, calendar and external waiting rules.
API use
The API uses /api/v1. Its OpenAPI document is at /api/v1/openapi.json. Read the task first, then send its ETag in If-Match when updating it, adding notes or requesting assistance. A stale update returns 412; read the task again before retrying. Assignment changes require a human planner. Agents can change their own actual work intervals and editable stage fields, but cannot change project ownership, project-level deadlines/priority, identities, integration mappings or audit fields.
Available work includes only currently scheduled runnable work. Waiting work is listed separately. No background process wakes or invokes an agent in this release.
Claim work before running a worker
GET /api/v1/identity confirms reachability, authentication, client, organisation, resource and scopes; no separate health endpoint is needed. Available work is scheduler-runnable owned work without an active claim. An unfinished stage whose estimate reached zero remains discoverable so its completion or corrected estimate can be reconciled.
Two workers using the same client should claim a selected task before executing it. POST /api/v1/tasks/{id}/claim with the task's If-Match and a unique Idempotency-Key. Exactly one worker receives a claim token and UTC expiry; others receive a conflict. Claiming reserves execution for 15 minutes and does not itself mark work In Progress. Use the existing task PATCH to start/update progress when appropriate.
While claimed, send X-Task-Claim with notes, actual work, assistance and task updates. POST the token to /api/v1/tasks/{id}/claim/renew before expiry, using a new logical request key and current ETag. Release it through /claim/release when stopping. Completing the task with its token releases the claim in the same transaction. Do not share claim tokens between concurrent workers.
A crash, reboot or lost network cannot hold a claim forever: its lease expires and work becomes claimable again. Expired worker tokens cannot mutate it. Fetch the task again and reconcile existing notes, requests, actual work and the remaining estimate before resuming; lease expiry does not undo recorded work or prove that an external action did not run. In Progress still follows CYJ's existing elapsed-progress rules. Use the same retry key to recover a lost claim response; never use a new key to blindly repeat external side effects.
Safe retries
All Agent API writes accept Idempotency-Key. Claim acquire/renew/release require it. Use a fresh random request identifier for each logical operation, keep its body unchanged, and reuse both if the HTTP response is lost. Within 24 hours CYJ returns the original successful result before checking the now-stale planning version. Keys belong to a client and organisation; reusing one for a different operation/body is rejected. Failed transactions leave no successful receipt. Revocation, scope and ownership checks still run on replay.
Without a retry key, existing If-Match protection remains: retrying the original ETag fails after a successful scheduling mutation. Re-read and reconcile rather than blindly retrying an append with a fresh ETag. Actual effort is a replacement of factual intervals, not an increment. PATCH remains a field assignment; retry receipts also avoid repeated completion/history effects. Receipts are retained for 24 hours and expired records are cleared on that client's next keyed write.