Configuration Reference

Complete reference for braids.yaml — the single file that defines your entire API composition.

Root Structure #

Every Braids project is driven by a single braids.yaml file. The top-level structure contains four main sections plus an optional server block:

version: "1"

connectors:
  # ... connector definitions

schemas:
  # ... output schemas

endpoints:
  # ... API endpoints

server:
  port: 8080
  hot_reload: true

Connectors #

Connectors define the upstream data sources Braids fetches from. Each connector has a unique name (the YAML key) and the following fields:

• type (required) — Built-in connector type name (stripe, github, shopify, etc.) or path for custom connectors.
• path (conditional) — Directory path for custom connectors. Required when type is path.
• config — Authentication credentials map. Supports ${ENV_VAR} substitution for secrets.
• resources — Optional per-instance resource overrides. Use this to customize paths, methods, or data extraction for a specific connector.

Connector example

connectors:
  stripe:
    type: stripe
    config:
      api_key: ${STRIPE_API_KEY}

  my_api:
    type: path
    path: ./connectors/my-api
    config:
      token: ${MY_API_TOKEN}

Resource overrides

Resource overrides let you customize how Braids interacts with a connector's upstream API. This is useful when the built-in resource definitions don't match your needs, or when you need to point a connector at a non-standard path:

connectors:
  stripe:
    type: stripe
    config:
      api_key: ${STRIPE_API_KEY}
    resources:
      orders:
        path: /v1/orders
        method: GET
        data_field: data

Schemas #

Schemas define the shape of your API's output. You own the schema — Braids maps upstream data into the structure you choose, rather than exposing the upstream format directly. Each schema has a unique name (the YAML key) and the following fields:

• merge_on (optional) — Field name to group and merge records by. When multiple sources return data with the same value for this field, Braids merges them into a single record.
• conflict_resolution (optional) — How to resolve when multiple sources provide the same merge key. Values: prefer_latest (use the most recently updated value) or default behavior (last source wins).
• fields (required) — Output field definitions. Each field specifies a type that Braids uses for validation and coercion.

schemas:
  customers:
    merge_on: email
    conflict_resolution: prefer_latest
    fields:
      id:
        type: string
      email:
        type: string
      name:
        type: string
      created_at:
        type: datetime

Field types

Endpoints #

Endpoints define the HTTP routes your Braids gateway serves. The YAML key is the URL path (e.g., /customers, /users/{id}). Each endpoint has:

• schema (required) — References a schema name defined in the schemas section.
• sources (required) — Array of data sources. Braids fetches all sources in parallel and merges the results.

Each source within sources has:

• connector (required) — Name of a defined connector.
• resource (required) — Resource name from the connector (e.g., customers, orders).
• params (optional) — Static query parameters sent upstream with each request.
• headers (optional) — Static headers sent upstream with each request.
• mapping (required) — Maps upstream fields to schema fields. Supports direct field references and simple expressions.

endpoints:
  /customers:
    schema: customers
    sources:
      - connector: stripe
        resource: customers
        params:
          limit: 100
        mapping:
          id: "'stripe_' + id"
          email: email
          name: name
          created_at: created

      - connector: shopify
        resource: customers
        headers:
          X-Custom: value
        mapping:
          id: "'shopify_' + id"
          email: email
          name: "first_name + ' ' + last_name"
          created_at: created_at

Path Parameters #

Use {param} syntax in endpoint paths to capture URL segments as path parameters. These values are extracted from the incoming request URL and made available for upstream URL substitution.

endpoints:
  /customers/{id}:
    schema: customer_detail
    sources:
      - connector: stripe
        resource: customers
        mapping:
          id: id
          email: email

For example, a request to GET /customers/cus_123 extracts id = "cus_123". The extracted parameter is passed to the upstream connector so it can fetch the correct record.

Server #

The optional server block configures how the Braids gateway runs:

server:
  port: 8080
  hot_reload: true

Environment Variables #

Braids supports ${VAR_NAME} placeholders that are replaced at config load time from environment variables. This keeps secrets out of your config file and makes it safe to commit braids.yaml to version control.

Works in: any position in braids.yaml. Substitution runs on the entire file before YAML parsing, so ${VAR_NAME} can appear in connector configs, resource queries, server settings, or anywhere else.

When unset: If an environment variable is not defined, the original ${VAR_NAME} placeholder remains as-is in the config. The connector will likely return an authentication error at request time rather than at startup.

Full Annotated Example #

A complete braids.yaml demonstrating all major features:

# ── Config version (required) ──────────────────────────
version: "1"

# ── Connectors ─────────────────────────────────────────
# Each connector defines an upstream data source.
# Use ${ENV_VAR} for secrets — never hardcode API keys.
connectors:
  stripe:
    type: stripe
    config:
      api_key: ${STRIPE_API_KEY}

  shopify:
    type: shopify
    config:
      store: ${SHOPIFY_STORE}
      access_token: ${SHOPIFY_ACCESS_TOKEN}

  github:
    type: github
    config:
      token: ${GITHUB_TOKEN}

  # Custom connector using a local OpenAPI spec
  internal_api:
    type: path
    path: ./connectors/internal-api
    config:
      token: ${INTERNAL_API_TOKEN}

  # Connector with resource overrides
  postgres:
    type: postgres
    config:
      connection_string: ${DATABASE_URL}
    resources:
      active_users:
        query: "SELECT id, email, name, created_at FROM users WHERE active = true"

# ── Schemas ─────────────────────────────────────────────
# You define the output shape. Braids maps upstream data
# into your schema — you own the contract.
schemas:
  customers:
    merge_on: email            # merge records from different sources by email
    conflict_resolution: prefer_latest  # when two sources have the same email, keep newer
    fields:
      id:
        type: string
      email:
        type: string
      name:
        type: string
      created_at:
        type: datetime

  customer_detail:
    fields:
      id:
        type: string
      email:
        type: string
      name:
        type: string
      total_spent:
        type: float
      order_count:
        type: int

# ── Endpoints ───────────────────────────────────────────
# Each key is a URL path served by the gateway.
# Sources are fetched in parallel and merged per schema.
endpoints:
  # List endpoint — merges Stripe + Shopify customers
  /customers:
    schema: customers
    sources:
      - connector: stripe
        resource: customers
        params:
          limit: 100
        mapping:
          id: "'stripe_' + id"
          email: email
          name: name
          created_at: created

      - connector: shopify
        resource: customers
        headers:
          X-Shopify-Api-Version: 2024-01
        mapping:
          id: "'shopify_' + id"
          email: email
          name: "first_name + ' ' + last_name"
          created_at: created_at

      - connector: postgres
        resource: active_users
        mapping:
          id: "'pg_' + id"
          email: email
          name: name
          created_at: created_at

  # Detail endpoint — path parameter for single record
  /customers/{id}:
    schema: customer_detail
    sources:
      - connector: stripe
        resource: customers
        mapping:
          id: id
          email: email
          name: name
          total_spent: balance
          order_count: orders

# ── Server ──────────────────────────────────────────────
server:
  port: 8080              # listening port (default: 8080)
  hot_reload: true       # auto-reload on config changes