Agents

Each agent wraps an LLM with a system prompt, tools, knowledge bases, and optional MCP servers. Agents use a ReAct loop to reason about user messages, call tools as needed, and generate streaming responses. Sessions maintain conversation history across turns.

Common Patterns

Create an agent, assign tools and knowledge bases, then use the streaming endpoint for conversations. Pass session_id to continue multi-turn conversations. For human-in-the-loop workflows, configure hooks and use the approve endpoint when approval_requested events are received.

Which key. Agent CRUD, tool, knowledge-base, MCP-server and hook routes require the project’s service role key. The conversation routes under Execution (listing, creating and deleting sessions, /run, /run/stream, reading a run, and approving a run) also accept a signed-in user’s access token, scoped to that user’s own sessions and runs, with the run-body limits noted below. See Which key for which route.

Agent CRUD

GET /api/agents

List all agents.

response = requests.get(f"{BASE_URL}/api/agents", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents`, { headers });

curl '{BASE_URL}/api/agents' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents

Create a new agent.

{
  "name": "My Agent",
  "model": "gpt-4o",
  "system_prompt": "You are a helpful assistant.",
  "settings": { "temperature": 0.7 }
}

The body honors name (required), model, system_prompt, and settings (object). Top-level fields like temperature are silently dropped; anything model-tuning related must be nested in settings. model is a LiteLLM model ID passed through unchanged (e.g. gpt-4o, claude-sonnet-4-6, openrouter/<org>/<model>); see Bring your own LLM for the per-provider format and key requirements.

response = requests.post(f"{BASE_URL}/api/agents", headers=headers, json={"name": "My Agent", "model": "gpt-4o", "system_prompt": "You are helpful.", "settings": {"temperature": 0.7}})

const res = await fetch(`${BASE_URL}/api/agents`, { method: "POST", headers, body: JSON.stringify({ name: "My Agent", model: "gpt-4o", system_prompt: "You are helpful.", settings: { temperature: 0.7 } }) });

curl -X POST '{BASE_URL}/api/agents' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "My Agent", "model": "gpt-4o"}'

GET /api/agents/

Get an agent by ID.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}`, { headers });

curl '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/agents/

Update an agent’s name, model, system prompt, or settings.

string

required

Agent ID

response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}", headers=headers, json={"settings": {"temperature": 0.5}})

await fetch(`${BASE_URL}/api/agents/${agentId}`, { method: "PATCH", headers, body: JSON.stringify({ settings: { temperature: 0.5 } }) });

curl -X PATCH '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"settings": {"temperature": 0.5}}'

DELETE /api/agents/

Delete an agent.

string

required

Agent ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Tool Assignments

POST /api/agents//tools

Assign a tool to the agent.

string

required

Agent ID

{ "tool_name": "database_query" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers, json={"tool_name": "database_query"})

await fetch(`${BASE_URL}/api/agents/${agentId}/tools`, { method: "POST", headers, body: JSON.stringify({ tool_name: "database_query" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"tool_name": "database_query"}'

GET /api/agents//tools

List tool assignments for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/tools`, { headers });

curl '{BASE_URL}/api/agents/{id}/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/agents//tools/

Update a tool assignment’s config_override.

string

required

Agent ID

string

required

Assignment ID

object

required

The full config_override object. Tool-specific shape; for database tools include schemas: { <schema_name>: [<table_name>, ...] }.

The body MUST use the key config_override. Passing config (or any other top-level key) is a silent no-op: the route returns 200 with the unchanged assignment because the handler only inspects config_override.How config_override works per tool type:

Database tools (database_query, database_write): config_override.schemas: { <schema>: [<table>, ...] } is the table list, and it’s everything the tools can reach: database_write rejects tables outside it, and database_query parses each query and rejects any reference to a table outside it. Only plain tables, partitioned tables and views created WITH (security_invoker = true) may be listed; a view without security_invoker, a materialized view or a foreign table answers 400. What the tools act as depends on who started the run (see Data tool access and limits). Schemas must be a dict, schema names must match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$, system schemas (ai, auth, storage, pg_*, etc.) are rejected, and each value must be a list of valid table names.
All other builtin tools (web_search, web_scrape, http_request, code_execute, storage_read, storage_write): any key in config_override whose name matches a parameter in the tool’s input_schema is force-injected into every call’s arguments. Keys not in the schema are silently dropped (no error, no warning). For example, setting config_override: { "max_results": 3, "include_domains": ["example.com"] } on a web_search assignment locks every search the agent does to 3 results from example.com. This constrains a tool without changing what the agent is told about it: the LLM still sees the full schema, but its requested values for those keys are overridden.
Custom tools: config_override is not used. Custom-tool behavior is controlled via the Tool row’s own config (endpoint, method, headers) at create time.
MCP tools: config_override is not used. MCP-tool behavior is controlled via the AgentMcpServer row’s headers and enabled flag.

{
  "config_override": {
    "schemas": {
      "public": ["users", "orders"]
    }
  }
}

response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers, json={"config_override": {"schemas": {"public": ["users", "orders"]}}})

await fetch(`${BASE_URL}/api/agents/${agentId}/tools/${assignmentId}`, { method: "PATCH", headers, body: JSON.stringify({ config_override: { schemas: { public: ["users", "orders"] } } }) });

curl -X PATCH '{BASE_URL}/api/agents/{id}/tools/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"config_override": {"schemas": {"public": ["users", "orders"]}}}'

DELETE /api/agents//tools/

Remove a tool assignment from the agent.

string

required

Agent ID

string

required

Assignment ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/tools/${assignmentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/tools/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Knowledge Base Assignments

POST /api/agents//knowledge-bases

Link a knowledge base to the agent. Creates a dynamic search tool.

string

required

Agent ID

{ "knowledge_base_id": "kb-uuid" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers, json={"knowledge_base_id": kb_id})

await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases`, { method: "POST", headers, body: JSON.stringify({ knowledge_base_id: kbId }) });

curl -X POST '{BASE_URL}/api/agents/{id}/knowledge-bases' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"knowledge_base_id": "kb-uuid"}'

GET /api/agents//knowledge-bases

List knowledge base assignments for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases`, { headers });

curl '{BASE_URL}/api/agents/{id}/knowledge-bases' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/agents//knowledge-bases/

Remove a knowledge base from the agent.

string

required

Agent ID

string

required

Assignment ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases/{assignment_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases/${assignmentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/knowledge-bases/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

MCP Servers

POST /api/agents//mcp-servers

Add an MCP server to the agent.

string

required

Agent ID

{
  "url": "https://mcp.example.com",
  "transport": "http",
  "name": "My MCP"
}

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers, json={"url": "https://mcp.example.com", "transport": "http", "name": "My MCP"})

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers`, { method: "POST", headers, body: JSON.stringify({ url: "https://mcp.example.com", transport: "http", name: "My MCP" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/mcp-servers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"url": "https://mcp.example.com", "transport": "http"}'

GET /api/agents//mcp-servers

List MCP servers for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers`, { headers });

curl '{BASE_URL}/api/agents/{id}/mcp-servers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PUT /api/agents//mcp-servers/

Update an MCP server configuration.

string

required

Agent ID

string

required

MCP Server ID

response = requests.put(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers, json={"url": "https://new-url.com"})

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers/${serverId}`, { method: "PUT", headers, body: JSON.stringify({ url: "https://new-url.com" }) });

curl -X PUT '{BASE_URL}/api/agents/{id}/mcp-servers/{server_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"url": "https://new-url.com"}'

DELETE /api/agents//mcp-servers/

Remove an MCP server from the agent.

string

required

Agent ID

string

required

MCP Server ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers/${serverId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/mcp-servers/{server_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Hooks

Intercept agent execution at lifecycle boundaries. For the full event/type semantics, the webhook request/response contract, and the streaming caveat, see Hooks & Middleware.

POST /api/agents//hooks

Add a hook to the agent.

string

required

Agent ID

string

required

When the hook fires. One of: OnRunStart, PreToolUse, OnDelegation, PostToolUse, PreResponse, OnRunComplete. Stored verbatim and not validated; an unrecognized value is saved but never fires.

string

required

What the hook does. One of: http (POST to a webhook URL), rule (local condition evaluation), approval (human-in-the-loop gate). Also stored verbatim and not validated.

object

required

Type-specific configuration (may be {}). For http: url (required), optional headers, timeout_seconds (default 5). For approval: optional message, timeout (default 300). For rule: a condition string or a rules array.

string

Tool name to target. Omit to match all tools (or for non-tool events).

boolean

default:"true"

Whether the hook is active.

integer

default:"0"

Execution order among the agent’s hooks (ascending).

Hooks are immutable; there is no update endpoint. To change a hook, DELETE it and create a new one.

# An HTTP hook that POSTs to your webhook before every tool call
response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers, json={"event": "PreToolUse", "type": "http", "config": {"url": "https://example.com/hook"}})

await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, { method: "POST", headers, body: JSON.stringify({ event: "PreToolUse", type: "http", config: { url: "https://example.com/hook" } }) });

curl -X POST '{BASE_URL}/api/agents/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"event": "PreToolUse", "type": "http", "config": {"url": "https://example.com/hook"}}'

{
  "id": "hook_...",
  "agent_id": "agent_...",
  "event": "PreToolUse",
  "matcher": null,
  "type": "http",
  "config": { "url": "https://example.com/hook" },
  "enabled": true,
  "position": 0,
  "created_at": "2026-01-01T00:00:00Z"
}

GET /api/agents//hooks

List hooks for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, { headers });

curl '{BASE_URL}/api/agents/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/agents//hooks/

Remove a hook from the agent.

string

required

Agent ID

string

required

Hook ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/hooks/{hook_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/hooks/${hookId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/hooks/{hook_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Execution

GET /api/agents//sessions

List chat sessions for the agent. With the service role key, you get every session of the agent; with an end user’s access token, only that user’s own sessions.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/sessions", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/sessions`, { headers });

curl '{BASE_URL}/api/agents/{id}/sessions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents//sessions

Create a session for the agent and return its generated id. This is how an end user starts a conversation before the first run; they can also omit session_id on the first run instead. Accepts the service role key or an end user’s access token.

string

required

Agent ID

string

The user who owns the session (a UUID). Service role key only; an end user who sends it gets 403. With an end user’s token, the session is always owned by that user. With the service role key and no user_id, the session belongs to no end user, so only the service role key can read or continue it.

array

Optional seed conversation (for imports and handoffs), as [{ "role": "user", "content": "..." }, { "role": "assistant", "content": "..." }, ...]: user/assistant pairs, alternating and starting with user, at most 200 messages of at most 20,000 characters each. Seeding with the service role key requires user_id.

# From your backend, owning the session to one of your users
response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/sessions",
    headers=headers,
    json={"user_id": user_id},
)
session_id = response.json()["session_id"]

// From your backend, owning the session to one of your users
const res = await fetch(`${BASE_URL}/api/agents/${agentId}/sessions`, {
  method: "POST", headers, body: JSON.stringify({ user_id: userId }),
});
const { session_id } = await res.json();

curl -X POST '{BASE_URL}/api/agents/{id}/sessions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"user_id": "<user-uuid>"}'

Response (201): { "session_id": "..." }

DELETE /api/agents//sessions/

Delete a session of this agent and its runs. Accepts the service role key or an end user’s access token; an end user can delete only their own sessions. A session that doesn’t exist, belongs to someone else, or belongs to a different agent answers 404.

string

required

Agent ID

string

required

Session ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/sessions/{session_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/sessions/${sessionId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/sessions/{session_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents//run

Run agent synchronously, returning the full response as JSON. No streaming, no tools, no ReAct loop: a single LLM call against the conversation context. Useful for question-answering. If you need tool use, use /run/stream. The endpoint accepts the same context-selection surface as /run/stream: you can attach ad-hoc retrieval (knowledge_bases), a pre-built context (context_handler_id), a raw context string (context_override), or by-reference items (context_items). Only one context source may be provided per request; sending more than one returns 400. runtime_knowledge_bases is not accepted here (it requires the tool loop) — sending it returns 400 pointing you to /run/stream.

string

required

Agent ID

{
  "message": "Hello",
  "session_id": "optional-session-uuid",
  "knowledge_bases": [{ "id": "kb-uuid", "top_k": 5 }],
  "max_context_tokens": 8000,
  "citations_enabled": false
}

Body field	Type	Notes
`message`	string (required)	User input
`session_id`	string	Reuse a session for multi-turn (at most 255 characters). Omit to start a fresh session; `session_id` is returned. With an end user’s token, it must be an existing session of theirs for this agent, or the run answers `404`.
`knowledge_bases`	array	Ad-hoc retrieval: `[{ id, top_k?, similarity_threshold?, filter_metadata?, retrieval_method? }]`. Service role key only.
`context_handler_id`	string	Use a pre-built context handler (see Context Handlers). Service role key only.
`context_override`	string	Raw context string injected verbatim; skips retrieval
`context_items`	array	By-reference items `[{ item_id }]` (service role key only) or by-value items `[{ text, meta? }]`
`max_context_tokens`	int	Truncate retrieved context to this token budget (default from agent settings or platform default)
`citations_enabled`	bool	Append a citation instruction and parse `[1]`-style refs from the response (default `false`)
`temperature`	float	Per-run override; falls back to agent setting
`response_format`	object	LiteLLM-compatible JSON-schema for structured output

Calling with an end user’s access token. This route and /run/stream accept a signed-in user’s token. Their run uses the knowledge bases configured on the agent: knowledge_bases, runtime_knowledge_bases, context_handler_id and by-reference context_items answer 403. They can continue only an existing session of their own and can’t name a new one. The agent’s data tools act as that user. See Rules for end-user runs.

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/run", headers=headers, json={"message": "Hello"})

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/run`, { method: "POST", headers, body: JSON.stringify({ message: "Hello" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/run' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Hello"}'

POST /api/agents//run/stream

Run agent with streaming SSE. Supports tools, the ReAct loop, and multi-turn via session_id. SSE event types include start, chunk, tool_call, tool_result, reasoning, reasoning_summary, and complete; the reasoning events surface the model’s internal thought stream when reasoning is enabled. Set reasoning_requested=true to request reasoning output for this run. The streaming endpoint accepts the same context-selection surface as /run above (knowledge_bases / context_handler_id / context_override / context_items, mutually exclusive), plus all the same max_context_tokens, citations_enabled, temperature, and response_format fields. See Streaming for the full SSE event catalog.

{
  "message": "Hello",
  "session_id": "optional-session-uuid",
  "reasoning_requested": false,
  "runtime_knowledge_bases": [{ "id": "kb-uuid", "top_k": 5 }]
}

Runtime knowledge base references

runtime_knowledge_bases gives the agent a real knowledge_search tool over knowledge bases you name for this one request — agentic search (the model decides when and what to search, and can search repeatedly), without attaching anything to the agent. Use it when a query should be grounded in a document set that isn’t part of the agent’s permanent configuration.

{
  "message": "What does the referenced contract say about termination?",
  "runtime_knowledge_bases": [
    { "id": "kb-uuid", "top_k": 5, "source_ids": ["source-uuid"] }
  ]
}

Entry field	Type	Notes
`id`	string (required)	An existing knowledge base in the project
`top_k`	int	1–100. Per-run override; falls back to the KB’s `retrieval_config`, then the project default
`retrieval_method`	string	`vector_search`, `full_text`, `hybrid`, or `tree_search`
`similarity_threshold`	number	0–1
`filter_metadata`	object	Metadata filter applied at retrieval
`source_ids`	array	Restrict retrieval to these sources — each must be indexed in that entry’s knowledge base
`max_context_tokens`	int	Per-entry knob — distinct from the top-level `max_context_tokens` request field (which caps injected context and is always honored). 1000–128000; honored only when the run’s search tool resolves to exactly one KB (attached + runtime combined)

Behavior to know:

Strictly per-request. Nothing is persisted — follow-up messages in the same session must re-send the field.
Merges with attached KBs into the run’s single knowledge_search tool. An entry naming a KB that is also attached overrides that attachment’s config for the run (e.g. tighten top_k or scope source_ids for one query).
Validated before the stream opens. Unknown ids, out-of-range knobs, unknown entry keys (typos like top_K are rejected, not ignored), more than 10 entries, or duplicate ids all return 400 — no billing, no stream.
Combinable with the context fields above (it adds a tool, not injected context). Combined with the preload knowledge_bases field, the preload retrieval runs up front, plus each knowledge_search call the model makes — both billed, no dedup.
Streaming only. The non-streaming /run has no tool loop and rejects the field with 400.
Service role key only. The field can name any KB in the project, so an end user’s run that sends it answers 403; their runs use the knowledge bases configured on the agent. See Rules for end-user runs.

string

required

Agent ID

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "Hello", "reasoning_requested": True},
    stream=True,
)
for line in response.iter_lines():
    if line and line.decode().startswith("data: "):
        event = json.loads(line.decode()[6:])
        print(event)

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST", headers,
  body: JSON.stringify({ message: "Hello", reasoning_requested: true }),
});
// Parse SSE events: start, chunk, tool_call, tool_result, reasoning, complete

curl -N -X POST '{BASE_URL}/api/agents/{id}/run/stream' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Hello", "reasoning_requested": true}'

GET /api/agents/runs/

Fetch a single agent run by run_id, independent of session context. Returns: id, run_id, session_id, parent_orchestration_run_id, parent_workflow_execution_id, status, input_messages, output_messages, content, usage, retrieved_context, error, started_at, completed_at, steps, events, tool_calls, reasoning_steps, and created_at. The parent fields are null for top-level runs; session_id is null for delegated or workflow-block runs. Accepts the service role key or an end user’s access token. An end user can read only runs in their own sessions; a run in someone else’s session, or in a session your backend created without a user_id, answers 404 rather than 403, to avoid leaking existence.

string

required

Run ID

response = requests.get(f"{BASE_URL}/api/agents/runs/{run_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/runs/${runId}`, { headers });

curl '{BASE_URL}/api/agents/runs/{run_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents/runs//approve

Approve or deny a pending tool call (human-in-the-loop). Accepts the service role key or an end user’s access token. An end user can approve or reject only paused runs they started themselves. A run your backend started with the service role key has no end-user owner, even in a session owned by that user, so only the service role key can approve it: relay the user’s decision from your backend.

string

required

Run ID

{ "approved": true }

response = requests.post(f"{BASE_URL}/api/agents/runs/{run_id}/approve", headers=headers, json={"approved": True})

await fetch(`${BASE_URL}/api/agents/runs/${runId}/approve`, { method: "POST", headers, body: JSON.stringify({ approved: true }) });

curl -X POST '{BASE_URL}/api/agents/runs/{run_id}/approve' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"approved": true}'

Error Responses

Agent routes return {"error": "<message>"}.

Status	Description
400	Missing or invalid required field (e.g. `name`, `tool_type`/`tool_name`, `knowledge_base_id`, MCP server `name`/`url`, hook `event`/`type`/`config`)
400	Invalid `config_override.schemas` on tool PATCH (e.g. not a dict, contains a system schema, has invalid table names, or names something other than a table or `security_invoker` view)
400	`session_id` isn’t a string of at most 255 characters
401	Missing or invalid bearer token; an end-user token without a UUID `sub` or an `exp`
403	An end user’s token on a route that requires the service role key (`{"error": "This endpoint requires the project's service role key"}`)
403	An end user’s run body sets `knowledge_bases`, `runtime_knowledge_bases`, `context_handler_id` or by-reference `context_items`, or an end user sets `user_id` on session create
404	No agent, tool/KB/MCP/hook assignment, or run exists with the given ID
404	`/run` or `/run/stream` with an end user’s token: the supplied `session_id` doesn’t exist or isn’t the caller’s session of this agent (returned as 404 to avoid leaking existence)
409	Knowledge base already assigned to this agent
409	An MCP server with this name already exists for this agent

Getting Started

Concepts

Guides

API Reference

Common Patterns

Agent CRUD

GET /api/agents

POST /api/agents

GET /api/agents/

PATCH /api/agents/

DELETE /api/agents/

Tool Assignments

POST /api/agents//tools

GET /api/agents//tools

PATCH /api/agents//tools/

DELETE /api/agents//tools/

Knowledge Base Assignments

POST /api/agents//knowledge-bases

GET /api/agents//knowledge-bases

DELETE /api/agents//knowledge-bases/

MCP Servers

POST /api/agents//mcp-servers

GET /api/agents//mcp-servers

PUT /api/agents//mcp-servers/

DELETE /api/agents//mcp-servers/

Hooks

POST /api/agents//hooks

GET /api/agents//hooks

DELETE /api/agents//hooks/

Execution

GET /api/agents//sessions

POST /api/agents//sessions

DELETE /api/agents//sessions/

POST /api/agents//run

POST /api/agents//run/stream

Runtime knowledge base references

GET /api/agents/runs/

POST /api/agents/runs//approve

Error Responses

​Common Patterns

​Agent CRUD

​GET /api/agents

​POST /api/agents

​GET /api/agents/

​PATCH /api/agents/

​DELETE /api/agents/

​Tool Assignments

​POST /api/agents//tools

​GET /api/agents//tools

​PATCH /api/agents//tools/

​DELETE /api/agents//tools/

​Knowledge Base Assignments

​POST /api/agents//knowledge-bases

​GET /api/agents//knowledge-bases

​DELETE /api/agents//knowledge-bases/

​MCP Servers

​POST /api/agents//mcp-servers

​GET /api/agents//mcp-servers

​PUT /api/agents//mcp-servers/

​DELETE /api/agents//mcp-servers/

​Hooks

​POST /api/agents//hooks

​GET /api/agents//hooks

​DELETE /api/agents//hooks/

​Execution

​GET /api/agents//sessions

​POST /api/agents//sessions

​DELETE /api/agents//sessions/

​POST /api/agents//run

​POST /api/agents//run/stream

​Runtime knowledge base references

​GET /api/agents/runs/

​POST /api/agents/runs//approve

​Error Responses

Common Patterns

Agent CRUD

GET /api/agents

POST /api/agents

GET /api/agents/

PATCH /api/agents/

DELETE /api/agents/

Tool Assignments

POST /api/agents//tools

GET /api/agents//tools

PATCH /api/agents//tools/

DELETE /api/agents//tools/

Knowledge Base Assignments

POST /api/agents//knowledge-bases

GET /api/agents//knowledge-bases

DELETE /api/agents//knowledge-bases/

MCP Servers

POST /api/agents//mcp-servers

GET /api/agents//mcp-servers

PUT /api/agents//mcp-servers/

DELETE /api/agents//mcp-servers/

Hooks

POST /api/agents//hooks

GET /api/agents//hooks

DELETE /api/agents//hooks/

Execution

GET /api/agents//sessions

POST /api/agents//sessions

DELETE /api/agents//sessions/

POST /api/agents//run

POST /api/agents//run/stream

Runtime knowledge base references

GET /api/agents/runs/

POST /api/agents/runs//approve

Error Responses