# 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

POST`/v1/agents/{agent}/invoke`

Run the agent. Body: input, session_id?, end_user_id?, qualifier?, upgrade?, messages?, wait_s (0 to wait none, default 30), stream. agents:invoke

GET`/v1/agents/runs/{run_id}`

A run: status, error_code, tools called, tokens, output (for an hour), pending approval. agents:invoke

GET`/v1/agents/runs/{run_id}/stream`

A run's events as SSE; send Last-Event-ID to resume. agents:invoke

POST`/v1/agents/runs/{run_id}/approvals/{request_id}`

Body {"decision": "approve" | "deny"}. agents:invoke

DELETE`/v1/agents/{agent}/sessions/{session_id}`

End a session: its VM, and the conversation, are destroyed. agents:invoke

```json
{
  "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

GET`/v1/agents`

Your agents. agents:read

GET`/v1/agents/{agent}`

One agent, with its endpoints (aliases). agents:read

POST`/v1/agents`

Create: {name, description?, config}. The config becomes v1, served at prod. agents:write

PATCH`/v1/agents/{agent}`

Rename, describe or pause. Behaviour changes are a new version. agents:write

GET`/v1/agents/{agent}/versions`

All versions. agents:read

GET`/v1/agents/{agent}/versions/{version}`

One version with its config: a number (3, v3), an alias, or latest. agents:read

POST`/v1/agents/{agent}/versions`

Publish: {config, notes?, promote?: ["prod"]}. agents:write

PUT`/v1/agents/{agent}/aliases/{name}`

Point an endpoint at a version: {version}. Promote and roll back. agents:write

GET`/v1/agents/{agent}/usage`

Runs and tokens per end user (days=, up to 90). agents:read

GET`/v1/model-credentials`

Your model keys, with a hint only. They are added in the console. agents:read

## Toolsets

GET`/v1/agent-toolsets`

Your toolsets and their tools. agents:read

POST`/v1/agent-toolsets`

Add: {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

GET`/v1/agent-toolsets/catalog`

Connectors: vendor-run MCP servers that sign in with OAuth. agents:read

POST`/v1/agent-toolsets/{toolset_id}/oauth/start`

Start 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

POST`/v1/agent-toolsets/{toolset_id}/oauth/disconnect`

Forget your own OAuth connection (end users' stay). agents:write

GET`/v1/agent-toolsets/{toolset_id}/connections`

Who is connected: you ("-") and each end user, with scope, expires_at, connected_at. Never tokens. agents:read

DELETE`/v1/agent-toolsets/{toolset_id}/connections/{end_user_id}`

Disconnect one end user ("-" = you). agents:write

PATCH`/v1/agent-toolsets/{toolset_id}`

Change url, credential ("" removes it), http_tools, tool_overrides or oauth_per_end_user. agents:write

POST`/v1/agent-toolsets/{toolset_id}/refresh`

Re-read an MCP server's tools. agents:write

DELETE`/v1/agent-toolsets/{toolset_id}`

Remove a toolset. agents:write

## End users and memory

GET`/v1/agents/{agent}/end-users/{end_user_id}/memory`

What the agent remembers about one end user ("-" = runs without one). agents:write

DELETE`/v1/agents/{agent}/end-users/{end_user_id}/memory`

Forget one fact (?key=) or all of them. agents:write

DELETE`/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

GET`/v1/agents/{agent}/schedules`

Schedules (crons) that run this agent. agents:read

POST`/v1/agents/{agent}/schedules`

{schedule, message, timezone?, name?}. agents:write

PATCH`/v1/agents/{agent}/schedules/{schedule_id}`

Change schedule, timezone, message, or enabled. agents:write

DELETE`/v1/agents/{agent}/schedules/{schedule_id}`

Remove a schedule. agents:write

GET`/v1/agents/{agent}/webhooks`

Webhooks, with a secret hint only. agents:read

POST`/v1/agents/{agent}/webhooks`

{name, input_template?, daily_cap?}. Returns the url and the secret, once. agents:write

PATCH`/v1/agents/{agent}/webhooks/{webhook_id}`

Change name, input_template, daily_cap or enabled. agents:write

POST`/v1/agents/{agent}/webhooks/{webhook_id}/rotate`

New secret, returned once; the old one stops working. agents:write

DELETE`/v1/agents/{agent}/webhooks/{webhook_id}`

Remove a webhook. agents:write

POST`/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. |