Skip to main content

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 pathWhoWhat it does
GET /code-agent-templatesany signed-in userThe starter templates, one per framework.
POST /code-agent-manifests/validateany signed-in userBody {"yaml": "...", "expected_name": "..."}. Always 200: {"valid": true, "manifest": {...}} or {"valid": false, "errors": [...]}, each error with path, message and code.
POST /code-agent-manifests/previewdeveloperReads 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 pathWhoWhat it does
GET /projects/{project_id}/code-agentsviewerThe project's code agents.
POST /projects/{project_id}/code-agentsdeveloper; admin for a source with credentialsCreates 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}viewerOne agent, with its source, live and staging versions and latest build.
PATCH /projects/{project_id}/code-agents/{name}developerChange description or auto_deploy_staging.
DELETE /projects/{project_id}/code-agents/{name}adminDeletes it. 409 while any deployment is active.
PUT /projects/{project_id}/code-agents/{name}/sourceadminReplace the source. Credentials go to Vault.
POST /projects/{project_id}/code-agents/{name}/source/webhook-secretadminRotate the webhook secret.
POST /projects/{project_id}/code-agents/{name}/snapshotsdeveloper; Keycloak token or personal API keyUpload 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}/snapshotsviewerSource snapshots.
POST /code-agent-sources/{source_id}/webhooksignature onlyYour 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 pathWhoWhat it does
POST /projects/{project_id}/code-agents/{name}/buildsdeveloperBuild a git commit: optional commit_sha or ref, default the branch head. 202.
GET /projects/{project_id}/code-agents/{name}/buildsviewerBuilds, newest first, paged with limit and before.
GET /projects/{project_id}/code-agents/{name}/builds/{build_id}viewer; Keycloak token or personal API keyOne 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}/logsviewer; Keycloak token or personal API keyThe log as text, or one stage. follow=true streams it as server-sent events.
POST /projects/{project_id}/code-agents/{name}/builds/{build_id}/canceldeveloperCancel a build.
GET /projects/{project_id}/code-agents/{name}/builds/{build_id}/sbomviewerThe image's CycloneDX SBOM.

Versions and deployments​

Method and pathWhoWhat it does
GET /projects/{project_id}/code-agents/{name}/versionsviewerVersions, with the live and staging ids, eval results and deployments.
GET /projects/{project_id}/code-agents/{name}/versions/{version_id}viewerOne version.
POST .../versions/{version_id}/deploydeveloperDeploy to staging with one replica. 202.
POST .../versions/{version_id}/scaledeveloper{"replicas": 0}, or {"min", "max"}. 202.
POST .../versions/{version_id}/restartdeveloperRoll the pods and apply changed secrets. 202.
POST .../versions/{version_id}/undeploydeveloperRemove the deployment. The live version needs {"take_offline": true}.
POST /projects/{project_id}/code-agents/{name}/promotedeveloper; admin to overrideBody {"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}/rollbackdeveloperBody {"version_id"}: a version that was live before. No eval gate.
GET /projects/{project_id}/code-agents/{name}/deploymentsviewerDeployments, newest first.
GET /projects/{project_id}/code-agents/{name}/runtimeviewerActive deployments with replicas, restarts, latency and recent errors. Every answer also says whether NetworkPolicy is enforced.
POST .../versions/{version_id}/chat/completionsdeveloperChat with one version, as the Playground does. Same body and stream as the Agent API.

Secrets​

Method and pathWhoWhat it does
GET /projects/{project_id}/code-agents/{name}/secretsdeveloperThe secret names the manifest declares, and whether each is set. Never values.
PUT /projects/{project_id}/code-agents/{name}/secretsadmin{"values": {"STRIPE_API_KEY": "...", "OLD_NAME": null}}. Applied at the next deploy, promote or restart.

Tools, policies and traces​

Method and pathWhoWhat it does
GET /projects/{project_id}/code-agents/{name}/toolsviewerThe platform tools the agent sees through the MCP tool server.
GET /projects/{project_id}/code-agents/{name}/tool-callsviewerThe agent's platform tool calls, with their approval state.
PUT /projects/{project_id}/agent-policies/{agent_name}/toolsadminLimit the platform tools an agent may call.
GET, PUT /projects/{project_id}/agent-policies/{agent_name}developer, adminThe agent's model policy: allowed_models, allow_external, max_tokens.
GET /workflow-runs/{workflow_id}/traceviewerA code agent run's spans, tool calls and model calls.
GET, PUT /projects/{project_id}/code-agents/{name}/trace-settingsviewer, adminWhether prompt and answer content is kept in spans. Off by default.

Quotas​

Method and pathWhoWhat it does
GET /license/agent-usageany signed-in userThe licence's code-agent limits and the install's use this month.
GET /agent-quotasplatform adminEvery project's quota and use.
GET /projects/{project_id}/agent-quotaviewerOne project's quota and use.
PUT /projects/{project_id}/agent-quotaplatform adminEvery 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".

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →