API & AI agents

ci-agent has an HTTP API for scripts and AI agents (Claude Code, Cursor, your own bots). With an API key, an agent can look at your projects, read build and container logs to find bugs, create and change projects, set environment variables, and deploy. You decide how much each key can do.

Quick start

  1. In the admin panel, open API keys (in the sidebar).
  2. Under Create key, fill in Name (for example claude-ops). A name has 1–40 characters: letters, digits, spaces, _, . or -. Each name must be unique.
  3. Pick an Access level and when the key Expires, then click Create key.
  4. Copy the key. It is shown only once. The page also shows a Prompt for your AI agent. Paste that prompt into your agent. It contains the key, the API address and links to these docs.
  5. Test it:
curl -H 'Authorization: Bearer cia_…' https://ci.example.com/api/v1

The answer lists your key’s level, every endpoint, whether your key may use it, and where the docs are.

The Connect an AI agent card at the bottom of the page has the same prompt with placeholders. Use it if you want to fill in the key yourself.

screenshot: API keys page with the Keys table, the Create key form and the Connect an AI agent card

Revoke or delete a key

  1. In the Keys table, click Revoke next to the key. Anything that uses it stops working at once.
  2. Optional: click Delete to remove the key from the list. Its audit entries stay. Delete only shows for revoked or expired keys, so an active key must be revoked first.

For AI agents: how to start

If you are an AI agent and a human gave you a ci-agent key, do this:

  1. Call GET /api/v1. Read key.level and the endpoints list. Only call endpoints where allowed is true.
  2. Read this guide as Markdown at GET /api/v1/docs (needs the key) or on the public site: https://m-hoseinzadeh.github.io/ci-agent-apt/docs/api.html
  3. Deploys are asynchronous. A deploy call returns a queued run right away. Poll the run until its status is no longer queued, fetching, building, testing or deploying. The final status is success, failed, timeout, interrupted or cancelled.
  4. To find a bug, read logs first: the run log (build and deploy output), then the container logs (the running app). Change things only after that.
  5. Ask the human before you delete or archive a project, or run commands inside containers.

Keys and access levels

A key looks like cia_ followed by 64 hex characters. Send it on every request:

Authorization: Bearer cia_…

Each key has one level. A higher level can do everything a lower level can.

Level What it can do
read See projects, runs, build logs, container logs, containers and health.
operator Everything in read, plus: create image-mode projects, edit projects, set resource limits and the auto-redeploy schedule, read and change environment variables, deploy, redeploy, cancel, recreate, start/stop/restart containers, pause deploys. Works with the source an admin set up; it cannot choose a git repository, zip URL, inline compose file or category.
admin Everything in operator, plus: choose git repositories, zip URLs, inline compose files and categories; archive and delete projects; run commands inside containers; manage domains, certificates, ports, default URLs, proxy tuning and volumes; read the audit log; rotate webhook tokens.

Why operator keys can’t choose the source: a compose file or repository decides what runs, and a compose file can ask for a privileged container or mount host folders, which gives full control of the server. Operator keys can only run what an admin already set up, plus image-mode projects, where ci-agent writes the compose file itself. compose_path and dockerfile_path must point at a file inside the repository for every key level (and in the UI): they may not start with / or use .. to climb above the repository root. They are relative to the working directory, so ../docker-compose.yml from working directory app is fine. For the same reason, an operator key:

Good to know:

Conventions

{ "error": { "code": "insufficient_level", "message": "this endpoint needs an admin key; this key is operator", "docs": "/api/v1/docs" } }
Status Meaning
401 No key, wrong key, revoked key or expired key (missing_key, invalid_key, revoked_key, expired_key).
403 The key’s level is too low (insufficient_level; the error shows required_level and your_level).
404 No such project, run, container or endpoint (not_found).
409 Conflict: slug_taken, deploys_paused, run_active, nothing_deployed, no_containers, or conflict (for example a service name that clashes with another project in the same category).
422 The request is invalid (invalid_request); the message says what to fix.
429 too_many_failures: too many wrong keys from your address. exec_busy: another exec is still running. The answer has a Retry-After: 60 header.
500 internal: something failed on the server. Details are in the ci-agent log.
504 timeout: reading container logs took too long. Lower tail or set since.

Read endpoints (read level)

Discovery and docs

Health and projects

Runs and build logs

Containers and app logs

Example: why did the last deploy of shop fail?

KEY='cia_…'; API=https://ci.example.com/api/v1
curl -H "Authorization: Bearer $KEY" "$API/projects/shop/runs?limit=1"
curl -H "Authorization: Bearer $KEY" "$API/projects/shop/runs/12/log?tail=200"
curl -H "Authorization: Bearer $KEY" "$API/projects/shop/logs?tail=100&since=30m"

Operator endpoints (operator level)

Create and edit projects

Field Required Notes
name, slug yes slug: lowercase letters, digits, dashes
mode no compose (default), dockerfile, image, inline
git_url for git deploys admin only
git_branch no defaults to master
compose_path no compose mode, default docker-compose.yml
dockerfile_path no dockerfile mode, default Dockerfile
working_dir no sub-folder of the repo to build in (monorepos); compose and dockerfile modes only
image_ref image mode e.g. nginx:1.27
compose_inline inline mode the full docker-compose.yml text; admin only
http_port no host port
container_port no app port inside the container; dockerfile and image modes only (ignored for compose and inline)
category no "a,b" or ["a","b"] — shared Docker networks; admin only
env no {"KEY": "value"}
status_callback_url, status_callback_token no where to send this project’s status callback reports; set before the first deploy, so a deploy: true run is reported too; admin only
watch_paths no ["services/wallet/**", "Dockerfile"] (or one pattern per line): a git push deploys only when it changed a matching file. See Webhooks
deploy no true = deploy right after creating
callback_url no with deploy: true: send that run’s status reports to this https:// URL instead of the project’s. See Per-run callback URL

With an operator key, create an image-mode project:

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Cache","slug":"cache","mode":"image","image_ref":"redis:8-alpine","container_port":6379,"deploy":true}' \
  "$API/projects"

With an admin key, create a project from a git repository:

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Shop","slug":"shop","git_url":"https://git.example.com/me/shop.git","http_port":8081,"env":{"NODE_ENV":"production"},"deploy":true}' \
  "$API/projects"

An operator key may also create a compose or dockerfile project without a git_url; an admin then sets the repository before it can deploy.

The answer (status 201) holds the new project and, with deploy: true, the queued run. A compose or dockerfile project needs a git_url to use deploy: true.

Resource limits

curl -X PATCH -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"cpus":0.5,"memory_mb":512}' "$API/projects/shop/limits/web"

Environment variables

Values are shown and stored in cleartext in the API (they are encrypted on disk).

Names use letters, digits and _ and don’t start with a digit. Values can’t contain line breaks and can’t be exactly ***** (the admin panel uses that as a placeholder).

ci-agent runs docker compose with these variables in its own environment (so your compose file can use ${KEY}). Some names would change how those tools run, so only admin keys may add or change them:

Names are exact and case-sensitive, so app settings such as GIT_SHA, ENV or SSH_PORT are fine. An operator key gets 403 insufficient_level for the names above. It may still send back a value an admin already set, unchanged, or remove it.

If the values changed, ci-agent applies them to the running app (it recreates the containers, or rebuilds a Dockerfile project). The answer’s applied field is a short text that says what happened (or null). Add ?apply=false to only save them; the next deploy uses them.

The run that applies the change is not reported to the status callback, and the answer has no run id. To follow it, list the runs with GET /api/v1/projects/{slug}/runs?limit=1.

Deploy

Deploy calls answer 202 with the queued run. Poll GET /api/v1/projects/{slug}/runs/{number} until status is no longer queued, fetching, building, testing or deploying.

If deploys are paused for the project, deploy, redeploy and recreate return 409 deploys_paused. Send {"force": true} to deploy anyway.

API deploys never replace each other in the queue. Only webhook runs do that (see Webhooks).

Instead of polling, set a status callback on the project. Then these runs POST each status change to your URL, with run_id = the run’s id:

Runs started by an env change (PUT/PATCH .../env), from the admin panel, or by auto-redeploy are not reported. See Webhooks → Status callback.

To send one run’s reports somewhere else, add callback_url to the deploy, redeploy, recreate or create (deploy: true) body:

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"callback_url":"https://cd.example.internal/run-status/42"}' \
  "$API/projects/my-app/deploy"

That run then reports only to this URL, not the project’s. It must be an absolute https:// URL of at most 2000 characters; anything else is answered with 422 and no run is started. Any key level may send it. The X-CiAgent-Token header depends on the key:

Containers

Admin endpoints (admin level)

{ "command": "php artisan migrate:status", "service": "web", "timeout_s": 30 }

Pick the container with service or container. A project with only one container needs neither. timeout_s is 1–120 (default 30). The answer has container, exit_code, ok (true when the exit code is 0), stdout and stderr (each cut at 64 KB), stdout_truncated, stderr_truncated and timed_out. This is not an interactive shell. Only two commands can run at a time; a third gets 429 exec_busy.

Domains

A domain decides which hostnames nginx sends to a project, so adding and deleting need an admin key. They do the same checks as the Domains tab and apply nginx right away:

The primary domain, manual Let’s Encrypt DNS-01 orders, DNS providers and the Let’s Encrypt account settings are still managed in the admin panel.

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"domain":"shop.example.com"}' "$API/projects/shop/domains"
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"source":"letsencrypt"}' "$API/projects/shop/domains/12/certificate"

Each domain in GET .../domains has wildcard: true for a *.zone domain.

Catch-all

One project on the server can receive every request whose host matches no other domain, for example your customers’ own domains pointed at this server. See Catch-all. Turn it on or off with PATCH /api/v1/projects/{slug} and {"catch_all": true} or {"catch_all": false} (admin key). The project needs an HTTP port. If another project has it, the answer is 409 conflict and nothing changes; turn it off there first. GET /api/v1/projects/{slug} shows catch_all.

Example — a project that serves every subdomain of example.com and every other host:

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"domain":"*.example.com"}' "$API/projects/sites/domains"
curl -X PATCH -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"catch_all":true}' "$API/projects/sites"

Ports

These do what the Ports card of the Settings tab and the Proxy tuning panel of the Domains tab do. They change nginx, so they need an admin key.

curl -X PATCH -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"subdomain":false,"nginx":{"websockets":true}}' "$API/projects/shop/ports/primary"
curl -X PATCH -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"host_port":8090,"container_port":3000}' "$API/projects/shop/ports/primary"

Volumes

These do what the Volumes card of the Settings tab does. A host path reaches the server’s files, so they need an admin key.

curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"source":"shop-data","target":"/var/lib/shop"}' "$API/projects/shop/volumes"

Old endpoints

Before API keys, ci-agent had one read-only token on the Settings page. On upgrade, that token becomes a read key named legacy, so scripts that use it keep working. (If you later go back to an older ci-agent version, create a new token on its Settings page.) These paths still work with any key and return the same JSON as before:

Security notes