Skip to content
Runbear Docs
GitHub

REST API overview

Call Runbear agents and manage your organization from your own code over the REST API, starting with a three-request quickstart.

On this page
Base URL and referenceWhat you needQuickstartNaming: agents and assistantsResource mapConventionsRelated

The Runbear REST API lets your own software talk to your agents: start a conversation, send messages, stream replies, attach files, and manage agents, keys and usage. Use it to put an agent behind your own product, run it from a backend job, or pull its traces and credit usage into your own systems.

These pages explain how the API behaves: authentication, chat, streaming, files, errors and limits. Every request and response field is listed in the OpenAPI reference.

Base URL and reference#

  • Base URL: https://api.runbear.io/v1
  • Interactive reference: https://api.runbear.io/v1/docs
  • Raw OpenAPI 3.1 document: https://api.runbear.io/v1/openapi.json

The API publishes 57 operations. Generate a client from the raw document if your language has an OpenAPI generator, and regenerate it when you pick up new fields.

What you need#

  • An API key for your organization. See Authentication and API keys.
  • The id of the agent you want to call. It is the id in the agent's dashboard URL, and GET /v1/assistants lists every agent your key can see.

Quickstart#

Create a thread for the agent, run a turn on it, then read the thread back.

export RUNBEAR_API_KEY="<your key>"
export AGENT_ID="<agent id>"

# 1. Create a thread
curl -s https://api.runbear.io/v1/threads \
  -H "Authorization: Bearer $RUNBEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"assistant_id\": \"$AGENT_ID\"}"
# => {"thread":{"id":"<thread id>"}}

# 2. Run a turn and wait for the reply
curl -s https://api.runbear.io/v1/threads/<thread id>/runs \
  -H "Authorization: Bearer $RUNBEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"assistant_id\": \"$AGENT_ID\", \"messages\": [{\"role\": \"user\", \"content\": \"What can you help me with?\"}]}"
# => {"message":{"id":"...","content":"..."}}

# 3. Read the conversation
curl -s https://api.runbear.io/v1/threads/<thread id>/messages \
  -H "Authorization: Bearer $RUNBEAR_API_KEY"

To show the reply as it is written, call /runs/stream instead of /runs and read the stream. For a single request that creates the thread for you, use POST /v1/chat/completions; Chat compares the two.

Naming: agents and assistants#

The API is older than the word "agent" in the dashboard, so both names appear. An assistant is an agent: request bodies and query strings name it assistant_id, and responses name it assistantId.

  • /v1/assistants is the original agent resource. GET /v1/assistants is the only endpoint that lists every agent, and takes an optional name filter (case-insensitive, partial match).
  • /v1/agents is the full management resource. GET /v1/agents does not list everything: it requires ids, a comma-separated list of 1 to 100 agent ids, and answers 400 without it.
  • PATCH /v1/assistants/{id} writes its description field into the agent's system prompt, not into a short description.

Resource map#

ResourceOperationsWhat it does
Threads and runsGET, POST /v1/threads; POST /v1/threads/{threadId}/runs and /runs/stream; GET /v1/threads/{threadId}/messagesConversations with an agent. See Chat
ChatPOST /v1/chat/completions, POST /v1/chat/suggestionsOne-call chat, and follow-up suggestions. See Chat
FilesPOST /v1/files/uploadAttachments for a message. See Files
SessionsPOST /v1/sessions, POST /v1/sessions/refreshBrowser session passes for the Web SDK
AssistantsGET /v1/assistants, GET and PATCH /v1/assistants/{id}List agents, and edit name and system prompt
AgentsGET, POST /v1/agents; GET, PATCH, DELETE /v1/agents/{id}Create and configure agents. See Managing agents via API
Agent knowledge/v1/agents/{id}/knowledge-bases/... (6 operations)Website, Google Drive and uploaded-file knowledge
Agent feedbackGET /v1/agents/{id}/analytics/feedbackResponse feedback counts
Tool integrations/v1/agents/{id}/tool-integrations/... (6 operations), GET /v1/tool-integrations/managed-mcpsAttach tools to an agent. See Tool integrations API
HooksGET, PUT, DELETE /v1/agents/{id}/hooks and /session-start-hookCall your code during a conversation. See Hooks API
TracesGET /v1/agents/{id}/traces, /traces/export, /traces/{traceId}, /messages/{messageId}/traceWhat each turn did. See Traces API
CreditsGET /v1/credits/usage, /usage/periods, /usage/entriesCredit usage. See Credits API
API keysGET, POST /v1/api-keys; PATCH, DELETE /v1/api-keys/{id}Manage keys. See Authentication and API keys
AI GatewayGET, PUT, DELETE /v1/ai-gatewayRoute the organization's model traffic through a Cloudflare AI Gateway
Google Drive service accountsGET, POST /v1/integrations/google-drive/service-accounts, DELETE .../{id}Service accounts for Drive knowledge
Integration suggestionsGET, PUT /v1/integration-suggestionsWhether agents suggest connecting apps they don't have yet

Conventions#

  • Requests and responses are JSON, except file upload (multipart) and the two streaming routes (NDJSON).
  • Ids are UUIDs. Timestamps are ISO 8601.
  • Most successful calls answer 200; the exceptions are listed in Errors and limits.
  • Paginated lists use opaque cursors. Pass back the nextCursor you received and stop when it is null.