REST API reference
Base URL https://api.orkestr.eu. Authenticate with an API token (Authorization: Bearer ork_...) that has the scope each route lists. {agent} is the agent's name or its agt_ id. An invoke-only token (agents:invoke) is safe to keep in your backend: it can run agents but not change them.
Running
/v1/agents/{agent}/invokeRun the agent. Body: input, session_id?, end_user_id?, qualifier?, upgrade?, messages?, wait_s (0 to wait none, default 30), stream. agents:invoke
/v1/agents/runs/{run_id}A run: status, error_code, tools called, tokens, output (for an hour), pending approval. agents:invoke
/v1/agents/runs/{run_id}/streamA run's events as SSE; send Last-Event-ID to resume. agents:invoke
/v1/agents/runs/{run_id}/approvals/{request_id}Body {"decision": "approve" | "deny"}. agents:invoke
/v1/agents/{agent}/sessions/{session_id}End a session: its VM, and the conversation, are destroyed. agents:invoke
{
"run_id": "run_01...",
"session_id": "ses_01...",
"session_created": true,
"status": "completed",
"output": "312 signups, up 9%. 14 came from one IP in two minutes.",
"error_code": null,
"approval": null
}status is completed, failed (see error_code), pending_approval (see approval: request_id, tool, arguments, expires_at), or queued / running with HTTP 202 if wait_s ran out.
Agents and versions
/v1/agentsYour agents. agents:read
/v1/agents/{agent}One agent, with its endpoints (aliases). agents:read
/v1/agentsCreate: {name, description?, config}. The config becomes v1, served at prod. agents:write
/v1/agents/{agent}Rename, describe or pause. Behaviour changes are a new version. agents:write
/v1/agents/{agent}/versionsAll versions. agents:read
/v1/agents/{agent}/versions/{version}One version with its config: a number (3, v3), an alias, or latest. agents:read
/v1/agents/{agent}/versionsPublish: {config, notes?, promote?: ["prod"]}. agents:write
/v1/agents/{agent}/aliases/{name}Point an endpoint at a version: {version}. Promote and roll back. agents:write
/v1/agents/{agent}/usageRuns and tokens per end user (days=, up to 90). agents:read
/v1/model-credentialsYour model keys, with a hint only. They are added in the console. agents:read
Toolsets
/v1/agent-toolsetsYour toolsets and their tools. agents:read
/v1/agent-toolsetsAdd: {name, kind: mcp | http, url, auth_header_name?, auth_secret?, http_tools?, tool_overrides?, auth_type?: "oauth", oauth_client_id?, oauth_client_secret?, oauth_scopes?, catalog_slug?, oauth_per_end_user?}. agents:write
/v1/agent-toolsets/catalogConnectors: vendor-run MCP servers that sign in with OAuth. agents:read
/v1/agent-toolsets/{toolset_id}/oauth/startStart an OAuth connection: {authorize_url, expires_in}. A person opens the link and approves. Optional body {end_user_id, return_url} makes a link for one of your end users. agents:write
/v1/agent-toolsets/{toolset_id}/oauth/disconnectForget your own OAuth connection (end users' stay). agents:write
/v1/agent-toolsets/{toolset_id}/connectionsWho is connected: you ("-") and each end user, with scope, expires_at, connected_at. Never tokens. agents:read
/v1/agent-toolsets/{toolset_id}/connections/{end_user_id}Disconnect one end user ("-" = you). agents:write
/v1/agent-toolsets/{toolset_id}Change url, credential ("" removes it), http_tools, tool_overrides or oauth_per_end_user. agents:write
/v1/agent-toolsets/{toolset_id}/refreshRe-read an MCP server's tools. agents:write
/v1/agent-toolsets/{toolset_id}Remove a toolset. agents:write
End users and memory
/v1/agents/{agent}/end-users/{end_user_id}/memoryWhat the agent remembers about one end user ("-" = runs without one). agents:write
/v1/agents/{agent}/end-users/{end_user_id}/memoryForget one fact (?key=) or all of them. agents:write
/v1/agents/{agent}/end-users/{end_user_id}Erase sessions, runs, usage, memory and connected accounts of one end user: {end_user_id, sessions, vms_destroyed, memory_entries, connections}. agents:write
Triggers
/v1/agents/{agent}/schedulesSchedules (crons) that run this agent. agents:read
/v1/agents/{agent}/schedules{schedule, message, timezone?, name?}. agents:write
/v1/agents/{agent}/schedules/{schedule_id}Change schedule, timezone, message, or enabled. agents:write
/v1/agents/{agent}/schedules/{schedule_id}Remove a schedule. agents:write
/v1/agents/{agent}/webhooksWebhooks, with a secret hint only. agents:read
/v1/agents/{agent}/webhooks{name, input_template?, daily_cap?}. Returns the url and the secret, once. agents:write
/v1/agents/{agent}/webhooks/{webhook_id}Change name, input_template, daily_cap or enabled. agents:write
/v1/agents/{agent}/webhooks/{webhook_id}/rotateNew secret, returned once; the old one stops working. agents:write
/v1/agents/{agent}/webhooks/{webhook_id}Remove a webhook. agents:write
/v1/hooks/agents/{webhook_id}The receiving end. No API token: the webhook secret, as a Bearer token or a sha256 HMAC of the body.
Errors
Errors carry a machine-readable code; 409 and 429 answers include Retry-After where retrying makes sense.
| Status and code | From | Meaning |
|---|---|---|
| 402 account_suspended | invoke | The account is suspended. |
| 403 agent_paused | invoke | The agent (or every agent on the account) is paused. |
| 403 plan_limit | invoke | The version needs something the plan does not allow, such as open network. |
| 409 approval_pending | invoke | The session is waiting for an approval; decide it first. |
| 409 session_busy | invoke | A run is already going in this session. Retry shortly. |
| 409 session_parking | invoke | The session is being parked. Retry in a moment. |
| 409 session_cap_reached | invoke | Too many live sessions for the plan. End some. |
| 410 session_ended | invoke | The session was ended; start a new one. |
| 424 credential_missing | invoke | The version's model credential was removed. |
| 429 rate_limited | invoke | More than 120 invokes a minute on one token. Honour Retry-After. |
| 429 too_many_runs | invoke | Too many runs in flight on the account. |
| 409 webhook_disabled | webhook | The webhook is turned off. |
| 429 daily_cap_reached | webhook | The webhook's runs for today are used up. |