API Reference

This reference describes the supported customer integration and configuration API. Admin-assistant helpers and other routes used only by the first-party Admin application are intentionally not an external integration contract.

For request and response details that are easiest to understand as a complete workflow, use the linked feature guides alongside this route reference.

Base URL and content types

Set the root origin for your Cloud workspace or Enterprise deployment:

export SYNTHETICBREW_URL="https://YOUR_SYNTHETICBREW_ORIGIN"
export SYNTHETICBREW_TOKEN="bb_your_token"

Protected REST requests use JSON unless a route says otherwise:

curl "$SYNTHETICBREW_URL/api/v1/agents" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Accept: application/json"

• JSON request: Content-Type: application/json
• Config import: Content-Type: application/x-yaml
• File upload: multipart/form-data
• Chat streaming response: text/event-stream
• Config export: YAML
• Enterprise metrics: Prometheus text format

Authentication

Create scoped keys in Admin -> API Keys. The API accepts those keys and valid signed JWTs as Bearer tokens:

Authorization: Bearer bb_your_api_token

An API key cannot call the key-management routes. POST /api/v1/auth/tokens, GET /api/v1/auth/tokens, and DELETE /api/v1/auth/tokens/{id} require the authenticated Admin session used by the dashboard.

Scopes

Scope	Grants
chat	Schema chat.
tasks	Task creation, reads, transitions, and cancellation.
agents:read, agents:write	Agent, capability, and knowledge resource reads or writes.
models:read, models:write	Model reads or writes.
mcp:read, mcp:write	MCP server reads or writes.
schemas:read, schemas:write	Schema, relation, and schema-memory reads or writes.
sessions:read, sessions:write	Session reads or writes.
settings:read, settings:write	Settings reads or writes.
audit:read	Audit-log reads.
resilience:read, resilience:write	Circuit-breaker reads or resets.
tools:read	Built-in tool metadata.
config	Config reload, import, and export.
api	Chat, tasks, sessions read, and read-only agent, model, MCP, schema, settings, audit, resilience, and tool access. It does not grant configuration writes.
provision	MCP provisioning reads plus create/update authority. It excludes destructive MCP management tools.
manage	Everything in provision plus destructive MCP management authority.
admin	Administrative superscope. Grant only to trusted operators.

The short aliases agents, models, mcp, schemas, sessions, settings, audit, resilience, and tools mean read-only access to that resource.

Enterprise local sessions

When an Enterprise deployment explicitly enables local authentication, the local session endpoints are available:

Method	Path	Purpose
POST	/api/v1/auth/local-session	Issue a local Admin session.
POST	/api/v1/auth/local-session/refresh	Refresh that session.

These routes are deployment-local access helpers, not a Cloud authentication mechanism. See Enterprise on-premises for authentication choices.

Anonymous discovery and health

Method	Path	Purpose
GET	/api/v1/health	Liveness/readiness information, version, agent count, and platform-default-model availability.
GET	/api/v1/models/registry	Read the built-in model catalog; filter by provider, tier, or supports_tools.
GET	/api/v1/models/registry/providers	List known provider metadata.
GET	/.well-known/mcp/server-card.json	Discover the authenticated management MCP server and its capabilities.
GET	/agent-setup/prompt.md	Read the generated coding-agent setup instructions for this deployment.
GET	/widget.js	Load the embeddable chat-widget bundle when it is installed in the deployment image.

The registry is a catalog, not your workspace’s configured model list. Use GET /api/v1/models for configured models.

OAuth discovery for coding agents

When the OAuth authorization server is enabled, an MCP client uses these endpoints:

Method	Path	Purpose
GET	/.well-known/oauth-authorization-server	Authorization-server metadata.
GET	/.well-known/oauth-protected-resource	Protected-resource metadata.
GET	/.well-known/oauth-protected-resource/api/v1/mcp/rpc	Resource-specific metadata for the MCP endpoint.
POST	/oauth/register	Dynamic client registration.
POST	/oauth/token	Authorization-code exchange or refresh.
POST	/api/v1/oauth/register	Edge-compatible alias for dynamic registration.
POST	/api/v1/oauth/token	Edge-compatible alias for token exchange or refresh.
GET	/api/v1/oauth/authorize-info	Authorization request information used by the browser consent UI.

Authorization codes are single-use and expire after five minutes. Let the coding agent’s OAuth client perform registration and exchange; do not script the Admin-only consent approval or exchange-status routes. For browsers and coding agents on different machines, follow Connect a coding agent.

Chat

Method	Path	Scope	Purpose
POST	/api/v1/schemas/{name}/chat	chat	Send a message or resume an interrupt. Streams SSE by default.

{name} is the immutable schema name, never its UUID. The schema must have chat enabled and an entry agent. The request body accepts message, session_id, stream, user_sub, headers, or resume_interrupt as described in REST API chat integration.

Agents and capabilities

Method	Path	Scope	Purpose
GET	/api/v1/agents	agents:read	List agents.
GET	/api/v1/agents/{name}	agents:read	Read an agent.
POST	/api/v1/agents	agents:write	Create an agent.
PUT	/api/v1/agents/{name}	agents:write	Fully replace an agent’s writable configuration.
PATCH	/api/v1/agents/{name}	agents:write	Update selected agent fields.
DELETE	/api/v1/agents/{name}	agents:write	Delete an agent.
GET	/api/v1/agents/{name}/lifecycle	agents:read	Inspect runtime lifecycle state when lifecycle management is enabled.
GET	/api/v1/agents/{name}/capabilities	agents:read	List capability bindings.
POST	/api/v1/agents/{name}/capabilities	agents:write	Add a capability binding.
PUT	/api/v1/agents/{name}/capabilities/{capId}	agents:write	Replace a capability binding.
DELETE	/api/v1/agents/{name}/capabilities/{capId}	agents:write	Remove a capability binding.

Agent names are stable URL handles. can_spawn is derived from schema delegation relations and is read-only; create or remove a relation instead of writing that field. Use PATCH for partial changes. PUT requires the complete writable resource.

See Agents and Multi-agent systems.

Models

Method	Path	Scope	Purpose
GET	/api/v1/models	models:read	List configured models.
POST	/api/v1/models	models:write	Create a model.
PUT	/api/v1/models/{name}	models:write	Fully replace a model.
PATCH	/api/v1/models/{name}	models:write	Update selected model fields.
DELETE	/api/v1/models/{name}	models:write	Delete a model.
POST	/api/v1/models/{name}/verify	models:write	Test connectivity and tool-calling support.

Accepted input types are ollama, openai_compatible, anthropic, azure_openai, and openrouter. openrouter is an input alias stored as openai_compatible; it defaults the base URL to OpenRouter when one is not supplied. Model kind is chat or embedding.

curl -X POST "$SYNTHETICBREW_URL/api/v1/models" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"primary-model",
    "type":"openrouter",
    "kind":"chat",
    "model_name":"anthropic/claude-sonnet-4",
    "api_key":"YOUR_PROVIDER_KEY"
  }'

See Models and Model selection.

Tasks

Method	Path	Scope	Purpose
POST	/api/v1/tasks	tasks	Create a task.
GET	/api/v1/tasks	tasks	List tasks.
GET	/api/v1/tasks/{id}	tasks	Read task detail.
DELETE	/api/v1/tasks/{id}	tasks	Cancel a non-terminal task; optional body {"reason":"..."}.
GET	/api/v1/tasks/{id}/subtasks	tasks	List direct subtasks.
POST	/api/v1/tasks/{id}/approve	tasks	Transition draft to approved.
POST	/api/v1/tasks/{id}/start	tasks	Transition approved or pending to in_progress.
POST	/api/v1/tasks/{id}/complete	tasks	Complete in-progress work; optional result.
POST	/api/v1/tasks/{id}/fail	tasks	Fail in-progress work; requires reason.
POST	/api/v1/tasks/{id}/priority	tasks	Set priority 0, 1, or 2.

Create a task:

curl -X POST "$SYNTHETICBREW_URL/api/v1/tasks" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title":"Prepare the launch brief",
    "description":"Draft a brief and verify every launch dependency.",
    "agent_name":"researcher",
    "mode":"background",
    "priority":1,
    "acceptance_criteria":["Sources linked","Dependencies verified"],
    "blocked_by":[],
    "require_approval":true
  }'

{
  "task_id": "8e449f4d-3b78-4e6f-85e6-ea4901670528",
  "status": "draft"
}

mode is interactive or background. Priority is 0 (normal), 1 (high), or 2 (critical). parent_task_id creates a subtask. Without approval the initial status is pending; with require_approval: true it is draft.

List query parameters are source, agent_name, status, page, and per_page. The default and maximum page size are 100. Responses use {data,total,page,per_page,total_pages}. Task IDs and blocker IDs are UUIDs.

Current limitation: agent_name is required in the create body, but the task does not retain it. The agent_name and source response fields are therefore empty, and those two list parameters do not narrow results. status and pagination do work. Use session, audit, or tool-call data when you need attribution.

See Tasks and lifecycle.

Schemas, relations, and memory

Method	Path	Scope	Purpose
GET	/api/v1/schemas	schemas:read	List schemas.
GET	/api/v1/schemas/{name}	schemas:read	Read a schema by name.
POST	/api/v1/schemas	schemas:write	Create a schema.
PUT	/api/v1/schemas/{name}	schemas:write	Fully replace a schema.
PATCH	/api/v1/schemas/{name}	schemas:write	Update selected schema fields.
DELETE	/api/v1/schemas/{name}	schemas:write	Delete a schema.
GET	/api/v1/schemas/{name}/agents	schemas:read	List schema members derived from relations.
GET	/api/v1/schemas/{name}/agent-relations	schemas:read	List delegation relations.
GET	/api/v1/schemas/{name}/agent-relations/{relationId}	schemas:read	Read a relation.
POST	/api/v1/schemas/{name}/agent-relations	schemas:write	Create a source-to-target relation.
PUT	/api/v1/schemas/{name}/agent-relations/{relationId}	schemas:write	Replace a relation.
DELETE	/api/v1/schemas/{name}/agent-relations/{relationId}	schemas:write	Delete a relation.
GET	/api/v1/schemas/{name}/memory	schemas:read	List persistent memory entries.
DELETE	/api/v1/schemas/{name}/memory	schemas:write	Clear schema memory.
DELETE	/api/v1/schemas/{name}/memory/{entry_id}	schemas:write	Delete one memory entry.

Schema membership is derived from agent relations; there is no separate membership write route. A relation’s source agent may delegate to its target agent.

See Schemas and session versus persistent memory.

Sessions

Method	Path	Scope	Purpose
GET	/api/v1/sessions	sessions:read	List sessions by user, status, or time. The accepted agent_name parameter currently does not narrow results because sessions do not retain agent assignment.
GET	/api/v1/sessions/{id}	sessions:read	Read session metadata.
GET	/api/v1/sessions/{id}/messages	sessions:read	Read persisted events.
POST	/api/v1/sessions	sessions:write	Create a session record.
PUT	/api/v1/sessions/{id}	sessions:write	Update title, status, or opaque metadata.
DELETE	/api/v1/sessions/{id}	sessions:write	Delete a session.

List filters are agent_name, user_sub, status, from, to, page, and per_page. The default page size is 20 and the maximum is 100. The response uses {data,total,page,per_page,per_page_max,total_pages}. Session IDs must be UUIDs and metadata writes are capped at 16 KB.

Regular end-user JWTs are restricted to their own user_sub. Admin sessions and trusted API-token services can access all sessions in the workspace. See REST API chat integration for examples and the response shape.

Knowledge bases and files

Knowledge uploads are stateless HTTP operations: upload a file in one request, retain the returned file identifier, and query the resource afterward. The upload request itself does not create a long-running client session.

Method	Path	Scope	Purpose
GET	/api/v1/knowledge-bases	agents:read	List knowledge bases.
GET	/api/v1/knowledge-bases/{name}	agents:read	Read a knowledge base.
POST	/api/v1/knowledge-bases	agents:write	Create a knowledge base.
PUT	/api/v1/knowledge-bases/{name}	agents:write	Fully replace a knowledge base.
PATCH	/api/v1/knowledge-bases/{name}	agents:write	Update selected knowledge-base fields.
DELETE	/api/v1/knowledge-bases/{name}	agents:write	Delete a knowledge base.
POST	/api/v1/knowledge-bases/{name}/agents/{agent_name}	agents:write	Link an agent.
DELETE	/api/v1/knowledge-bases/{name}/agents/{agent_name}	agents:write	Unlink an agent.
GET	/api/v1/knowledge-bases/{name}/files	agents:read	List files.
GET	/api/v1/knowledge-bases/{name}/files/{file_id}	agents:read	Read file metadata.
POST	/api/v1/knowledge-bases/{name}/files	agents:write	Upload and index a file.
DELETE	/api/v1/knowledge-bases/{name}/files/{file_id}	agents:write	Delete a file and its indexed chunks.

The agent-scoped compatibility routes remain available for existing integrations:

Method	Path	Scope	Purpose
GET	/api/v1/agents/{name}/knowledge/status	agents:read	Read the agent’s knowledge status.
GET	/api/v1/agents/{name}/knowledge/files	agents:read	List agent-scoped files.
POST	/api/v1/agents/{name}/knowledge/files	agents:write	Upload a file through the compatibility surface.
DELETE	/api/v1/agents/{name}/knowledge/files/{file_id}	agents:write	Delete an agent-scoped file.

Prefer named knowledge bases for new integrations because they support many-to-many agent linking. See Knowledge.

Knowledge graphs

Method	Path	Scope	Purpose
GET	/api/v1/knowledge-graphs	agents:read	List bundles.
GET	/api/v1/knowledge-graphs/{bundle}	agents:read	Read bundle metadata.
GET	/api/v1/knowledge-graphs/{bundle}/schemas	agents:read	List entity schemas.
GET	/api/v1/knowledge-graphs/{bundle}/schemas/{entity_type}	agents:read	Read one entity schema.
PUT	/api/v1/knowledge-graphs/{bundle}/schemas/{entity_type}	agents:write	Create or replace an entity schema.
GET	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}	agents:read	List and filter entities.
POST	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/batch-get	agents:read	Read several entities by ID.
GET	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}	agents:read	Read one entity.
POST	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}	agents:write	Create one entity.
PUT	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}	agents:write	Replace one entity.
DELETE	/api/v1/knowledge-graphs/{bundle}/entities/{entity_type}/{id}	agents:write	Idempotently delete one entity and report whether it existed.
POST	/api/v1/knowledge-graphs/{bundle}/import	agents:write	Apply a complete bundle payload.
DELETE	/api/v1/knowledge-graphs/{bundle}	agents:write	Delete a bundle.

A bundle import is a full reconciliation: records absent from the payload are removed. Through the MCP provisioning server, importing over an existing bundle also requires replace_existing: true and a token with manage authority; use entity upserts when you intend to preserve other records. REST callers must likewise treat the import as destructive even though the REST route is guarded by agents:write.

Equality filters are coerced to the field’s declared JSON type. Invalid boolean or numeric values return 400 instead of comparing as strings. See Knowledge Graphs for payloads, all nine MCP tools, capability binding, and brewctl examples.

MCP server configuration and provisioning

Method	Path	Scope	Purpose
GET	/api/v1/mcp-servers	mcp:read	List configured MCP servers.
POST	/api/v1/mcp-servers	mcp:write	Create a server.
PUT	/api/v1/mcp-servers/{name}	mcp:write	Fully replace a server.
PATCH	/api/v1/mcp-servers/{name}	mcp:write	Update selected server fields.
DELETE	/api/v1/mcp-servers/{name}	mcp:write	Delete a server.
POST	/api/v1/mcp-servers/{name}/refresh	mcp:write	Re-run tools/list and replace the cached catalog without reconnecting.
GET	/api/v1/mcp/catalog	Authenticated	List the built-in MCP catalog.
POST	/api/v1/mcp/rpc	provision or manage	Streamable-HTTP JSON-RPC endpoint for coding-agent provisioning tools.

Tool-level checks on /api/v1/mcp/rpc separate non-destructive provisioning from destructive management. A provision token can list, create, and update supported resources; delete tools and destructive existing-bundle replacement require manage.

See MCP Servers and Connect a coding agent.

Configuration and settings

Method	Path	Scope	Purpose
POST	/api/v1/config/reload	config	Reload tenant configuration so externally changed resources become available without a service restart.
GET	/api/v1/config/export	config	Export YAML without secrets.
POST	/api/v1/config/import	config	Import YAML configuration.
GET	/api/v1/settings	settings:read	List tenant settings.
PUT	/api/v1/settings/{key}	settings:write	Update one setting.

Config import and export include agents, models, MCP servers, schemas and relations, and Knowledge Graph bundles. Settings are managed through their own API and are not part of this YAML bundle. Keep secrets in the deployment secret store or Admin credential fields; exported configuration does not reveal them.

Configuration export and brewctl kg pull each include at most 500 entities per Knowledge Graph entity type. For a complete copy of a larger graph, keep the maintained bundle source or paginate the entity-list endpoint until every record is exported. Import commits models, MCP servers, agents, and schemas before applying Knowledge Graphs, so a graph error does not undo earlier successful sections.

See Configuration management and Settings and BYOK.

Audit, usage, tools, and resilience

Method	Path	Scope	Purpose
GET	/api/v1/audit	audit:read	Query the audit log and filters.
GET	/api/v1/audit/tool-calls	Authenticated	Query paginated tool-call events.
GET	/api/v1/usage	Authenticated	Read the usage totals available for the current deployment.
GET	/api/v1/admin/usage-limits	admin	List configured tenant and per-user usage limits.
PUT	/api/v1/admin/usage-limits	admin	Create or replace one usage-limit scope.
DELETE	/api/v1/admin/usage-limits/{scope}	admin	Remove the tenant or per_user limit.
GET	/api/v1/tools/metadata	tools:read	List built-in tool metadata.
GET	/api/v1/resilience/circuit-breakers	resilience:read	List circuit-breaker states.
POST	/api/v1/resilience/circuit-breakers/{name}/reset	resilience:write	Reset a circuit breaker.
GET	/metrics	Enterprise deployment	Read Prometheus-format metrics when enabled for the deployment.

Tool-call filters are session_id, agent, tool, status, user_id, from, to, page, and per_page; its default page size is 50 and maximum is 100. Protect /metrics with network policy or a reverse proxy.

Usage limits are operator controls rather than request-rate counters. See Usage limits for their rolling-window semantics and 402 behavior.

SyntheticBrew does not expose a rate-limit usage route. Cloud traffic limits are managed by SyntheticBrew, while Enterprise administrators configure request limits at their ingress or reverse proxy.

Errors and update semantics

Errors use an appropriate HTTP status and a JSON error body. Common statuses are 400 for invalid input, 401 for missing authentication, 403 for insufficient scope, 404 for unavailable resources or resources not visible to the caller, and 409 for state conflicts.

Unless a section states otherwise:

• POST creates or performs an explicit action;
• PUT is a full replacement and requires the resource’s required fields;
• PATCH changes only supplied fields;
• successful DELETE operations may return an empty response;
• names in URL paths are stable resource names, while {id}, {relationId}, {capId}, file_id, and entry_id are identifiers returned by the API.

What’s next

• Bootstrap and GitOps
• REST API chat integration
• API keys and OAuth
• Enterprise operations