API

API overview

The Backbone Lab API is a REST API at https://api.bkbn.ai for AI photo editing of real-estate listings: HDR develop, perspective correction, signature tone, sky replacement, decluttering, virtual staging, magic eraser. You upload photos, submit orders against a fixed catalog of features, follow them in realtime, and download the results.

Prerequisites

To use the API, you need:

A workspace with API access (request a key).
An API key (starts with sk-), passed in the X-API-Key header.

How it works

Every feature follows the same asynchronous pattern:

Upload assets: POST /v1/assets declares the file and returns an assetId plus a presigned uploadUrl. PUT the bytes there, confirm with POST /v1/assets/:id/uploaded, and the asset is ready once ingest has normalized it.
Submit an order: POST /v1/orders with your asset ids under inputs (1-5 brackets of one scene) and the feature options next to them. Returns an orderId; orders are asynchronous, not blocking.
Follow it: stream GET /v1/orders/:id/events (SSE) or poll GET /v1/orders/:id. The SDKs multiplex a single WebSocket instead.
Download the result: GET /v1/assets/:id with the order's outputAssetId.

Shooting a whole property? Batches submit every scene in one call, with shared defaults and per-scene overrides.

SDKs

Official clients for JavaScript/TypeScript (@bkbnlab/api), Python (bkbnlab) and Kotlin/JVM (ai.bkbnlab:api-kotlin) share the same surface: upload, order, batch, wait, watch. They hide the upload dance, hold one multiplexed WebSocket per client for realtime, fall back to polling on restrictive networks, and raise typed errors. Every feature page shows the same example in all three languages plus curl.

Request and response format

Requests with a body are JSON. Every JSON response is wrapped in a data envelope:

{ "data": { "orderId": "8a4f…", "inputCount": 1 } }

Failures use an error envelope with the HTTP status and a human-readable reason — see Errors:

{ "error": { "status": 400, "reason": "each value in inputs must be a UUID" } }

The feature catalog

Features are versioned — each one carries the semver of the recipe it currently delivers, so quality improvements are visible without any interface change. The live catalog is public:

curl https://api.bkbn.ai/v1/features

The full reference, grouped by category, lives in Features:

Enhancement: enhancer, auto HDR, sky replacement, declutter, mess cleaner, privacy blur.
Staging: indoor and outdoor staging; room transforms and renovation are coming soon.
Inpainting: magic eraser.
Floor plans and video: coming soon.

Endpoints at a glance

Endpoint	Purpose
`GET /v1/features`	The versioned feature catalog (public).
`POST /v1/assets`	Declare an upload — returns a presigned URL.
`POST /v1/orders`	Submit one order (one scene, any features).
`POST /v1/batches`	Submit a whole shoot atomically.
`GET /v1/orders/:id/events`	SSE lifecycle stream of one order.
`GET /v1/events`	SSE account feed — everything on your key.
`POST /v1/api-keys/rotate`	Rotate your key — see Authentication.

The machine-readable spec is at https://api.bkbn.ai/openapi.json.

Next steps

Quickstart: first order, end to end.
Features: every feature and its options.
Rate limits, Streaming, Errors: production concerns.