Code agents
These routes manage code agents. They take a Keycloak access token, unless a row says a personal API key works too. While code agents are switched off (agents.enabled: false), every route here answers 404.
Roles in the tables: viewer, developer and admin are the caller's role on the project.
Manifests and templates
| Method and path | Who | What it does |
|---|---|---|
GET /code-agent-templates | any signed-in user | The starter templates, one per framework. |
POST /code-agent-manifests/validate | any signed-in user | Body {"yaml": "...", "expected_name": "..."}. Always 200: {"valid": true, "manifest": {...}} or {"valid": false, "errors": [...]}, each error with path, message and code. |
POST /code-agent-manifests/preview | developer | Reads orchestrate.yaml from a git source before you create the agent. Returns the manifest or its errors, the commit and the branches. |
An invalid manifest anywhere else answers 422 with detail.code manifest_invalid and the same errors list.
Agents and sources
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/code-agents | viewer | The project's code agents. |
POST /projects/{project_id}/code-agents | developer; admin for a source with credentials | Creates one. Body: name, description, auto_deploy_staging (default true) and source. Returns the webhook address and secret once, when a webhook is on. |
GET /projects/{project_id}/code-agents/{name} | viewer | One agent, with its source, live and staging versions and latest build. |
PATCH /projects/{project_id}/code-agents/{name} | developer | Change description or auto_deploy_staging. |
DELETE /projects/{project_id}/code-agents/{name} | admin | Deletes it. 409 while any deployment is active. |
PUT /projects/{project_id}/code-agents/{name}/source | admin | Replace the source. Credentials go to Vault. |
POST /projects/{project_id}/code-agents/{name}/source/webhook-secret | admin | Rotate the webhook secret. |
POST /projects/{project_id}/code-agents/{name}/snapshots | developer; Keycloak token or personal API key | Upload source as multipart/form-data: archive (.tar.gz or .zip), trigger (upload or push), and optional git details. Starts a build. This is what voisctl agent push calls. |
GET /projects/{project_id}/code-agents/{name}/snapshots | viewer | Source snapshots. |
POST /code-agent-sources/{source_id}/webhook | signature only | Your git server's push webhook: GitHub, GitLab, Gitea, Forgejo and Bitbucket signatures are accepted. Pushes to the tracked branch start a build. |
A source is one of:
{ "type": "git", "url": "https://git.example.com/team/support-bot.git", "branch": "main",
"subdirectory": "agents/support", "auth": { "type": "token", "token": "..." },
"webhook": true, "poll_interval_seconds": 300 }
{ "type": "template", "framework": "langgraph" }
{ "type": "upload" }
{ "type": "push" }
Git auth is {"type": "none"}, {"type": "token", "token", "username"} or {"type": "ssh_key", "ssh_private_key", "known_hosts"}.
Builds
| Method and path | Who | What it does |
|---|---|---|
POST /projects/{project_id}/code-agents/{name}/builds | developer | Build a git commit: optional commit_sha or ref, default the branch head. 202. |
GET /projects/{project_id}/code-agents/{name}/builds | viewer | Builds, newest first, paged with limit and before. |
GET /projects/{project_id}/code-agents/{name}/builds/{build_id} | viewer; Keycloak token or personal API key | One build with its stages: fetch, validate, render, install, build, test, push, sign. A failed build has a failure with the stage, a summary and the last log lines. |
GET /projects/{project_id}/code-agents/{name}/builds/{build_id}/logs | viewer; Keycloak token or personal API key | The log as text, or one stage. follow=true streams it as server-sent events. |
POST /projects/{project_id}/code-agents/{name}/builds/{build_id}/cancel | developer | Cancel a build. |
GET /projects/{project_id}/code-agents/{name}/builds/{build_id}/sbom | viewer | The image's CycloneDX SBOM. |
Versions and deployments
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/code-agents/{name}/versions | viewer | Versions, with the live and staging ids, eval results and deployments. |
GET /projects/{project_id}/code-agents/{name}/versions/{version_id} | viewer | One version. |
POST .../versions/{version_id}/deploy | developer | Deploy to staging with one replica. 202. |
POST .../versions/{version_id}/scale | developer | {"replicas": 0}, or {"min", "max"}. 202. |
POST .../versions/{version_id}/restart | developer | Roll the pods and apply changed secrets. 202. |
POST .../versions/{version_id}/undeploy | developer | Remove the deployment. The live version needs {"take_offline": true}. |
POST /projects/{project_id}/code-agents/{name}/promote | developer; admin to override | Body {"version_id", "override_reason"}. 200 when the switch is done, 202 while the version is brought to live size. A failing eval gate answers 409 with detail.code eval_gate and the gate's verdict. |
POST /projects/{project_id}/code-agents/{name}/rollback | developer | Body {"version_id"}: a version that was live before. No eval gate. |
GET /projects/{project_id}/code-agents/{name}/deployments | viewer | Deployments, newest first. |
GET /projects/{project_id}/code-agents/{name}/runtime | viewer | Active deployments with replicas, restarts, latency and recent errors. Every answer also says whether NetworkPolicy is enforced. |
POST .../versions/{version_id}/chat/completions | developer | Chat with one version, as the Playground does. Same body and stream as the Agent API. |
Secrets
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/code-agents/{name}/secrets | developer | The secret names the manifest declares, and whether each is set. Never values. |
PUT /projects/{project_id}/code-agents/{name}/secrets | admin | {"values": {"STRIPE_API_KEY": "...", "OLD_NAME": null}}. Applied at the next deploy, promote or restart. |
Tools, policies and traces
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/code-agents/{name}/tools | viewer | The platform tools the agent sees through the MCP tool server. |
GET /projects/{project_id}/code-agents/{name}/tool-calls | viewer | The agent's platform tool calls, with their approval state. |
PUT /projects/{project_id}/agent-policies/{agent_name}/tools | admin | Limit the platform tools an agent may call. |
GET, PUT /projects/{project_id}/agent-policies/{agent_name} | developer, admin | The agent's model policy: allowed_models, allow_external, max_tokens. |
GET /workflow-runs/{workflow_id}/trace | viewer | A code agent run's spans, tool calls and model calls. |
GET, PUT /projects/{project_id}/code-agents/{name}/trace-settings | viewer, admin | Whether prompt and answer content is kept in spans. Off by default. |
Quotas
| Method and path | Who | What it does |
|---|---|---|
GET /license/agent-usage | any signed-in user | The licence's code-agent limits and the install's use this month. |
GET /agent-quotas | platform admin | Every project's quota and use. |
GET /projects/{project_id}/agent-quota | viewer | One project's quota and use. |
PUT /projects/{project_id}/agent-quota | platform admin | Every quota key (max_code_agents, max_concurrent_builds, build_minutes_per_month, runtime_cpu_millicores, runtime_memory_mib, runtime_gpus, null for no limit), or {"reset": true}. |
A licence limit refuses with 402, a project quota with 429, and a missing licence feature with 403.
Calling code agents
A code agent is called like any agent: through the Agent API, the hosted chat, channels, A2A and voice. Responses say agent_kind: "code".