Skip to main content

API reference

Orchestrate has two HTTP services you call:

ServiceWhat it is forIn-cluster address
APIEverything the admin console does, plus the Agent API your applications call, the hosted chat, A2A and channel webhooks.Service api, port 8000
Model GatewayModel 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:

PlaceholderStands for
https://orchestrate-api.example.comYour API address
https://orchestrate-gateway.example.comYour 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.

TokenWorks onGet it from
Keycloak access tokenThe API and the Model GatewayKeycloak, by signing in
Personal API key (starts vcpk_)The Model Gateway, and code agent source uploadsAPI keys in the console, or POST /api-keys
Project API key (starts vcpj_)The Agent API (/v1/agents/..., /v1/runs/..., /v1/threads/...) onlyAn agent's Connect section, or POST /projects/{project_id}/api-keys
Agent key (starts vcag_)The Model Gateway as one agent, and A2AAPI 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 -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"

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, developer or admin
  • 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 are multipart/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 limit and offset.

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.

StatusMeaning
400The request cannot be carried out as sent. detail says why.
401No token, or the token or API key is invalid, expired or revoked.
402The licence has lapsed past its grace period, or a licence limit is reached. See Licence.
403Your role does not allow this, or policy denied it (Denied by policy).
404The resource does not exist, or you cannot see it.
409The 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.
422The request body is malformed. A 422 with detail.code set to guardrail_refused or prompt_injection_refused is a guardrail refusal.
429A budget, rate limit or quota was reached. Retry-After says when to try again. See Usage controls.
502A service Orchestrate depends on refused or failed, such as the Model Gateway, the policy engine, the audit service or LiveKit. detail names it.
503A 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​

PageCovers
Model GatewayChat, embeddings, speech-to-text, text-to-speech
ModelsThe catalog, builds, deploys, imported weights and clusters
AgentsAgent versions and workflow graphs, tools, running agents, live versions and release settings
Code agentsSources, builds, versions, deployments, promotion and secrets
Runs and approvalsRun status, traces, cancelling and approving tool calls
Agent APICalling agents from applications, project keys and the hosted chat
A2A and agent keysAgents calling agents, and agent keys
ChannelsTeams, Slack and WhatsApp
Knowledge basesKnowledge bases, documents and search
ConnectorsConnectors, MCP servers, OpenAPI import and users' connections
Voice sessionsVoice sessions, voice settings and calls in progress
TelephonySIP trunks, numbers and outbound calls
EvalsEval suites, cases, runs, comparisons, online evals and feedback
GovernanceCustom policies, rules in force, blocked actions, pending approvals, guardrail profiles and model access
Usage and limitsUsage, costs, prices, budgets, rate limits and key rotation
Audit logReading and verifying the audit log, checkpoints, SIEM export and retention
ComplianceThe AI registry, packs and evidence bundles
API keysCreating and revoking personal API keys
IdentityIdentity providers, groups, MFA and invitations
Organizations and projectsOrganizations, folders, projects, members, and deleting projects
Settings and tenancyInstall and organization settings, and organizations in SaaS mode
SitesHybrid sites and their work
PlatformHealth, 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.

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 →