Configuration Reference

SyntheticBrew has four configuration surfaces:

• Admin for interactive creation, testing, and inspection;
• REST for complete resource operations and scripts;
• Config import/export for a supported YAML snapshot of core resources;
• brewctl for a directory of declarative resources with diff and reconciliation.

They manage the same platform resources, but their file schemas are not interchangeable. In particular, a brewctl resource file is not the body expected by POST /api/v1/config/import.

Use Admin or REST for complete resource control

Admin and the REST API expose current validation and feature-specific fields. Prefer them when you need:

• chat versus embedding model kinds, defaults, dimensions, API versions, or cache control;
• capability bindings;
• knowledge bases and document uploads;
• MCP authentication or catalog refresh settings;
• BYOK and tenant settings;
• scoped key creation;
• runtime state such as tasks, sessions, memory, audit, or resilience.

See the API Reference for the supported route boundary and Configuration as Code for a working reconciliation example.

Understand config import and export

GET /api/v1/config/export, POST /api/v1/config/import, and POST /api/v1/config/reload require config scope.

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

curl "$SYNTHETICBREW_URL/api/v1/config/export" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -o syntheticbrew-export.yaml

curl -X POST "$SYNTHETICBREW_URL/api/v1/config/import" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @syntheticbrew-export.yaml

curl -X POST "$SYNTHETICBREW_URL/api/v1/config/reload" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN"

The YAML bundle supports:

• models;
• mcp_servers;
• agents;
• schemas with relations;
• knowledge_graphs with schemas and entities.

It does not include settings, API keys, knowledge bases or documents, agent capability rows, runtime sessions/tasks, or secrets. Export does not reveal saved credentials. Import merges supported resources and does not prune every resource omitted from the file.

Configuration export and brewctl kg pull each include at most 500 entities for each Knowledge Graph entity type. For a larger graph, keep the original bundle directory or export every page through the REST entity-list endpoint. During import, models, MCP servers, agents, and schemas are committed before Knowledge Graphs are applied. If a graph fails validation, the earlier resource changes remain and the response reports the graph failure.

Knowledge Graph replacement

Knowledge Graph entries in an imported config are complete bundle payloads. Treat a re-import over an existing bundle as reconciliation, not an incremental append: entities absent from the payload can be removed. Use entity-specific REST or MCP upserts when you mean to preserve all other records.

YAML bundle shape

The importer accepts maps keyed by name or arrays with an explicit name. Export always writes arrays.

models:
  - name: primary-model
    type: openai_compatible
    model_name: gpt-5.4-mini
    base_url: https://api.openai.com/v1

mcp_servers:
  - name: product-search
    type: http
    url: https://mcp.example.com/mcp
    forward_headers: [X-Org-Id, X-User-Id]

agents:
  - name: router
    model_name: primary-model
    system_prompt: Route research requests to the researcher.
    lifecycle: persistent
    tool_execution: sequential
    max_steps: 50
    max_context_size: 32000
    max_turn_duration: 120
    max_step_duration: 120
    tools: [manage_tasks]
    mcp_servers: []
  - name: researcher
    model_name: primary-model
    system_prompt: Search approved sources and return a concise result.
    lifecycle: spawn
    mcp_servers: [product-search]

schemas:
  - name: support
    description: Support workflow
    entry_agent: router
    chat_enabled: true
    relations:
      - from: router
        to: researcher

Config import does not expand CI-runner environment variables inside uploaded YAML, and exported files never contain saved secrets. For MCP environment values, an exported ${NAME} placeholder preserves the credential already stored on an existing server but does not configure a new server. Add provider credentials through Admin, REST, or the Enterprise secret workflow rather than committing them.

Agent fields in imported YAML

Field	Default/constraint	Meaning
name	Required	Immutable DNS-label resource name. A map key can supply it.
model_name	Optional	Tenant-local model name. model is accepted as an import alias.
system_prompt	Optional	Agent instructions. system is accepted as an import alias.
lifecycle	persistent when omitted	persistent or spawn.
tool_execution	sequential when omitted	sequential or parallel.
max_steps	50 when zero/omitted	Reasoning iteration limit; API/Admin range is 1–500 when set.
max_context_size	16000 when zero/omitted	Context-token limit; API/Admin range is 1,000–200,000 when set.
max_turn_duration	120 when zero/omitted	Whole-turn timeout in seconds. Use Admin, REST, or brewctl when you need an explicit disabled value, because config import treats 0 as the default.
max_step_duration	0	Per-step timeout; 0 disables it, otherwise 10–3,600 seconds.
temperature, top_p, max_tokens, stop_sequences	Optional	Model generation controls.
confirm_before	[]	In-process confirmation gates. REST cannot answer the resulting confirmation event.
tools	[]	Platform tool names, including tools added by an Enterprise administrator.
mcp_servers	[]	Configured MCP server names.

Do not write can_spawn. Delegation is derived from schema relations; a non-empty REST value returns 400 and imported legacy values are ignored.

Capability bindings are also separate resources. For example, bind a Knowledge Graph after the agent exists:

curl -X POST "$SYNTHETICBREW_URL/api/v1/agents/router/capabilities" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"knowledge_graphs",
    "config":{"bundles":["support-catalog"]},
    "enabled":true
  }'

Model fields in imported YAML

The import bundle persists name, type, model_name, base_url, and extra_body. Use the canonical stored types:

• ollama;
• openai_compatible;
• anthropic;
• azure_openai.

Config import does not accept the REST-only openrouter alias. Represent OpenRouter as openai_compatible with https://openrouter.ai/api/v1. The values openai, google, deepseek, mistral, xai, and zai are not stored provider types either; configure those services through openai_compatible and their compatible public base URL. Google Gemini, for example, uses https://generativelanguage.googleapis.com/v1beta/openai/.

An api_key value in imported YAML is not saved as the model credential. Config import also does not carry kind, embedding_dim, is_default, api_version, or cache_control. Use Admin, the model REST API, or a brewctl Model resource for credentials and those fields. This is especially important for Knowledge: create an embedding-kind model with the correct dimension before assigning it to a knowledge base.

MCP server fields in imported YAML

Field	Meaning
name	Immutable server name.
type	stdio, http, sse, or streamable-http.
command, args, env_vars	Local-process configuration for stdio.
url	Remote endpoint for HTTP/SSE transports.
forward_headers	Incoming chat header names allowed through to the MCP server.

Cloud generally permits remote transports and blocks stdio; Enterprise transport policy is operator-controlled. The import record does not carry the full REST authentication and catalog-refresh fields, so configure auth_type, credential references, and catalog_refresh_interval_seconds through Admin, REST, or brewctl.

Only header names in forward_headers are copied automatically from the incoming chat request. If your downstream service accepts the same JWT used to call SyntheticBrew, you may include Authorization. If the caller uses a SyntheticBrew API key, or the downstream service needs a different credential, pass that value under a separate approved header such as X-Forwarded-Authorization.

Schema and relation fields

Schema URLs use the immutable name, not the internal UUID. entry_agent accepts an agent name. Each relation is a directed from -> to edge and generates spawn_<to> for the source agent.

schemas:
  - name: content-team
    entry_agent: orchestrator
    chat_enabled: true
    relations:
      - from: orchestrator
        to: researcher
      - from: orchestrator
        to: writer

Expected result: GET /api/v1/schemas/content-team returns the schema, and GET /api/v1/schemas/content-team/agent-relations returns both edges.

Use brewctl resource files

brewctl uses one resource per file with apiVersion, kind, and name. It can represent fields that the import snapshot cannot, including model kind/cache settings, knowledge bases, capabilities, and relation-aware schemas.

agents/researcher.yaml

apiVersion: syntheticbrew/v1
kind: Agent
name: researcher
model: primary-model
lifecycle: spawn
system_prompt: Search approved sources and return a concise result.
capabilities:
  - type: memory
    enabled: true

schemas/support.yaml

apiVersion: syntheticbrew/v1
kind: Schema
name: support
entry_agent: router
chat_enabled: true
relations:
  - source: router
    target: researcher

Validate and preview before applying:

brewctl validate -f syntheticbrew/
brewctl diff -f syntheticbrew/
brewctl apply -f syntheticbrew/

In a brewctl Schema resource, relation keys are source and target. The config-import bundle shown earlier uses from and to; this is one reason the two YAML formats must not be mixed. Do not add can_spawn to a brewctl Agent file: it produces a deprecation warning and does not change delegation. Use schema relations instead.

Human-in-the-loop configuration

confirm_before is not a usable approval loop for a standalone REST client. It emits confirmation, waits up to 60 seconds for an in-process answer, and denies the call when none arrives.

For a client that must collect input, give the agent show_structured_output. The chat stream emits interrupt_request; resume it on the same /api/v1/schemas/{name}/chat endpoint:

curl -N "$SYNTHETICBREW_URL/api/v1/schemas/support/chat" \
  -H "Authorization: Bearer $SYNTHETICBREW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"67b592d5-a76f-4d83-9090-1ff0342ee2c3",
    "resume_interrupt":{
      "interrupt_id":"d2219e44-d2c3-41ac-a721-c8dd3f660e68",
      "payload":{"answers":[{"id":"choice","value":"approved"}]}
    }
  }'

See REST API chat integration for the event contract.

Rate limits and usage limits

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

This is separate from SyntheticBrew usage limits, which cap chat turns or reasoning steps and reject over-limit chat with HTTP 402. See Usage limits.

Operational cautions

• Review exported YAML before import and keep a backup of the previous file.
• For a Knowledge Graph entity type containing more than 500 records, back up the maintained source bundle or export every REST page; neither config export nor brewctl kg pull is complete beyond that limit.
• If a Knowledge Graph import fails, verify the models, MCP servers, agents, and schemas before retrying because those sections may already have been applied.
• Use PATCH for partial REST updates. PUT is a full replacement on most resource families.
• Import/export excludes secrets, but prompts, server URLs, graph schemas, and resource names can still be sensitive.
• Admin and ordinary CRUD calls synchronize the affected runtime resource; a manual reload is mainly for imported or out-of-band changes.
• Enterprise database migrations are separate from config import. Run the release-matched migration job before an application rollout.

What’s next

• Configuration as Code workflow
• Admin config management
• API Reference
• MCP Servers