# Managing agents via API > Create, configure, and delete agents over the REST API, and manage their knowledge sources, Google Drive service accounts, and AI Gateway routing. Source: https://docs.runbear.io/api/agents Last updated: 2026-09-30 The **Agents API** creates and configures agents from your own code: the model and runtime, the system prompt, tool approval, knowledge search, timeouts, and the knowledge sources the agent reads. Use it to provision agents from a script, keep configuration in version control, or build agent management into your own admin tools. ## What you need - An [API key](/api/api-keys.md). Reading needs no particular capability; creating, changing, and deleting needs the [`manageAgents` capability](/api/api-keys.md#capabilities). - For Claude Agent SDK agents, API access to that runtime enabled for your organization. Without it, requests that create or change one answer `400` with `claude_agent_sdk_not_permitted`; contact [support@runbear.io](mailto:support@runbear.io) to enable it. ## Finding agents There are two ways to list agents: - `GET /v1/assistants` lists every agent your key can see, with an optional `name` filter. Start here to find ids. - `GET /v1/agents?ids=,` returns the full configuration of up to 100 agents you name. It requires `ids`. `GET /v1/agents/{agentId}` returns one agent's full configuration. The `/v1/agents` endpoints cover **Anthropic**, **OpenAI Responses**, **Gemini**, and **Claude Agent SDK** agents; other agent types answer `404`. [REST API overview](/api/overview.md#naming-agents-and-assistants) explains why both names exist. ## Endpoints | Endpoint | Purpose | | --------------------------------------------- | ----------------------------------------------------- | | `POST /v1/agents` | Create an agent. Answers `201` with its configuration | | `GET /v1/agents/{agentId}` | Read an agent's configuration | | `PATCH /v1/agents/{agentId}` | Change an agent. Only the fields you send change | | `DELETE /v1/agents/{agentId}` | Delete an agent. This can't be undone | | `GET /v1/agents/{agentId}/analytics/feedback` | Read the agent's response feedback and message counts | Every field is listed in the [OpenAPI reference](https://api.runbear.io/v1/docs). ## Creating an agent ```bash curl -s https://api.runbear.io/v1/agents \ -H "Authorization: Bearer $RUNBEAR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support", "systemPrompt": "You answer questions about Acme products.", "provider": { "type": "anthropic" }, "timeoutMinutes": 10 }' ``` `provider.type` picks the runtime: `anthropic`, `openai-responses`, `gemini`, or `claude-agent-sdk`. It can't change later; a `PATCH` that sends a different type answers `400` with `provider_type_mismatch`. Each provider takes a `model`, and uses Runbear's managed key unless you send `useOwnApiKey: true` with your own `apiKey`. The OpenAPI reference lists the models each provider accepts. A Claude Agent SDK agent takes only a model and an optional API key: it has no `thinking`, `temperature`, or `webSearch` settings. An agent created through the API doesn't get Runbear's [built-in tools](/api/mcp-server.md#built-in-tools-on-an-agent), which agents created in the dashboard do. ## Configuration | Field | What it controls | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The agent's name, 1 to 255 characters | | `systemPrompt` | The agent's instructions, at most 200,000 characters. See [System prompt length](#system-prompt-length) | | `timeoutMinutes` | How long one turn may run, from 1 to 20 minutes; 6 by default. Claude Agent SDK agents have a lower cap; see [Chat](/api/chat.md#how-long-a-turn-can-run) | | `toolProgress.enabled` | Whether tool activity is shown to the person chatting: tool cards in channels and tool events in the [stream](/api/streaming.md). On by default. The agent runs the same tools either way | | `longTermMemory.enabled` | Whether the agent keeps long-term memory. On by default | | `tools.requireApprovalBeforeToolCalls` | Ask for approval before every tool call. When on, it supersedes `tools.requireApprovalForResourceChanges`, which asks only before tools that change something | | `provider.thinking` | Anthropic agents. `{ "type": "enabled", "effort": "..." }` turns on extended thinking; `effort` is `low`, `medium` (the default), `high`, `xhigh`, or `max`. The higher levels use more thinking tokens, and so more credits on the managed key | | `knowledgeSearch` | How knowledge search ranks results. See below | | `responseComponents` | Update only. How often the agent answers with an interactive component. See [Response Components API](/api/response-components.md) | | `aiGateway` | Route this agent's model traffic through a Cloudflare AI Gateway. See [AI Gateway](#ai-gateway) | ### Knowledge search > **Note** > > **Limited availability.** This feature is being rolled out gradually. Contact [support@runbear.io](mailto:support@runbear.io) to enable it for your organization. `knowledgeSearch` tunes how the agent's knowledge search picks results. Sending it without the feature enabled answers `400` with `knowledge_search_not_permitted`. | Field | Meaning | Default | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | | `maxResults` | Documents returned per search, 1 to 50 | 5 | | `scoreThreshold` | Minimum relevance score to include a result, 0 to 1. Lower returns more results | 0.444 | | `semanticWeight` | How much meaning counts against exact keywords, 0 (keywords only) to 1 (meaning only). OpenAI Responses agents ignore it | 0.4 | ### System prompt length A system prompt can be at most 200,000 characters. Put reference material in a [knowledge source](/agents/knowledge/overview.md) rather than in the prompt. On create, a longer prompt fails validation with `400`. On update it answers `400` with `system_prompt_too_long`. An agent whose prompt was already longer than the limit keeps working, and an update may set any prompt no longer than the one it has now. ### Errors Create and update errors use a route-specific body, `{ "error": "", "message": "..." }` (see [Errors and limits](/api/errors-and-limits.md#other-shapes)). The causes you are most likely to meet: | Status | `error` or `code` | When | | ------ | ------------------------------------ | -------------------------------------------------------------------------------- | | `400` | `agent_limit_reached` | Your plan's agent limit is reached. Delete agents or upgrade | | `400` | `claude_agent_sdk_not_permitted` | API access to Claude Agent SDK agents isn't enabled for your organization | | `400` | `provider_type_mismatch` | An update sent a different `provider.type` | | `400` | `system_prompt_too_long` | An update sent a prompt over the limit | | `400` | `knowledge_search_not_permitted` | `knowledgeSearch` was sent without the feature enabled | | `400` | `ai_gateway_unsupported_provider` | `aiGateway` was sent for a provider other than Anthropic or OpenAI Responses | | `403` | `forbidden_ai_gateway_not_permitted` | `aiGateway` was enabled on a plan without AI Gateway | | `404` | `not_found` | The agent doesn't exist in your organization, or the API doesn't manage its type | ## Feedback analytics `GET /v1/agents/{agentId}/analytics/feedback` counts the reactions people left on the agent's replies, each with its share of all messages, alongside the number of messages, the number of distinct users, and the estimated time saved. Narrow it with optional `from` and `to` dates in ISO 8601 form. ## Knowledge sources These endpoints read and set an agent's knowledge sources. Most sources, such as Notion or Confluence, are set up on the agent's **Knowledge** tab; see [Knowledge](/agents/knowledge/overview.md). | Endpoint | Purpose | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `GET /v1/agents/{agentId}/knowledge-bases/website` | Read the website crawl settings and sync status. `404` when none is set | | `PUT /v1/agents/{agentId}/knowledge-bases/website` | Replace the website crawl settings | | `PUT /v1/agents/{agentId}/knowledge-bases/google-drive` | Sync Google Drive files and folders through a service account | | `GET /v1/agents/{agentId}/knowledge-bases/google-drive-service-account` | Read the service-account Drive settings and sync status. `404` when none is set | | `GET /v1/agents/{agentId}/knowledge-bases/google-drive-oauth` | Read the Drive settings connected with a user's own Google sign-in, and their sync status. `404` when none is set | | `GET /v1/agents/{agentId}/knowledge-bases/uploaded-files` | List files uploaded to the agent as knowledge, including ones still being processed | The `PUT` endpoints require the `manageAgents` capability. Each sync status has a `state` (`IN_PROGRESS`, `SUCCESS`, `PARTIAL_SUCCESS`, `FAILED`, or `SUSPENDED`), the time of the last successful sync, and the most recent error, if any. ### Website The `PUT` body is the complete list of sites to crawl: ```json { "configs": [ { "rootUrl": "https://docs.example.com", "excludedUrls": ["https://docs.example.com/internal"] } ] } ``` It replaces what is there. A site already in the list keeps the pages picked for it in the dashboard, and only its `excludedUrls` change; a site not in the list is removed; and an empty `configs` stops crawling altogether. Every successful `PUT` starts a new crawl. Each `rootUrl` may appear once. Anthropic, OpenAI Responses, Gemini, and Claude Agent SDK agents support website knowledge; other types answer `400` with `provider_does_not_support_website_sync`. ### Google Drive through a service account Send the Drive file and folder ids to sync as `fileIds`. If exactly one [service account](#google-drive-service-accounts) is available to the person who owns the API key, it is used; with more than one, pass its id as `integrationId`, or the request answers `400` with `google_drive_sa_ambiguous`. With none, it answers `400` with `google_drive_sa_not_configured`, and a service account the key's owner may not use answers `403` with `code: "forbidden_google_drive_sa"`. ## Google Drive service accounts A Google service account lets agents read Drive files shared with it, without anyone's personal Google sign-in. | Endpoint | Purpose | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GET /v1/integrations/google-drive/service-accounts` | List the organization's service accounts, with how many agents use each | | `POST /v1/integrations/google-drive/service-accounts` | Add a service account. Send its JSON key file as `keyFileContent`, a plain JSON string (not base64). Runbear checks the key against the Drive API before saving it | | `DELETE /v1/integrations/google-drive/service-accounts/{id}` | Remove a service account. Any agent knowledge settings that use it are removed too | `POST` and `DELETE` require the `manageAgents` capability. Only organization admins and the person who added a service account can delete it. ## AI Gateway Available on the Enterprise plan. A Cloudflare AI Gateway sits between Runbear and the model provider, so your organization can watch, cache, and control model traffic in its own Cloudflare account. It applies to Anthropic and OpenAI Responses agents. | Endpoint | Purpose | | ----------------------- | ------------------------------------------------------------------------- | | `GET /v1/ai-gateway` | Read the organization's gateway settings. Answers `204` when none are set | | `PUT /v1/ai-gateway` | Set the organization's gateway | | `DELETE /v1/ai-gateway` | Remove the organization's gateway. Answers `404` when none is set | The `PUT` body: ```json { "cloudflareAccountId": "", "gatewayName": "runbear", "cfApiToken": "", "enabled": true } ``` `cfApiToken` is write-only and is never returned. While `enabled` is `true`, every Anthropic and OpenAI Responses agent routes through the gateway unless it overrides it. An agent overrides the organization's gateway with its own `aiGateway` field on create or update: the same four fields, with `enabled: true`, to use a different gateway, or `{ "enabled": false }` to call the provider directly. When you read the agent, `aiGateway.source` says where its setting comes from: `agent` or `organization`. `PUT` and `DELETE` require the `manageAgents` capability. On a plan without AI Gateway, an agent's `aiGateway` override answers `403` with `code: "forbidden_ai_gateway_not_permitted"`. Until a pending fix ships, the organization endpoints above answer `403` with `{ "error": "forbidden", "message": "..." }` instead of that code. Sending `aiGateway` for a Gemini or Claude Agent SDK agent answers `400` with `ai_gateway_unsupported_provider`. ## Related - [REST API overview](/api/overview.md) — base URL, quickstart, and every resource - [Tool integrations API](/api/tool-integrations.md) — attach tools to the agents you create - [Hooks API](/api/hooks.md) — call your own code during an agent's conversations - [Response Components API](/api/response-components.md) — interactive components in replies - [Errors and limits](/api/errors-and-limits.md) — error shapes and rate limits