Developers
Brand Engine API
Brand identity is compiled once in the hub and read everywhere else. This API is how your services and federated tools fetch it, stay in sync, and send events back.
Quickstart
From zero to a cached brand bundle in four steps.
- 1. Get a credential. For your own back-office services, issue an API key (be_…) from the Developer page inside the hub. For a federated child tool, ask the hub owner for CORE_CHILD_APP_TOKEN__<TOOL> and CHILD_WEBHOOK_SECRET__<TOOL>.
- 2. Confirm access. Call GET /api/public/brands with the API key. You should get back the brand the key is scoped to, including its current identity_version.
- 3. Read the identity. From your backend call GET /api/public/v1/brand/by-id/:id/bundle with the child token and X-Tool-Slug header. Store the response in a brand_cache row keyed by brand_id, together with identity_version.
- 4. Stay fresh. Expose a webhook endpoint, verify X-Hub-Signature with CHILD_WEBHOOK_SECRET__<TOOL>, and mark the matching brand_cache row stale on identity.updated. Re-fetch the bundle with ?since=<cached version> on the next read.
First call
curl https://thebrandengine.ai/api/public/brands \ -H "Authorization: Bearer be_xxxxxxxxxxxxxxxx"
v0 public API
Bearer API key or user session token. For your own services, webhooks, and automations.
- GET
/api/public/toolsAPI key (Bearer be_…)List tools available in the ecosystem, with this brand's entitlement state.
- GET
/api/public/brandsAPI key (Bearer be_…)List brands the API key can access. For brand-scoped keys this returns the one brand.
- GET
/api/public/brands/meFederation token (Bearer JWT)List every brand the signed-in user is a member of. Used by children to render a brand switcher.
- GET
/api/public/brand/meFederation token (Bearer JWT)Active brand identity. Honors X-Brand-Id when the caller is a member of the requested brand.
- POST
/api/public/eventsAPI key (Bearer be_…)Emit an orchestration event other tools can react to.
- POST
/api/public/federation/mintFederation token (Bearer JWT)Mint a short-lived federation token. Optional { brand_id } body to target a specific brand.
- POST
/api/public/federation/exchangePublicExchange a federation token for the user's brand context.
v1 ecosystem contract
Server-to-server endpoints used by federated tools such as Dialog Center and AI Agents.
- GET
/api/public/v1/brand/by-id/:id/bundleChild app token (CORE_CHILD_APP_TOKEN__<TOOL>)Server-to-server brand bundle. Pass ?since=<version> for 304-style not_modified.
- POST
/api/public/v1/eventsChild app token (CORE_CHILD_APP_TOKEN__<TOOL>)Locked schema, idempotent event ingestion.
- POST
/api/public/v1/internal/dispatch-tickWEBHOOK_DISPATCH_SECRET (hub-internal)Cron-driven webhook fan-out tick.
- POST
/api/public/v1/internal/register-subscriptionWEBHOOK_DISPATCH_SECRET (hub-internal)Admin upsert of (brand_id, tool_slug) → webhook_url.
- GET
/api/public/v1/docs/openapi.jsonPublicMachine-readable OpenAPI 3.1 description of this API.
- GET
/api/public/v1/docs/api.pdfPublicDownload the current API documentation as a PDF.
Other formats
The HTML reference is the source of truth. These are generated from it.