Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

Axis provides two tools for taking ownership of a job. claim_next_job is the load-balanced entry point — a worker agent calls it when it’s ready for whatever comes next, and the server hands out the highest-priority unblocked job atomically. claim_job is for planned multi-agent runs where the work has already been divided and each agent claims its intended task by ID. Both paths guarantee that two agents racing for the same job cannot both win: the server uses SELECT ... FOR UPDATE SKIP LOCKED inside the claim transaction, making double-claiming structurally impossible.

​
claim_next_job

claim_next_job is the standard worker entry point. Call it when your agent is ready for work and doesn’t have a specific job in mind. The server evaluates the full queue — filtered to unblocked, unclaimed jobs for the project — sorts by priority (then FIFO within priority), and atomically assigns the top result to the caller.

​
Parameters

​
agentId
string
The identity of the agent claiming the job. Defaults to the session’s unique identity when omitted. Appears in list_jobs output as claimedBy and in lock denial messages so other agents know who has the work.
​
projectName
string
Defaults to the auto-detected project. Override only when targeting a specific project explicitly.

​
Return Value

On success: 
{
  "status": "CLAIMED",
  "job": {
    "jobId": "j_abc123",
    "title": "Add JWT auth to /api/auth route",
    "description": "Replace session cookie with JWT. Update src/auth.ts..."
  }
}
When the queue is empty (all jobs are done, cancelled, or claimed by others): 
NO_JOBS_AVAILABLE
NO_JOBS_AVAILABLE is the completion signal in the autonomous loop — when you receive it, all available work is taken. Either the project is finished or every remaining job is blocked by a dependency that hasn’t completed yet.

​
claim_job

claim_job claims a specific job by ID. Use it in planned multi-agent runs where a Manager has posted the full job list and each worker knows which job it should take. Keeping each agent’s context focused on its intended work — rather than pulling in whatever happens to be next — reduces cross-contamination between unrelated task contexts.

​
Parameters

​
jobId
string
required
The job ID to claim. Returned by post_job and visible in list_jobs output.
​
agentId
string
The identity of the agent claiming the job. Defaults to the session’s unique identity.
​
projectName
string
Defaults to the auto-detected project.

​
Return Value

ResponseMeaning
CLAIMEDJob successfully assigned to the calling agent
BLOCKED_BY_DEPENDENCIESOne or more dependency jobs are not yet done
ALREADY_CLAIMEDAnother agent already holds this job
NOT_FOUNDNo job with this ID exists on the project board
BLOCKED_BY_DEPENDENCIES is not an error — it means the board’s dependency graph is working correctly. When you receive it, call list_jobs to identify which jobs are blocking, then either claim one of those blockers instead or wait for another agent to complete them.

​
release_job

release_job returns a claimed job to the board. Use it when your agent is blocked, switching tasks, or realizes it claimed the wrong job. The job reverts to pending status and becomes available for any agent to claim.

​
Parameters

​
jobId
string
required
The ID of the job to release back to the board.
​
agentId
string
The agent releasing the job. Defaults to the session’s unique identity.
​
projectName
string
Defaults to the auto-detected project.
If you hold file locks for the job you’re releasing, call release_file_access for each locked file before releasing the job — otherwise those locks remain active and block other agents from picking up the work.

​
cancel_job

cancel_job removes a job from the board entirely. Use it when requirements have changed, a job was posted in error, or a dependency changed and the job is no longer needed. Cancelled jobs are recorded in history but no longer appear in list_jobs results or the claim_next_job queue.

​
Parameters

​
jobId
string
required
The ID of the job to cancel.
​
reason
string
Optional human-readable explanation for the cancellation. Stored in job history and visible to other agents reviewing the board.
​
projectName
string
Defaults to the auto-detected project.

​
The Completion Loop

The recommended pattern for autonomous worker agents is to loop until the board is empty. After completing a job, immediately call claim_next_job again rather than stopping. If another agent joins mid-stream, it will steal the next job from the queue — this is desired behavior, not a race condition. 
while (true) {
  const result = await claim_next_job({ agentId: "my-agent" });

  if (result === "NO_JOBS_AVAILABLE") {
    break;  // All work is done — report success to the user
  }

  // Lock files, do work, update shared context
  await doWork(result.jobId);

  // Mark done, release locks, move on
  await complete_job({ jobId: result.jobId, outcome: "Done" });
}
For multi-agent runs with an intended division of labor, prefer list_jobs to inspect the board first, then claim_job(jobId) to claim your specific task. This keeps each agent’s context focused on its own work instead of pulling in whatever the queue happens to serve next.

Build docs developers (and LLMs) love

Get started for freeTalk to us