API Reference

How the Braids gateway responds to requests — response format, error handling, and runtime behavior.

Response Format#

Every endpoint returns a consistent JSON envelope:

{
  "data": [
    {
      "id": "stripe_cus_123",
      "email": "[email protected]",
      "name": "Alice Johnson",
      "created_at": "2024-03-11T12:00:00Z"
    },
    {
      "id": "shopify_789",
      "email": "[email protected]",
      "name": "Bob Smith",
      "created_at": "2024-03-10T08:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "sources": ["stripe", "shopify"]
  }
}

Field	Type	Description
`data`	array	Array of merged records matching the schema
`meta.total`	integer	Number of records in `data`
`meta.sources`	array	List of connector names that were queried
`meta.errors`	array	Errors from individual sources. Only present when one or more sources fail.

Path Parameters#

Endpoints can include named path parameters using {param} segments:

Define paths with {param} segments: /customers/{id}
The gateway extracts named segments from the URL
Path params are passed to upstream connectors for URL substitution
For database extensions, params become positional query parameters ($1, ?)

Request:  GET /customers/cus_123
Config:   /customers/{id}
Extracts: { "id": "cus_123" }

The extracted id is available to:

Upstream REST API paths (e.g., /v1/customers/cus_123)
SQL query parameters ($1)
MongoDB filter substitution ({id})

Partial Results#

When one source fails but others succeed, the gateway returns partial results instead of failing entirely:

{
  "data": [
    {
      "id": "stripe_cus_123",
      "email": "[email protected]",
      "name": "Alice Johnson"
    }
  ],
  "meta": {
    "total": 1,
    "sources": ["stripe", "shopify"],
    "errors": [
      {
        "source": "shopify",
        "error": "upstream returned 401 Unauthorized"
      }
    ]
  }
}

Successful sources are included in data. Failed sources are listed in meta.errors with the error message. The response still returns HTTP 200 with whatever data was available.

Note

This partial-failure design means a single misconfigured connector won't break your entire API. Check meta.errors to monitor source health.

Source Parameters and Headers#

Each source can include static query parameters and headers that are sent with every upstream request:

braids.yaml

sources:
  - connector: stripe
    resource: customers
    params:
      limit: 100
      expand: [subscriptions]
    headers:
      X-Request-Source: braids
    mapping:
      id: id
      email: email

params — Static query parameters appended to the upstream request URL
headers — Static headers added to the upstream request
Array values in params: expand: [subscriptions] becomes expand[]=subscriptions

Error Responses#

HTTP error responses returned by the gateway itself:

Status	Condition	Response
`200`	Success (or partial success)	Data envelope with `meta.errors`
`404`	Endpoint not found	Plain text: `404 page not found`
`500`	Schema not found / internal error	Plain text: `schema not found` (or error message)

Debug Mode#

When running with --debug, the gateway logs detailed request/response info for every upstream call:

[DEBUG] Incoming: GET /customers → matched endpoint
[DEBUG] Source stripe/customers: 25 records, 142ms elapsed
[DEBUG] Source shopify/customers: 18 records, 238ms elapsed

Useful for: diagnosing connector issues, verifying source record counts, and understanding request routing.

Tip

Don't run with --debug in production — it logs full request/response details which may include sensitive data.

Hot Reload#

When server.hot_reload: true:

The gateway watches braids.yaml for changes
On file change, the config is reloaded and connectors are re-initialized
In-flight requests complete with the old config
New requests use the new config
A debounce prevents rapid successive reloads

Log output:

2025/03/11 14:32:01 Config changed, reloading...
2025/03/11 14:32:01 Config reloaded successfully

Previous ← CLI Reference