API overview

Every Brainerce endpoint, request, and response, rendered from the committed OpenAPI spec.

The Brainerce API is REST + JSON over HTTPS. Same set of endpoints powers the dashboard, the SDK, and your integrations — there is no separate "admin API" or "internal API."

Base URL

All endpoints sit under https://api.brainerce.com/api/. Vibe-coded storefront routes live at https://api.brainerce.com/api/vc/{salesChannelId}/....

Authentication

Pick the right mode for your use case — see Authentication for the full breakdown:

Vibe-Coded — salesChannelId in the path (no header)
Storefront — storeId in the path (read-only, public)
Admin — Authorization: Bearer brainerce_<key> header (an X-API-Key: brainerce_<key> header is accepted too; prefer Bearer, and never send both)
Customer-scoped — Authorization: Bearer {customerToken} header on top of any of the above

Response format

All endpoints return JSON. Successful responses use HTTP 200/201. Errors use 4xx/5xx with a body shape:

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "Validation error: storeId is required",
  "error": "Bad Request",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products"
}

Switch on code — it is always present and stable. error is not always present, and message is prose that can be reworded. See Errors for the full error catalog.

Pagination

List endpoints return a standard envelope:

{
  "data": [
    /* items */
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1247,
    "totalPages": 63
  }
}

Use ?page= and ?limit= query params to page through results. limit defaults to 20 and is capped at 100 — a larger value is silently clamped, not rejected. See Pagination before writing a backfill loop.

Rate limits

See Rate Limits for per-endpoint quotas and recommended client behavior.

Quickstart

Three steps from zero to your first authenticated request.

1. Get an API key

In the dashboard → Settings → Authentication → API Keys → Create API Key. Pick the scopes you need (e.g. products:read, orders:write) and copy the plain-text key — it's shown only once. Format: brainerce_xxxxxxxxxxxxxxxx.

A test key (brainerce_test_xxxxxxxxxxxxxxxx) carries a different prefix so it stands out in code, logs and dashboards. ⛔ It is not a sandbox. Both prefixes hash and validate identically, and a test key reads and writes the same live store data as a live key, with the same scopes. There is no isolated test environment: a delete made with a test key deletes the real record.

What is separate is payment: an order placed while the payment provider is in its own sandbox or test mode is stamped as a test order and is excluded from analytics. That flag comes from the provider, not from the key you called with. Before running anything destructive, point the integration at a store you are willing to damage.

2. Make your first call

curl https://api.brainerce.com/api/v1/store \
  -H "Authorization: Bearer brainerce_xxxxxxxxxxxxxxxx"

A successful response returns your store info:

{
  "id": "store_xyz",
  "name": "Your Store",
  "currency": "USD",
  "domain": "yourstore.com"
}

3. List products

curl "https://api.brainerce.com/api/v1/products?limit=10" \
  -H "Authorization: Bearer brainerce_xxxxxxxxxxxxxxxx"

{
  "data": [{ "id": "prod_abc", "name": "T-shirt", "price": "29.99", "currency": "USD" }],
  "meta": { "page": 1, "limit": 10, "total": 1247, "totalPages": 125 }
}

That's the whole shape. Every list endpoint follows it. Browse the Public API (v1) reference for the full surface, or jump straight to a resource group below.

Endpoint groups

The endpoint reference is generated from docs/api/openapi.yaml, a committed file that is regenerated by hand, not on every deploy. It therefore reflects the last regeneration rather than the running backend, and a handful of resources are missing from it entirely — those pages render their intro and no operations. Where a page looks empty, the surface is real; the spec is behind. /v1/* routes are the public contract; dashboard-only routes (Clerk JWT) and storefront /vc/{salesChannelId}/* routes carry no versioning guarantee even where the reference happens to list them.

Public API (v1) — the integrator REST surface under /api/v1/*. Start here if you're calling Brainerce from outside the dashboard.
Orders, Customers — per-resource reference for the public API.
Cart + Checkout — the buy-flow state machine.
Coupons, Product Reviews — marketing surfaces.
Inventory, Shipping, Tax — operations.
Categories, Brands, Tags, Attributes, Metafields — taxonomy.
Email, Sync — admin.

Webhook subscriptions, API keys, sales channels, analytics, discount rules, store provisioning and team management are missing from the generated spec, so their reference pages are empty. Until the spec is regenerated, use: Webhooks and the event catalogue for webhook subscriptions, Authentication for API keys, and Resource locations for where the rest of those resources are mounted.

Marketplace apps using app_inst_* tokens against /v1/installations/* should read Authentication → App Installation Tokens. The HTTP MCP server has a dedicated reference at MCP server.

See the Integration Guide for end-to-end examples (build a storefront, sync products, take a payment).

On this page