Agent API
The /v1 agent routes take a project API key (vcpj_) and nothing else. They are authorized as the key's project: a request can't name another project, and a key restricted to one agent reaches only that agent, its threads and its runs. See Agent API for how to use them.
| Method and path | What it does |
|---|---|
POST /v1/agents/{agent_name}/chat/completions | Runs the live version on a conversation. OpenAI Chat Completions shape; stream: true for server-sent events. |
POST /v1/agents/{agent_name}/runs | Starts a run and returns at once (202). |
GET /v1/runs/{run_id} | A run's status and answer. |
POST /v1/runs/{run_id}/feedback, DELETE /v1/runs/{run_id}/feedback | Rate a finished run, or take the rating back. |
POST /v1/threads | Start a thread with one agent. |
GET /v1/threads/{thread_id}, DELETE /v1/threads/{thread_id} | Read or delete a thread. |
Chat completions
/v1/agents/{agent_name}/chat/completionsBody
messagesarrayrequireduser and assistant messages. System and developer messages are dropped.thread_idstringoptionalstreambooleanoptionaltrue for server-sent events.userstringoptionalmodelstringoptionaltoolsarrayoptionalResponses
chat.completion shape. model is the agent's name.GET /v1/runs/{run_id}.code says which.code and run_id are in detail.code is prompt_injection_refused or guardrail_refused.code and run_id are in detail.Start an async run
/v1/agents/{agent_name}/runsBody
inputstringoptionalmessages.messagesarrayoptionalthread_idstringoptionalwebhook_urlstringoptionalagentApi.webhookAllowedHosts.userstringoptionalResponses
Get a run
/v1/runs/{run_id}The run, read live while it is going and from its record once it has ended. The webhook carries the same body.
Response fields
idstringoptionalstatusstringoptionalrunning, awaiting_approval, completed, rejected, refused or failed.agent_namestringoptionalagent_kindstringoptionalnative or code.versionintegeroptionalthread_idstring or nulloptionaloutputstring or nulloptionalusageobject or nulloptionalcitationsarray or nulloptionalpending_approvalsarrayoptionalrejectionobject or nulloptionalrefusalobject or nulloptionalcode, message and the report.errorstring or nulloptionalwebhookobject or nulloptionalstatus, attempts and last_error.Webhook deliveries
A delivery is a POST of the run body with these headers:
| Header | Contents |
|---|---|
X-Orchestrate-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed by the webhook secret returned with the project key |
X-Orchestrate-Run-Id | The run id, to drop a repeated delivery |
Any status other than 2xx is retried with backoff, from 10 seconds up to an hour apart. Redirects are not followed.
Rate a run
/v1/runs/{run_id}/feedbackRecords a thumb up or down on a finished run. One verdict per person: rating again replaces it. DELETE with ?user_id= takes it back.
Body
ratingstringrequiredup or down.commentstringoptionaluser_idstringoptionalThreads
/v1/threadsBody
agent_namestringrequiredReturns the thread with its id, agent_name, retention_days and turns. GET /v1/threads/{thread_id} returns its turns, tool calls included. DELETE removes it.
Project API keys
These routes take a Keycloak access token, never a key.
| Method and path | Who | What it does |
|---|---|---|
POST /projects/{project_id}/api-keys | project admin | Creates a key. Body: name, optional agent_name to restrict it to one agent, optional expires_at. Returns the key and its webhook_secret, once. |
GET /projects/{project_id}/api-keys | developer or admin | Lists keys, without their secrets, revoked and expired ones included. |
DELETE /projects/{project_id}/api-keys/{key_id} | developer or admin | Revokes a key. |
POST /projects/{project_id}/api-keys/{key_id}/rotate | project admin | New secret, same key. Body: overlap_hours (0 to 720, default 24). |
Limits and scopes for a key are set with PUT /projects/{project_id}/keys/{key_id}/usage-limits.
Hosted chat
The hosted chat page and widget use these routes. See Hosted chat and widget.
| Method and path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/agents/{agent_name}/chat-settings | viewer | The agent's chat settings and its chat id. |
PUT /projects/{project_id}/agents/{agent_name}/chat-settings | project admin | Body: enabled, anonymous_enabled, anonymous_hourly_limit, display_name, logo_url, accent_color, welcome_message, starter_prompts (up to 4), locale, allowed_origins (up to 20). |
GET /chat/{chat_id}/config | anyone | The chat's branding. |
POST /chat/{chat_id}/threads | the chat's users | Start a conversation. |
GET /chat/{chat_id}/threads/{thread_id} | the thread's owner | Its messages and citations, and any run still going. |
POST /chat/{chat_id}/threads/{thread_id}/messages | the thread's owner | Send a message. Answers as server-sent events. |
GET /chat/{chat_id}/runs/{run_id} | the thread's owner | A run's answer, after an approval. |
POST /chat/{chat_id}/runs/{run_id}/feedback | the thread's owner | Rate an answer. |
"The chat's users" are signed-in users of the install, with a Keycloak access token, or anyone when anonymous chat is on. API keys are refused.