# REST API overview > Call Runbear agents and manage your organization from your own code over the REST API, starting with a three-request quickstart. Source: https://docs.runbear.io/api/overview Last updated: 2026-09-30 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](https://api.runbear.io/v1/docs). ## Base URL and reference - **Base URL:** `https://api.runbear.io/v1` - **Interactive reference:** [`https://api.runbear.io/v1/docs`](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](/api/api-keys.md). - 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. ```bash export RUNBEAR_API_KEY="" export 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":""}} # 2. Run a turn and wait for the reply curl -s https://api.runbear.io/v1/threads//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//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](/api/streaming.md). For a single request that creates the thread for you, use `POST /v1/chat/completions`; [Chat](/api/chat.md) 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 | Resource | Operations | What it does | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Threads and runs | `GET`, `POST /v1/threads`; `POST /v1/threads/{threadId}/runs` and `/runs/stream`; `GET /v1/threads/{threadId}/messages` | Conversations with an agent. See [Chat](/api/chat.md) | | Chat | `POST /v1/chat/completions`, `POST /v1/chat/suggestions` | One-call chat, and follow-up suggestions. See [Chat](/api/chat.md) | | Files | `POST /v1/files/upload` | Attachments for a message. See [Files](/api/files.md) | | Sessions | `POST /v1/sessions`, `POST /v1/sessions/refresh` | Browser session passes for the [Web SDK](/api/web-sdk/authentication.md) | | Assistants | `GET /v1/assistants`, `GET` and `PATCH /v1/assistants/{id}` | List agents, and edit name and system prompt | | Agents | `GET`, `POST /v1/agents`; `GET`, `PATCH`, `DELETE /v1/agents/{id}` | Create and configure agents. See [Managing agents via API](/api/agents.md) | | Agent knowledge | `/v1/agents/{id}/knowledge-bases/...` (6 operations) | Website, Google Drive and uploaded-file knowledge | | Agent feedback | `GET /v1/agents/{id}/analytics/feedback` | Response feedback counts | | Tool integrations | `/v1/agents/{id}/tool-integrations/...` (6 operations), `GET /v1/tool-integrations/managed-mcps` | Attach tools to an agent. See [Tool integrations API](/api/tool-integrations.md) | | Hooks | `GET`, `PUT`, `DELETE /v1/agents/{id}/hooks` and `/session-start-hook` | Call your code during a conversation. See [Hooks API](/api/hooks.md) | | Traces | `GET /v1/agents/{id}/traces`, `/traces/export`, `/traces/{traceId}`, `/messages/{messageId}/trace` | What each turn did. See [Traces API](/api/traces.md) | | Credits | `GET /v1/credits/usage`, `/usage/periods`, `/usage/entries` | Credit usage. See [Credits API](/api/credits.md) | | API keys | `GET`, `POST /v1/api-keys`; `PATCH`, `DELETE /v1/api-keys/{id}` | Manage keys. See [Authentication and API keys](/api/api-keys.md#managing-keys-through-the-api) | | AI Gateway | `GET`, `PUT`, `DELETE /v1/ai-gateway` | Route the organization's model traffic through a Cloudflare AI Gateway | | Google Drive service accounts | `GET`, `POST /v1/integrations/google-drive/service-accounts`, `DELETE .../{id}` | Service accounts for Drive knowledge | | Integration suggestions | `GET`, `PUT /v1/integration-suggestions` | Whether 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](/api/streaming.md)). - Ids are UUIDs. Timestamps are ISO 8601. - Most successful calls answer `200`; the exceptions are listed in [Errors and limits](/api/errors-and-limits.md#success-status-codes). - Paginated lists use opaque cursors. Pass back the `nextCursor` you received and stop when it is `null`. ## Related - [Authentication and API keys](/api/api-keys.md) - [Chat](/api/chat.md) and [Streaming](/api/streaming.md) - [Files](/api/files.md) - [Errors and limits](/api/errors-and-limits.md) - [Web SDK](/api/web-sdk.md) — embed an agent in a web page - [MCP server](/api/mcp-server.md) — manage agents from an AI client