API Reference

Complete REST API reference for the ByteBrew Engine. All endpoints return JSON (except SSE streams) and accept JSON request bodies.

Deploying from scratch?

If you are looking to provision a full ByteBrew installation — models, agents, schemas, and MCP servers — from a script or CI pipeline, see the Bootstrap & GitOps guide. It covers the correct order of operations, an idempotent upsert pattern, and a complete working bash script.

Authentication

All API requests must include a valid Ed25519-signed JWT or an API token in the Authorization header. The engine verifies every token with its Ed25519 public key — the password-based /auth/login endpoint has been removed.

Getting a JWT (self-hosted, local auth mode)

With BYTEBREW_AUTH_MODE=local (the default) the engine auto-generates an Ed25519 keypair on first boot and mints tokens on demand:

curl -X POST http://localhost:8443/api/v1/auth/local-session

{"access_token": "eyJhbG...", "expires_at": "2026-03-23T07:00:00Z"}

The returned JWT can be used in the Authorization: Bearer <token> header for all subsequent requests.

Getting a JWT (Cloud / external auth)

In Cloud or any deployment with BYTEBREW_AUTH_MODE=external, the engine does not issue tokens itself. Obtain the JWT from your auth provider (ByteBrew Cloud API or your own IdP that signs with the engine’s configured Ed25519 public key) and pass it in the Authorization header.

Creating a persistent API token

For long-lived integrations, create API tokens through the Admin Dashboard:

• Navigate to Admin Dashboard -> API Keys
• Click “Create API Key” and select the scopes you need
• Copy the token immediately — it is shown only once and cannot be recovered
• Tokens are prefixed with bb_ for easy identification in logs and config

Using the token

# curl
curl http://localhost:8443/api/v1/agents \
  -H "Authorization: Bearer bb_your_api_token"

// JavaScript (fetch)
const response = await fetch('http://localhost:8443/api/v1/agents', {
  headers: { 'Authorization': 'Bearer bb_your_api_token' },
});

# Python (requests)
import requests
response = requests.get(
    'http://localhost:8443/api/v1/agents',
    headers={'Authorization': 'Bearer bb_your_api_token'},
)

Token scopes

Scope	Description
chat	Send messages to schemas (POST /api/v1/schemas/{name}/chat) and respond to user input
tasks	Create, list, cancel tasks and provide input
agents:read	List and inspect agent configurations
agents:write	Create, update, and delete agents
models:read	List and inspect model configurations
models:write	Create, update, delete, and verify models
mcp:read	List MCP server configurations
mcp:write	Create, update, and delete MCP servers
config	Reload, export, and import configuration
admin	Full access to all endpoints including API key management, settings, tokens, sessions, and audit

Least privilege

Create separate tokens for different integrations. A chatbot frontend only needs chat scope. A CI/CD pipeline might need config for hot-reload. A monitoring dashboard might use agents:read + models:read. Use admin scope only for the Admin Dashboard and management scripts.

Error responses

// 401 Unauthorized — missing or invalid token
{"error": "unauthorized", "message": "Invalid or expired API token"}

// 403 Forbidden — token lacks required scope
{"error": "forbidden", "message": "Token does not have 'config' scope"}

Base URL: http://localhost:8443/api/v1

Content-Type: application/json

Chat (SSE Streaming)

Send a message to a schema and receive a stream of Server-Sent Events. This is the primary endpoint for building conversational interfaces. The schema must have Chat Enabled toggled on in Admin Dashboard → Schemas.

POST /api/v1/schemas/{name}/chat

The {name} is the schema name (a DNS-label like support-handbook), visible in Admin Dashboard → Schemas or returned by GET /api/v1/schemas. Schema names are declared in your configuration and are immutable post-create.

Request body

Parameter	Default	Description
message *	—	The user message to send to the agent.
session_id	auto-generated	Session ID for continuing a conversation. Omit to start a new session.

Full example

# Start a new conversation
curl -N http://localhost:8443/api/v1/schemas/support-handbook/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "What laptops do you have under $1000?"}'

SSE event types

Event	Description
thinking	Internal reasoning text (if the model supports it).
message_delta	Text chunk from the agent. Concatenate all deltas for the full response.
message	Complete message (sent after all deltas).
tool_call	Agent is executing a tool. For spawn_* calls, the sub-agent runs synchronously and the result returns via tool_result.
tool_result	Tool execution result. Contains the output returned by the tool.
structured_output	Structured data block emitted by show_structured_output (table, info, or form). Client renders the block; form answers arrive as the next chat message.
confirmation	Interactive pause — a confirm_before approval gate. Contains call_id for the respond endpoint.
error	An error occurred during processing.
done	Stream is complete. Contains session_id.

Example response stream

event: message_delta
data: {"content":"I found several laptops under $1000. "}

event: tool_call
data: {"tool":"search_products","input":{"query":"laptops under 1000","limit":"5"}}

event: tool_result
data: {"tool":"search_products","output":"[{\"name\":\"ProBook 450\",\"price\":849}...]"}

event: message_delta
data: {"content":"Here are the top options:\n\n1. **ProBook 450** — $849..."}

event: message
data: {"content":"I found several laptops under $1000. Here are the top options:\n\n1. **ProBook 450** — $849..."}

event: done
data: {"session_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

Continue the conversation

curl -N http://localhost:8443/api/v1/schemas/support-handbook/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me more about the ProBook 450", "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Agents

List and inspect configured agents. Requires agents:read or admin scope.

# List all agents
curl http://localhost:8443/api/v1/agents \
  -H "Authorization: Bearer bb_your_token"

[
  {
    "name": "sales-agent",
    "model": "glm-5",
    "lifecycle": "persistent",
    "tools_count": 5,
    "has_knowledge": true
  }
]

# Get agent details
curl http://localhost:8443/api/v1/agents/sales-agent \
  -H "Authorization: Bearer bb_your_token"

{
  "name": "sales-agent",
  "model": "glm-5",
  "lifecycle": "persistent",
  "tools": ["knowledge_search", "search_products", "create_order"],
  "mcp_servers": ["crm-api"],
  "can_spawn": ["researcher"],
  "max_steps": 50,
  "max_context_size": 16000
}

Create Agent

curl -X POST http://localhost:8443/api/v1/agents \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "system": "You are a helpful assistant.",
    "model": "glm-5",
    "tools": ["knowledge_search"],
    "can_spawn": ["researcher"],
    "lifecycle": "persistent",
    "max_steps": 50
  }'

Update Agent

curl -X PUT http://localhost:8443/api/v1/agents/my-agent \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"system": "Updated prompt.", "max_steps": 100}'

Delete Agent

curl -X DELETE http://localhost:8443/api/v1/agents/my-agent \
  -H "Authorization: Bearer bb_your_token"
# Returns 204 No Content

Models

CRUD for LLM model providers. Requires admin scope.

List Models

curl http://localhost:8443/api/v1/models \
  -H "Authorization: Bearer bb_your_token"

[
  {
    "id": 1,
    "name": "qwen3",
    "type": "ollama",
    "base_url": "http://localhost:11434",
    "model_name": "qwen3:30b-a3b",
    "has_api_key": false,
    "created_at": "2026-03-20T12:00:00Z"
  }
]

Create Model

curl -X POST http://localhost:8443/api/v1/models \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-model",
    "type": "ollama",
    "model_name": "llama3.2",
    "base_url": "http://localhost:11434",
    "api_key": "ollama"
  }'

Supported types: ollama, openai_compatible, anthropic, azure_openai, google, openrouter, deepseek, mistral, xai, zai.

Note

Models are resolved dynamically — no Engine restart needed after adding a model. The next chat request will use the new model immediately.

Update Model

curl -X PUT http://localhost:8443/api/v1/models/my-model \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "new-key", "model_name": "qwen3:70b"}'

API key is only updated if a non-empty value is provided.

Delete Model

curl -X DELETE http://localhost:8443/api/v1/models/my-model \
  -H "Authorization: Bearer bb_your_token"
# Returns 204 No Content

Verify Model Connectivity

Test that a model is accessible and supports tool calling before using it.

curl -X POST http://localhost:8443/api/v1/models/my-model/verify \
  -H "Authorization: Bearer bb_your_token"

{
  "connectivity": "ok",
  "tool_calling": "supported",
  "response_time_ms": 1240,
  "model_name": "llama3.2",
  "provider": "ollama",
  "error": null
}

Field	Values	Description
connectivity	ok, error	Whether the API endpoint is accessible
tool_calling	supported, not_detected, skipped	Whether the model generates tool calls
response_time_ms	number	Latency of the ping request
error	string or null	Error details if connectivity failed

Tip

For known providers (OpenAI, Anthropic, Google, Mistral), tool calling probe is skipped — all their models support it. Probe runs only for Ollama and custom providers.

Session Respond

When an agent reaches a confirm_before gate, the client receives a confirmation SSE event. Use this endpoint to send the user’s approval or rejection back to the agent.

curl -X POST http://localhost:8443/api/v1/sessions/{session_id}/respond \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "conf_abc123",
    "answers": ["approve"]
  }'

The call_id comes from the SSE event’s metadata. The agent receives the answer and continues execution.

Note

This endpoint handles confirm_before approval gates. For show_structured_output form mode, the user’s answers arrive as the next regular chat message — no respond endpoint needed.

Sessions

Manage conversation sessions. Sessions store the full message history between a user and an agent. Requires chat or admin scope.

# List sessions (with optional filters)
curl "http://localhost:8443/api/v1/sessions?agent=sales-agent&limit=10" \
  -H "Authorization: Bearer bb_your_token"

{
  "sessions": [
    {
      "id": "a1b2c3d4",
      "agent": "sales-agent",
      "created_at": "2025-03-19T10:00:00Z",
      "message_count": 12
    }
  ]
}

# Get session with messages
curl http://localhost:8443/api/v1/sessions/a1b2c3d4 \
  -H "Authorization: Bearer bb_your_token"

# Delete session
curl -X DELETE http://localhost:8443/api/v1/sessions/a1b2c3d4 \
  -H "Authorization: Bearer bb_your_token"

Tasks

Create and manage agent tasks. Tasks are units of work that agents process asynchronously — they can be created by users, triggers, or other agents. Requires tasks or admin scope.

# Create a task
curl -X POST http://localhost:8443/api/v1/tasks \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "researcher",
    "title": "Market analysis Q1",
    "description": "Analyze Q1 2025 market trends for the SaaS sector"
  }'

{
  "id": "task_abc123",
  "agent": "researcher",
  "title": "Market analysis Q1",
  "status": "pending",
  "created_at": "2025-03-19T14:30:00Z"
}

# List tasks with filters
curl "http://localhost:8443/api/v1/tasks?status=pending&agent=researcher" \
  -H "Authorization: Bearer bb_your_token"

# Get task details
curl http://localhost:8443/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer bb_your_token"

# Cancel a task (pending or in_progress only)
curl -X DELETE http://localhost:8443/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer bb_your_token"

Task statuses

Status	Description
pending	Task created, waiting to be picked up by the agent.
in_progress	Agent is actively working on the task.
needs_input	Agent paused and waiting for user input (e.g., confirmation).
completed	Task finished successfully.
failed	Task failed due to an error.
cancelled	Task was cancelled by a user or API call.

Config

Manage engine configuration at runtime. Hot-reload applies changes without restarting the engine. Export/import enable GitOps workflows. Requires config or admin scope.

# Hot-reload configuration from the database
curl -X POST http://localhost:8443/api/v1/config/reload \
  -H "Authorization: Bearer bb_your_token"

# Response
# {"status":"ok","agents_loaded":4,"models_loaded":3}

# Export current config as YAML (secrets are excluded)
curl http://localhost:8443/api/v1/config/export \
  -H "Authorization: Bearer bb_your_token" \
  -o config-backup.yaml

# Import YAML config (merges with existing)
curl -X POST http://localhost:8443/api/v1/config/import \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @new-config.yaml

# Response
# {"status":"ok","agents_imported":2,"models_imported":1,"tools_imported":3}

Health

Check engine status. No authentication required — useful for load balancer health checks.

curl http://localhost:8443/api/v1/health

{
  "status": "ok",
  "version": "1.0.0",
  "agents_count": 4,
  "uptime": "2h34m12s"
}

BYOK Headers (per-request model override)

Bring Your Own Key lets API consumers override the model for a single request. This must be enabled in Settings for each provider. Useful for multi-tenant deployments where each customer provides their own API key.

curl -N http://localhost:8443/api/v1/schemas/{schema_id}/chat \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -H "X-Model-Provider: anthropic" \
  -H "X-Model-API-Key: sk-ant-user-provided-key" \
  -H "X-Model-Name: claude-sonnet-4-20250514" \
  -d '{"message": "Hello"}'

Security consideration

BYOK headers are only accepted when the corresponding provider is explicitly enabled in Settings. By default, all providers are disabled for BYOK. The user-provided key is used for that single request only and is never stored.

Model Registry

Browse the built-in catalog of known models and providers. No authentication required.

# List all models (filterable by provider, tier, supports_tools)
curl "http://localhost:8443/api/v1/models/registry?provider=anthropic&tier=1"

# List all providers
curl http://localhost:8443/api/v1/models/registry/providers

See Model Registry for full documentation.

Tool Call Audit (EE)

Query tool call history for compliance and debugging. Requires admin scope.

curl "http://localhost:8443/api/v1/audit/tool-calls?agent=sales-agent&from=2026-03-01" \
  -H "Authorization: Bearer bb_your_token"

Returns paginated results with session ID, agent name, tool name, input/output, status, duration, and timestamp. See REST API: Tool call audit log for the full query parameter reference.

Rate Limit Usage (EE)

Check current rate limit consumption for a specific key. Requires admin scope.

curl "http://localhost:8443/api/v1/rate-limits/usage?key_header=X-Org-Id&key_value=org-123" \
  -H "Authorization: Bearer bb_your_token"

Returns rule name, key, tier, used/limit counts, window duration, and reset time. See Configuration: Rate Limits for setup.

Prometheus Metrics (EE)

curl http://localhost:8443/metrics

Returns Prometheus-compatible metrics. No authentication required. See Production: Prometheus Metrics for available metric names and Kubernetes integration.

---

What’s next

• Admin Dashboard: API Keys
• Core Concepts: Tasks
• Multi-Agent Config