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
- In the admin panel, open API keys (in the sidebar).
- 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. - Pick an Access level and when the key Expires, then click Create key.
- 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.
- 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.
Revoke or delete a key
- In the Keys table, click Revoke next to the key. Anything that uses it stops working at once.
- 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:
- Call
GET /api/v1. Readkey.leveland theendpointslist. Only call endpoints whereallowedistrue. - 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 - Deploys are asynchronous. A deploy call returns a queued run right away.
Poll the run until its
statusis no longerqueued,fetching,building,testingordeploying. The final status issuccess,failed,timeout,interruptedorcancelled. - 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.
- 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:
- can’t change the
modeorimage_refof a project that has a host bind mount (an admin added it for the image that runs now); -
can’t change the
modeorimage_refof a project with a Path port in single-domain mode, because those pages run on the admin panel’s own domain.In both cases a new tag or digest of the same image is fine (
nginx:1.27→nginx:1.28); only a different image repository needs an admin key; - can’t set environment variables that change how ci-agent’s own docker tools run (see Environment variables).
Good to know:
- ci-agent stores only a hash of each key. If you lose a key, revoke it and create a new one.
- Keys can expire (7, 30, 90 or 365 days, or never). Expired and revoked keys stop working at once.
- The API keys page shows when and from which IP address each key was last used.
- Every change made with a key is written to the Audit page as
api:<key name>. - Keys skip the password and 2FA login. Give each agent its own key with the lowest level it needs.
Conventions
- Base URL:
https://<your admin domain>/api/v1. An agent running on the server itself can also usehttp://127.0.0.1:8044/api/v1(8044 is the default port; seelistenin Configuration). Other machines reach it through the admin domain, or on the server’s IP and port only if you opened the panel port. - Projects are named by their slug (for example
shop). - Runs (deployments) have a number per project:
/api/v1/projects/shop/runs/12. Each run also has a globalid, used by/api/v1/runs/{id}. - Request and response bodies are JSON. Unknown fields in a request are rejected, so typos don’t pass silently.
- Passwords inside URLs (
https://user:token@…) are shown as***@, and the query part of a URL is replaced with?…, so keys don’t leak them. - Errors look like this:
{ "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
GET /api/v1— your key, its level, every endpoint (withallowed), docs links.GET /api/v1/docs— this guide as Markdown.
Health and projects
GET /api/v1/health— every project withstatus(healthy,degraded,problem) and a list ofproblems.GET /api/v1/projects— all projects with their mode, categories and last run. Add?archived=trueto include archived projects.GET /api/v1/projects/{slug}— one project: git URL and branch, mode, ports (http_port,container_port,primary_service), services, domains, watch paths,catch_all,run_timeout_s,redeploy_every_hours, health and last run. Operator and admin keys also getcompose_inline,status_callback_urlandstatus_callback_token_set(true/false— the token itself is never returned).
Runs and build logs
GET /api/v1/projects/{slug}/runs— recent runs (?limit=20, at most 200).GET /api/v1/projects/{slug}/runs/{number}— one run. Fields:id(global) andnumber(per project),project(the slug)status,trigger,source_ref(what was deployed),commit_sha,commit_message,image_tagsqueued_at,started_at,finished_at,errorcallback:requested(whether this run reports to the status callback),target("run"when the run was started with its owncallback_url, else"project"),url(that per-run URL with any user name and password hidden, ornull),state(pending,delivered,failed,skipped, ornullwhile the run is still going) anddetail(for exampleHTTP 200)links:selfandlog, the API paths of this run and its log
GET /api/v1/projects/{slug}/runs/{number}/log— the end of the run’s build and deploy log (?tail=500lines, at most 5000). The answer has therun, itslinesandtruncated. Only the last 512 KB of the log file is read. A run with no log (not started yet, or removed by log retention) gives 404.GET /api/v1/runs— recent runs of all projects (?limit=50, at most 500). With?active=trueyou get only the queued and running runs, andlimitis ignored.GET /api/v1/runs/{id}— one run by its global id.GET /api/v1/projects/{slug}/domains— the project’s domains:id,domain,canonical,tls,port_id(null= the primary HTTP port),maintenanceandcertificate: the stored certificate that covers the domain (name,source,wildcard,challenge,not_after), ornull.GET /api/v1/projects/{slug}/ports— the project’s ports: the primary HTTP port ("id": "primary") and each extra port, withslug,host_port,container_port,label,service, its default URLs (subdomain,path: on or off) and its proxy tuning (nginx:max_body_mb,proxy_timeout_s,websockets,extra). A read key seesextra_set(true/false) instead of theextradirectives.GET /api/v1/projects/{slug}/limits— the CPU and memory cap and GPU access of each service, as on the Resource limits card:service,cpus(cores, e.g.0.5),memory_mbandgpu.nullmeans no cap. Every known service is listed, also the ones without a cap.GET /api/v1/projects/{slug}/volumes— the project’s volume mounts:id,kind(namedorbind),source,target,read_onlyandservice(null= the singleappservice).
Containers and app logs
GET /api/v1/projects/{slug}/containers— the project’s containers with service name, state, CPU and memory.GET /api/v1/projects/{slug}/logs— the end of the containers’ logs. Options:?service=web(one service),?tail=200(at most 2000),?since=10m(30s,10m,2h,1d). The answer haslines,truncatedandstderr. Output is cut at 1 MB. If reading takes more than 15 seconds you get 504timeout; lowertailor setsince.
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
POST /api/v1/projects— create a project. Fields:
| 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.
-
PATCH /api/v1/projects/{slug}— change settings. Send only the fields you want to change:name,mode,category,git_url,git_branch,compose_path,dockerfile_path,working_dir,image_ref,compose_inline,run_timeout_s(seconds, at most 86400;0= server default),status_callback_urlandstatus_callback_token(an empty string clears them),watch_paths([]clears them: every push deploys again),catch_all(trueorfalse, see Catch-all),redeploy_every_hours(re-run the last successful deploy every N hours, 0–168;0= off).git_url,compose_inline,category, the twostatus_callback_*fields andcatch_allneed an admin key. Ports change with the port endpoints, resource limits with the limit endpoint, volumes with the volume endpoints, and domains with the domain endpoints. The answer holds the updatedprojectand anote: a short text that starts withSavedand says what else happened.Example — report this project’s API and webhook deploys to your CD system:
curl -X PATCH -H "Authorization: Bearer $KEY" \ -H 'Content-Type: application/json' \ -d '{"status_callback_url":"https://cd.example.internal/ci-agent/status", "status_callback_token":"<shared secret>"}' \ "$API/projects/my-app"
Resource limits
-
PATCH /api/v1/projects/{slug}/limits/{service}— cap one service’s CPU and memory, or give it the GPU, as on the Resource limits card of the Settings tab. Send only what you want to change:Field Meaning cpuscores, a number or a string: 0.5= half a core,2= two cores.null= no CPU cap.memory_mbmemory cap in MB, e.g. 512.null= no memory cap.gputruegives the service the host’s GPU (like--gpus all). The host needs the NVIDIA Container Toolkit, or the deploy fails.{service}is a service name fromGET .../limits(appfor dockerfile and image projects). The caps take effect on the next deploy. The answer has the savedlimitand anote.
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).
GET /api/v1/projects/{slug}/env— all variables.PUT /api/v1/projects/{slug}/env— replace all variables:{"env": {"KEY": "value"}}.PATCH /api/v1/projects/{slug}/env— change some variables:{"set": {"KEY": "value"}, "unset": ["OLD_KEY"]}.
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:
PATH,HOME,TMPDIR,SHELL,BASH_ENV,IFS,GCONV_PATH,LOCPATH,NLSPATH,GLIBC_TUNABLES,HOSTALIASES,LOCALDOMAIN,RES_OPTIONS,RESOLV_HOST_CONF;SSH_AUTH_SOCK,SSH_ASKPASS,SSH_ASKPASS_REQUIRE,GIT_SSH,GIT_SSH_COMMAND,GIT_ASKPASS,GIT_EXEC_PATH,GIT_PROXY_COMMAND,GIT_TEMPLATE_DIR,GIT_DIR,GIT_WORK_TREE;- any name starting with
LD_,DOCKER_,COMPOSE_(exceptCOMPOSE_PROFILES),BUILDKIT_,BUILDX_,XDG_orGIT_CONFIG.
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
POST /api/v1/projects/{slug}/deploy— deploy now. With no body, a git project deploys its saved git URL and branch, and an image/inline project deploys from its own config. Optional fields:branch,force,callback_url(see below), and (admin keys only)git_urlorzip_urlto deploy from a different source.POST /api/v1/projects/{slug}/runs/{number}/redeploy— deploy the saved files of an earlier run again (a rollback).POST /api/v1/projects/{slug}/recreate— recreate the containers from the last successful run, with the current env.POST /api/v1/projects/{slug}/runs/{number}/cancel— cancel a queued or running run.
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 deploy, redeploy and recreate, and by create with
deploy: true; - runs started by the project’s webhook URLs.
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:
- admin key: the project’s Callback token, if one is set;
- operator key: no token. An operator chooses this URL, and the Callback
token is an admin-only secret, so it is never sent there. The one exception
is a
callback_urlthat is exactly the project’s own Status callback URL: the token was set for that address, so it goes with it.
Containers
POST /api/v1/projects/{slug}/containers/{name}/{op}—opisstart,stop,restart,pauseorunpause.nameis a container name from/containers.POST /api/v1/projects/{slug}/pause-deploys—{"paused": true}stops webhook deploys, and API deploys then need"force": true;{"paused": false}turns them back on.
Admin endpoints (admin level)
POST /api/v1/projects/{slug}/archive—{"archived": true}orfalse.DELETE /api/v1/projects/{slug}— deletes the project and all its data (containers, volumes, images). You must repeat the slug:DELETE /api/v1/projects/shop?confirm=shop. Not possible while a deploy is running (409run_active). The answer is{"deleted": true, "had_errors": …}.had_errorsistruewhen some cleanup step failed; check the ci-agent log.POST /api/v1/projects/{slug}/exec— run one command inside a container:
{ "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.
POST /api/v1/projects/{slug}/domains— add a domain (see Domains).PATCH /api/v1/projects/{slug}/domains/{id}— turn HTTPS on or off.DELETE /api/v1/projects/{slug}/domains/{id}— delete a domain.POST /api/v1/projects/{slug}/domains/{id}/certificate— get a certificate for a domain (see Domains).POST /api/v1/projects/{slug}/ports— add an extra port (see Ports).PATCH /api/v1/projects/{slug}/ports/{port}— change a port’s numbers, service, slug, default URLs or proxy tuning (see Ports).DELETE /api/v1/projects/{slug}/ports/{port}— remove an extra port.POST /api/v1/projects/{slug}/volumes— mount a volume (see Volumes).DELETE /api/v1/projects/{slug}/volumes/{id}— remove a volume mount.POST /api/v1/projects/{slug}/rotate-webhook— make new webhook URLs. The old ones stop working. The answer has the new URLs inwebhook_gitandwebhook_zip. Thewebhook_zipURL also takes a ZIP file as the POST body (see Webhooks).GET /api/v1/audit— the latest audit log entries (?limit=100).
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:
POST /api/v1/projects/{slug}/domainswith{"domain": "app.example.com"}. Add"port_id": <id>to bind it to one of the project’s extra ports instead of its primary HTTP port. The hostname must be a bare, valid name, or a wildcard like*.example.com(see Wildcard domains); it may not be the admin panel’s own domain, another project’s domain (409conflict) or a host routed to a tunnel. A host that sits under another project’s wildcard, likeci.example.comnext to*.example.com, is allowed: it goes to its own project. The new domain is not primary, so it serves the app directly. Add"tls": trueto serve it over HTTPS at once; that needs a certificate that already covers the hostname (a wildcard for its zone or one named for it), otherwise the answer is 422 and nothing is added. The answer (status 201) has the newdomainandnginx, a short text that says how the nginx update went.PATCH /api/v1/projects/{slug}/domains/{id}with{"tls": true}or{"tls": false}— switch HTTPS for an existing domain, with the same certificate check. The answer has the updateddomainandnginx.DELETE /api/v1/projects/{slug}/domains/{id}— theidcomes fromGET .../domains. The answer hasdeleted,was_canonical(redirects to it are now off) andnginx.-
POST /api/v1/projects/{slug}/domains/{id}/certificate— get a certificate for the domain, as the Issue a certificate card on the domain’s SSL page does, then switch HTTPS on. Fields (all optional):Field Meaning sourceletsencrypt(default),internal_ca,self_signedoruploadscopesingleorwildcard, for the other sources. Blank: the zone’s apex gets a wildcard, a subdomain a cert of its own. Let’s Encrypt always makes a cert for this one host (HTTP-01). A wildcard domain (*.example.com) always gets a wildcard for its zone;singleis refused.tlsfalsestores the certificate but leaves HTTPS off; switch it on later withPATCH .../domains/{id}cert_pem,key_pemfor upload: the full chain and the private keydns_providerwith letsencrypt: get a wildcard for the domain’s zone by DNS-01, the TXT records added through this DNS provider (its Name on the Certificates page)."scope": "single"makes a cert for this one host instead. It renews automatically. A wildcard domain needs this: Let’s Encrypt can’t issue a wildcard over HTTP-01, soletsencryptwithoutdns_provideris refused (422).Let’s Encrypt checks the domain over plain HTTP on port 80, so its DNS must already point at this server (directly or through a CDN that forwards
/.well-known/acme-challenge/). The server itself also needs outbound HTTPS to Let’s Encrypt. The call waits for Let’s Encrypt, usually 5–30 seconds. The answer (status 201) has the updateddomain, thecertificate(name,wildcard,not_after) andnginx. If Let’s Encrypt refuses, the answer is 422 with its reason, and nothing changes. The same 422 comes after 15 seconds if the server can’t reach Let’s Encrypt at all (“could not reach Let’s Encrypt”), or after 50 seconds if it doesn’t finish, which is before nginx or a CDN in front of the panel gives up at 60.With
dns_provider, the server needs outbound HTTPS to the provider’s API too, and the call also waits until the zone’s nameservers serve the TXT records. If the order is done within 45 seconds the answer is 201 as above, withdns_providerincertificate. If not, the answer is 202 with"status": "issuing": the order goes on in the background, and the certificate shows on the domain (GET .../domains) when it is done. A failure after that is written to the audit log (GET /api/v1/audit).Behind a CDN: with HTTPS on, nginx redirects plain HTTP to HTTPS. If the CDN reaches this server over plain HTTP, that becomes a redirect loop. Send
"tls": false, switch the CDN to HTTPS towards the server, then turn HTTPS on withPATCH .../domains/{id}.
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.
-
POST /api/v1/projects/{slug}/ports— publish an extra port:Field Required Meaning host_portyes port published on the server (the nginx proxy target) container_portno port the service listens on inside; default = host_portserviceno compose service that publishes it; default = the single appserviceslugno names its default subdomain and path; default = from label, elseport-<host_port>labelno free text A port this project already publishes, or a slug another of its ports uses, gives 409
conflict. The answer (status 201) has the newportandnginx. -
PATCH /api/v1/projects/{slug}/ports/{port}—{port}isprimary(the project’s HTTP port) or an extra port’sidfromGET .../ports. Send only what you want to change:Field Meaning host_portthe published port. On primary,nullmakes the project internal-only (no published port). An extra port can’t benull; delete it instead.container_portthe port inside the container; null= same ashost_portservicethe compose service that publishes it; null= the singleappserviceslug,labelextra ports only (the primary port uses the project slug) subdomaintrue/false: the default subdomain<slug>.<base domain>pathtrue/false: the default path<base domain>/<slug>/. Turning it on is refused when another project uses that path (409conflict), when the port has no HTTP port, or in single-domain mode without a base path (422).nginxproxy tuning: max_body_mb(largest upload in MB),proxy_timeout_s(1–86400),websockets(trueforwards WebSocket and SSE upgrades),extra(raw lines added to the proxylocationblock). Fields you leave out stay as they are;nullgoes back to nginx’s default.The port numbers, service, slug and label are saved first, then the default URLs and tuning. Proxy tuning is checked before anything changes. The answer has the updated
port(as inGET .../ports) andnginx, a short text that says how the nginx update went. As in the panel, the new values are saved even when nginx refuses them (for example a typo inextra): the note then starts withnginx apply failed, nginx keeps its previous config, and you can send a fix.
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"
DELETE /api/v1/projects/{slug}/ports/{port}— remove an extra port. Its domains go back to the primary port. The primary port can’t be deleted (422); send{"host_port": null}to it instead.
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.
-
POST /api/v1/projects/{slug}/volumes— mount a volume:Field Required Meaning kindno named(a Docker volume, the default) orbind(a folder on the server)sourceyes the volume name, or an absolute host path for bindtargetyes absolute path inside the container read_onlyno truemounts it read-onlyserviceno compose service to mount it into; default = the single appserviceA second volume on the same
targetgives 409conflict. ci-agent then recreates the last successful deploy so the mount takes effect. The answer (status 201) has the newvolumeand anote. -
DELETE /api/v1/projects/{slug}/volumes/{id}— remove a mount. A named volume keeps its data; a host folder is not touched. The last successful deploy is recreated.
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:
GET /api/healthGET /api/projectsGET /api/runs/{id}
Security notes
- Treat a key like a password. Don’t commit it to git or paste it into logs.
- Operator and admin keys can read every environment variable of every project, including passwords.
- Admin keys can take over the server. They can deploy any compose file or repository (a compose file can ask for a privileged container or mount host folders) and run commands inside containers. Give admin keys only to agents you trust, with a short expiry.
- Operator keys can’t choose a project’s repository or edit its compose
file, but they can point
compose_pathat any compose file inside that repository, deploy any image in image mode, change environment variables, redeploy and stop containers, so a careless agent can break a running app. Use a read key when the agent only needs to look and debug. - Operator keys can see Shared environment values. The API never returns them, but every project’s containers receive them, including an image-mode project whose image the key picked. That image can print them to its log. So don’t put a secret in Shared environment that operator keys must not see. Per-project variables are no safer: operator keys can read those directly.
- Container logs are not filtered, so a read key can see anything your app prints there.
status_callback_urldecides where the agent sends HTTP requests, so only admin keys can set it.- A project’s webhook URL is as powerful as an admin key for that project.
Whoever has it can pass their own
git_urlorzip_urland deploy any code. Keep it as secret as an admin key, and rotate it if it leaks. - After 10 wrong keys in a minute, an address is blocked for a minute. All
programs on the server itself share the address
127.0.0.1, so one script with a wrong key can briefly block the others. - More in Security.