API integration guide

Production-oriented reference for remote queue management.

Back to dashboard

Quick start

All /api/v1/* endpoints require an active API token. Send it as a Bearer token or with X-API-Token.

curl -sS https://queue.example/api/v1/environment \
  -H 'Authorization: Bearer <API_TOKEN>'

Tokens are created at /api-tokens and are shown only once. Use HTTPS and never place tokens in URLs, logs or browser source.

Endpoints

MethodPathPurpose
GET/api/v1/healthLightweight health and status counts.
GET/api/v1/environmentHost, CPU, memory, storage, profiles/models, projects, jobs, token usage.
GET/api/v1/statsAggregate jobs/projects/tokens/status metrics.
GET/api/v1/jobsList jobs with pagination and filters.
POST/api/v1/jobsCreate a queued job by default, or a draft when requested.
GET/api/v1/jobs/{id}Full job metadata.
GET/api/v1/jobs/{id}/statusCompact lifecycle status.
GET/api/v1/jobs/{id}/resultResult metadata and stdout/stderr.
GET/api/v1/jobs/{id}/logs?stream=stdout|stderr|allJob logs (bounded response).
POST/api/v1/jobs/{id}/reread-logsExplicitly read all persisted stdout/stderr, refresh metadata and recover follow-up jobs.
PATCH/PUT/api/v1/jobs/{id}Edit a queued job.
DELETE/api/v1/jobs/{id}Cancel a job.
POST/api/v1/jobs/{id}/retry|cancel|killLifecycle actions.
GET/api/v1/projects, /api/v1/rules, /api/v1/profilesSupporting resources.
GET/api/v1/openai-accountDevice-login status; requires an active API token and never returns credentials.
POST/api/v1/deploy-bindingsCreate/update a binding; binding_mode: generic, openvscode, django or custom.
POST/api/v1/openai-account/start|cancelStart or cancel the server-side codex login --device-auth flow.

Link an OpenAI account

The web console runs codex login --device-auth as the service account. Open the device URL, enter the one-time code, and poll the status endpoint. The code is held in memory for the current process; the Codex CLI owns its credential storage.

curl -sS -X POST https://queue.example/api/v1/openai-account/start \
  -H 'Authorization: Bearer <API_TOKEN>'
curl -sS https://queue.example/api/v1/openai-account \
  -H 'Authorization: Bearer <API_TOKEN>'

Only trusted administrators should perform this action. Do not paste the device code into tickets, chat or logs.

List and filter jobs

Use limit (1–500), offset, status, search and cwd. The response contains items, total, offset and status counts.

curl -G https://queue.example/api/v1/jobs \
  -H 'Authorization: Bearer <API_TOKEN>' \
  --data-urlencode 'status=QUEUED' --data-urlencode 'limit=50' --data-urlencode 'offset=0'

Create a job

prompt is required. You may use base_prompt, extra_prompt, rule_ids, profile, model, priority, timeout, retries, cwd, project_id or project, and idempotency_key. Omit save_draft (or set it to false) to enqueue immediately; set save_draft: true or draft: true to create a DRAFT that will not be picked up by the worker.

If the project name/id does not exist it is created automatically. A missing working directory is created recursively. Omit project to use local_project.

curl -sS -X POST https://queue.example/api/v1/jobs \
  -H 'Authorization: Bearer <API_TOKEN>' -H 'Content-Type: application/json' \
  -d '{"project":"billing-agent","cwd":"/srv/work/billing","base_prompt":"Run the tests","profile":"ollama_qwen35","model":"qwen3.5:35b","priority":100,"idempotency_key":"billing-2026-08-28-001"}'

Successful creation returns 201 and {"id":"..."}. Reusing an idempotency key returns the existing job id.

curl -sS -X POST https://queue.example/api/v1/jobs \
  -H 'Authorization: Bearer <API_TOKEN>' -H 'Content-Type: application/json' \
  -d '{"project":"billing-agent","base_prompt":"Prepare a migration plan","save_draft":true}'

Observe and manage a job

# status
curl -sS https://queue.example/api/v1/jobs/<JOB_ID>/status -H 'Authorization: Bearer <API_TOKEN>'

# full result (stdout/stderr are UTF-8 text, bounded to 10 MiB)
curl -sS https://queue.example/api/v1/jobs/<JOB_ID>/result -H 'Authorization: Bearer <API_TOKEN>'

# edit only while QUEUED
curl -sS -X PATCH https://queue.example/api/v1/jobs/<JOB_ID> \
  -H 'Authorization: Bearer <API_TOKEN>' -H 'Content-Type: application/json' \
  -d '{"priority":20,"extra_prompt":"Also run the lint checks"}'

# cancel (DELETE is an alias)
curl -sS -X POST https://queue.example/api/v1/jobs/<JOB_ID>/cancel -H 'Authorization: Bearer <API_TOKEN>'

Standard errors

HTTPMeaningTypical response
400Invalid JSON, field, state or action.{"error":"..."}
401Missing, expired, suspended or invalid token.{"error":"unauthorized"}
404Unknown job/resource/route.{"error":"job_not_found"}
413Request exceeds configured body limit.{"error":"Invalid request size"}
5xxServer/storage failure.Retry with backoff; do not duplicate non-idempotent requests.

Clients should treat unknown error fields as optional, redact tokens from logs, and retry only safe/idempotent reads or requests carrying an idempotency key. Add ?full=1 to the logs or result endpoint when the complete persisted stdout/stderr is required; the default response remains bounded.

Production checklist