Skip to main content

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 pathWhat it does
POST /v1/agents/{agent_name}/chat/completionsRuns the live version on a conversation. OpenAI Chat Completions shape; stream: true for server-sent events.
POST /v1/agents/{agent_name}/runsStarts 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}/feedbackRate a finished run, or take the rating back.
POST /v1/threadsStart a thread with one agent.
GET /v1/threads/{thread_id}, DELETE /v1/threads/{thread_id}Read or delete a thread.

Chat completions​

POST/v1/agents/{agent_name}/chat/completions

Body​

messagesarrayrequired
The conversation, as user and assistant messages. System and developer messages are dropped.
thread_idstringoptional
Continue a thread. Then send only the new message.
streambooleanoptional
true for server-sent events.
userstringoptional
Your application's id for the person you are calling for. Used by connectors that act as each user.
modelstringoptional
Accepted and ignored.
toolsarrayoptional
Code agents only: client tools passed to the agent's code. Refused for console-made agents.

Responses​

200
The answer, in the chat.completion shape. model is the agent's name.
202
The run is waiting for a person to approve a tool call. The body is the run: poll GET /v1/runs/{run_id}.
403
The key may not call this agent, or a model it would use. code says which.
404
No such agent in the key's project.
409
The agent has no live version, or a tool call was rejected or expired. For a rejection, code and run_id are in detail.
422
A guardrail refused the request: code is prompt_injection_refused or guardrail_refused.
429
A budget or rate limit was reached. See Usage controls.
502
The run failed. code and run_id are in detail.

Start an async run​

POST/v1/agents/{agent_name}/runs

Body​

inputstringoptional
One user message. Send this or messages.
messagesarrayoptional
The conversation, OpenAI-shaped.
thread_idstringoptional
Continue a thread.
webhook_urlstringoptional
Called when the run ends. Its host must be in agentApi.webhookAllowedHosts.
userstringoptional
Your id for the person you are calling for.

Responses​

202
Started. The body is the run.
400
The webhook host isn't allowed, or the body is wrong.

Get a run​

GET/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​

idstringoptional
The run id.
statusstringoptional
running, awaiting_approval, completed, rejected, refused or failed.
agent_namestringoptional
The agent.
agent_kindstringoptional
native or code.
versionintegeroptional
The version that ran.
thread_idstring or nulloptional
The thread, if any.
outputstring or nulloptional
The answer, as stored (redacted).
usageobject or nulloptional
Token counts.
citationsarray or nulloptional
Knowledge-base passages the answer used.
pending_approvalsarrayoptional
While waiting: the tool calls waiting for a person.
rejectionobject or nulloptional
Who rejected a tool call and why, or that it expired.
refusalobject or nulloptional
The guardrail refusal: code, message and the report.
errorstring or nulloptional
Why a failed run failed.
webhookobject or nulloptional
The webhook's status, attempts and last_error.

Webhook deliveries​

A delivery is a POST of the run body with these headers:

HeaderContents
X-Orchestrate-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed by the webhook secret returned with the project key
X-Orchestrate-Run-IdThe 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​

POST/v1/runs/{run_id}/feedback

Records 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​

ratingstringrequired
up or down.
commentstringoptional
Optional. Stored redacted.
user_idstringoptional
Your id for the person who rated, so one key can relay many people's verdicts.

Threads​

POST/v1/threads

Body​

agent_namestringrequired
The agent the thread is with.

Returns 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 pathWhoWhat it does
POST /projects/{project_id}/api-keysproject adminCreates 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-keysdeveloper or adminLists keys, without their secrets, revoked and expired ones included.
DELETE /projects/{project_id}/api-keys/{key_id}developer or adminRevokes a key.
POST /projects/{project_id}/api-keys/{key_id}/rotateproject adminNew 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 pathWhoWhat it does
GET /projects/{project_id}/agents/{agent_name}/chat-settingsviewerThe agent's chat settings and its chat id.
PUT /projects/{project_id}/agents/{agent_name}/chat-settingsproject adminBody: 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}/configanyoneThe chat's branding.
POST /chat/{chat_id}/threadsthe chat's usersStart a conversation.
GET /chat/{chat_id}/threads/{thread_id}the thread's ownerIts messages and citations, and any run still going.
POST /chat/{chat_id}/threads/{thread_id}/messagesthe thread's ownerSend a message. Answers as server-sent events.
GET /chat/{chat_id}/runs/{run_id}the thread's ownerA run's answer, after an approval.
POST /chat/{chat_id}/runs/{run_id}/feedbackthe thread's ownerRate 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.

Was this page helpful?