Managing agents via API

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. Reading needs no particular capability; creating, changing, and deleting needs the manageAgents capability.
• 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 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=<id>,<id> 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 explains why both names exist.

Endpoints#

Every field is listed in the OpenAPI reference.

Creating an agent#

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, which agents created in the dashboard do.

Configuration#

Knowledge search#

knowledgeSearch tunes how the agent's knowledge search picks results. Sending it without the feature enabled answers 400 with knowledge_search_not_permitted.

System prompt length#

A system prompt can be at most 200,000 characters. Put reference material in a knowledge source 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": "<cause>", "message": "..." } (see Errors and limits). The causes you are most likely to meet:

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.

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:

{
  "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 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.

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.

The PUT body:

{
  "cloudflareAccountId": "<Cloudflare account id>",
  "gatewayName": "runbear",
  "cfApiToken": "<Cloudflare API token>",
  "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 — base URL, quickstart, and every resource
• Tool integrations API — attach tools to the agents you create
• Hooks API — call your own code during an agent's conversations
• Response Components API — interactive components in replies
• Errors and limits — error shapes and rate limits