API reference
Orchestrate has two HTTP services you call:
| Service | What it is for | In-cluster address |
|---|---|---|
| API | Everything the admin console does, plus the Agent API your applications call, the hosted chat, A2A and channel webhooks. | Service api, port 8000 |
| Model Gateway | Model calls from your own applications: chat, embeddings, speech-to-text and text-to-speech. | Service model-gateway, port 8001 |
Your operator decides whether each one has a hostname outside the cluster. See Configuration. The examples use these placeholders:
| Placeholder | Stands for |
|---|---|
https://orchestrate-api.example.com | Your API address |
https://orchestrate-gateway.example.com | Your Model Gateway address |
If a service is not exposed, forward its port and use http://localhost:
kubectl port-forward -n vois-orchestrate svc/api 8000:8000
kubectl port-forward -n vois-orchestrate svc/model-gateway 8001:8001
Use the namespace Orchestrate is installed in.
Authentication
Every request, except GET /health and GET /version, needs a bearer token:
Authorization: Bearer <token>
There are four kinds of token, each for one job.
| Token | Works on | Get it from |
|---|---|---|
| Keycloak access token | The API and the Model Gateway | Keycloak, by signing in |
Personal API key (starts vcpk_) | The Model Gateway, and code agent source uploads | API keys in the console, or POST /api-keys |
Project API key (starts vcpj_) | The Agent API (/v1/agents/..., /v1/runs/..., /v1/threads/...) only | An agent's Connect section, or POST /projects/{project_id}/api-keys |
Agent key (starts vcag_) | The Model Gateway as one agent, and A2A | API keys > Agent keys, or POST /projects/{project_id}/agent-keys |
Use a project key for applications that call agents, and a personal or agent key for code that calls models. Use a Keycloak access token for everything else, such as managing agents or knowledge bases. Keys are not accepted by the rest of the API, and no key can list, create or revoke keys.
Get a Keycloak access token
Request a token from the vois-orchestrate realm with your username and password. The console's client, vois-orchestrate-console, allows this.
If your operator exposed Keycloak's sign-in pages with the console, use that address, for example https://orchestrate.example.com/realms/vois-orchestrate/.... Otherwise forward its port first:
kubectl port-forward -n vois-orchestrate svc/keycloak 8180:8080
- cURL
- Python
curl -X POST "http://localhost:8180/realms/vois-orchestrate/protocol/openid-connect/token" \
-d grant_type=password \
-d client_id=vois-orchestrate-console \
-d username="$ORCHESTRATE_USER" \
-d password="$ORCHESTRATE_PASSWORD"
import os
import requests
res = requests.post(
"http://localhost:8180/realms/vois-orchestrate/protocol/openid-connect/token",
data={
"grant_type": "password",
"client_id": "vois-orchestrate-console",
"username": os.environ["ORCHESTRATE_USER"],
"password": os.environ["ORCHESTRATE_PASSWORD"],
},
)
res.raise_for_status()
token = res.json()["access_token"]
Send access_token from the response as the bearer token. Access tokens expire after 5 minutes by default. Request a new one, or use the refresh_token from the same response with grant_type=refresh_token.
The token carries the user's platform roles. Use a dedicated Keycloak user for scripts, with only the roles and project memberships the script needs.
Access tokens from a port-forwarded Keycloak work on the API and the Model Gateway like any other. If two-factor sign-in is required for the user, every call is refused until they set up an authenticator, so script users are best created without that requirement or as members of an organization that doesn't require it.
On an install that hosts several organizations, a user who belongs to more than one picks the organization for a request with the X-Vois-Tenant header.
Roles
The API checks two things:
- the platform role in the token:
viewer,developeroradmin - the caller's membership role on the organization, folder or project the request is about
Each endpoint in this reference says what it needs. A platform admin passes every check. See Users, roles and projects.
Requests and responses
- Send request bodies as JSON with
Content-Type: application/json, except file uploads, which aremultipart/form-data. - Responses are JSON, except text-to-speech audio and streamed chat.
- IDs are strings. Some you choose, such as connector and project IDs. Others Orchestrate generates.
- Timestamps are ISO 8601 in UTC.
- Most list endpoints return everything in one response. The audit log and blocked actions are paged with
limitandoffset.
Both services also publish their OpenAPI schema at /openapi.json.
Errors
Errors have a detail field. Usually it is a sentence that says what went wrong and what to do about it. Some errors, such as a guardrail refusal or a blocked release, return an object with a code or a gate you can act on.
| Status | Meaning |
|---|---|
400 | The request cannot be carried out as sent. detail says why. |
401 | No token, or the token or API key is invalid, expired or revoked. |
402 | The licence has lapsed past its grace period, or a licence limit is reached. See Licence. |
403 | Your role does not allow this, or policy denied it (Denied by policy). |
404 | The resource does not exist, or you cannot see it. |
409 | The request conflicts with the current state. For example, the model is not built yet, a run's approval is already decided, or the release gate refuses a version. |
422 | The request body is malformed. A 422 with detail.code set to guardrail_refused or prompt_injection_refused is a guardrail refusal. |
429 | A budget, rate limit or quota was reached. Retry-After says when to try again. See Usage controls. |
502 | A service Orchestrate depends on refused or failed, such as the Model Gateway, the policy engine, the audit service or LiveKit. detail names it. |
503 | A dependency is unreachable, such as Keycloak or the orchestration engine, or there is no voice capacity. |
A malformed body gets the standard validation error:
{
"detail": [
{ "loc": ["body", "project_id"], "msg": "Field required", "type": "missing" }
]
}
Pages in this reference
| Page | Covers |
|---|---|
| Model Gateway | Chat, embeddings, speech-to-text, text-to-speech |
| Models | The catalog, builds, deploys, imported weights and clusters |
| Agents | Agent versions and workflow graphs, tools, running agents, live versions and release settings |
| Code agents | Sources, builds, versions, deployments, promotion and secrets |
| Runs and approvals | Run status, traces, cancelling and approving tool calls |
| Agent API | Calling agents from applications, project keys and the hosted chat |
| A2A and agent keys | Agents calling agents, and agent keys |
| Channels | Teams, Slack and WhatsApp |
| Knowledge bases | Knowledge bases, documents and search |
| Connectors | Connectors, MCP servers, OpenAPI import and users' connections |
| Voice sessions | Voice sessions, voice settings and calls in progress |
| Telephony | SIP trunks, numbers and outbound calls |
| Evals | Eval suites, cases, runs, comparisons, online evals and feedback |
| Governance | Custom policies, rules in force, blocked actions, pending approvals, guardrail profiles and model access |
| Usage and limits | Usage, costs, prices, budgets, rate limits and key rotation |
| Audit log | Reading and verifying the audit log, checkpoints, SIEM export and retention |
| Compliance | The AI registry, packs and evidence bundles |
| API keys | Creating and revoking personal API keys |
| Identity | Identity providers, groups, MFA and invitations |
| Organizations and projects | Organizations, folders, projects, members, and deleting projects |
| Settings and tenancy | Install and organization settings, and organizations in SaaS mode |
| Sites | Hybrid sites and their work |
| Platform | Health, version, the current user, the licence and system status |
This reference covers the endpoints you are most likely to call from your own code. The console also uses some endpoints that are not listed here.