Backbone LabDocs
API

API overview

The Backbone Lab API is a RESTful API at https://api.bkbn.com that exposes the same generative graph runtime our internal teams use — virtual staging, brochure composition, floor-plan inference and the underlying workflow primitives.

Prerequisites

To use the Backbone Lab API, you need:

  • A Backbone account with API access enabled.
  • An API key issued from the Console (console.bkbn.com/settings/keys), or a configured Workload Identity Federation rule.

For step-by-step setup, see Quickstart.

Available APIs

The Backbone Lab API surface includes:

General availability

  • Workflows API — run any named graph (staging, relight, declutter, brochure) as a single streaming call (POST /v1/workflows/{name}/run).
  • Staging API — empty-room to furnished render with six curated styles (POST /v1/staging).
  • Floor Plans API — editable plan inference from a 2-minute walk-through (POST /v1/floor-plans).

Beta

  • Brochures API — compose an editorial brochure from a listing (storyboard, palette, copy, layout) in one call (POST /v1/brochures).

Authentication

Every request must include these headers. See Authentication for the full reference.

HeaderValueRequired
x-api-keyYour API key from the Console.One of x-api-key or Authorization.
AuthorizationBearer <token> where <token> is a short-lived access token from POST /v1/oauth/token.One of x-api-key or Authorization.
bkbn-versionAPI version (e.g., 2026-01-01).Yes.
content-typeapplication/jsonYes.

Request and response format

Request size limits

EndpointMaximum request size
Workflows, Staging, Floor Plans32 MB
Brochures64 MB
Batch jobs256 MB

If you exceed these limits you receive a 413 request_too_large error.

Response headers

Every response carries:

  • request-id — a globally unique identifier for the request.
  • bkbn-organization-id — the organization tied to the calling API key.

Example request

A minimal workflow call that runs the staging-v2.4 graph:

curl https://api.bkbn.com/v1/workflows/staging-v2.4/run \
  -H "x-api-key: $BKBN_API_KEY" \
  -H "bkbn-version: 2026-01-01" \
  -H "accept: text/event-stream" \
  -H "content-type: application/json" \
  -d '{
    "input": "https://cdn.bkbn.com/listings/8472/raw.jpg",
    "params": {
      "style": "scandi-warm",
      "keep_geometry": true,
      "resolution": "4k"
    }
  }'

The response is a Server-Sent Events stream:

event: node.start  { "id": "segment_rooms" }
event: node.done   { "id": "segment_rooms", "ms": 312 }
event: node.start  { "id": "condition_style" }
event: node.done   { "id": "condition_style", "ms": 96 }
event: render.progress { "step": 28, "total": 28 }
event: result
{ "url": "https://cdn.bkbn.com/listings/8472/staged.jpg", "ms": 1244 }

Rate limits and availability

The API enforces request-per-minute and tokens-per-minute limits organized into tiers. Each tier raises automatically as usage grows. View your organization's current limits in the Console under Settings → Limits.

For full details, see Rate limits.

Next steps