sanderkorf Bambuser Live REST API
HTTPS/JSON API for automating shows, products, users, and related resources. Server-side only — do not call from the browser.
References: endpoints · models
Base URLs
Match BamHub region:
| Region | BamHub host | API base |
|---|---|---|
| Global | https://lcx.bambuser.com/ |
https://liveshopping-api.bambuser.com/v1 |
| Europe | https://lcx-eu.bambuser.com/ |
https://liveshopping-api-eu.bambuser.com/v1 |
OpenAPI default server is EU. Prefer EU unless project env documents otherwise.
Authentication
Create a key in BamHub → Settings → Integrations → API Keys. Assign scopes listed per endpoint.
Authorization: Token YOURAPIKEYHERE
Not Bearer. Product catalog feed auth (often Bearer with a feed secret) is a different credential for a different surface.
Rate limiting
Default: 5 requests / 10 seconds (moving window). Exceed → HTTP 429. Some endpoints may document tighter limits; otherwise assume the default. Back off and retry.
Resources (map)
| Area | Typical ops |
|---|---|
| Shows | List/create/get/patch/delete; products (incl. batch add); highlights (beta); chat / pinned comments; assets; tags; channels; broadcasts; transcripts |
| Products | List/get/patch/delete; highlighted products and appearance lookups |
| Webhooks | Create subscription; fetch event by eventId to verify delivery |
| Statistics | Per-show / multi-show / activity / traffic / orders |
| Users / tags / channels | Invite/list/update; tag CRUD; channel create/get |
Full table: reference/endpoints.md.
Show model (CMS sync)
Important Show fields (see models). Typical CMS field names when syncing:
| Bambuser | Notes |
|---|---|
id |
Stable show id → e.g. bambuserShowId |
title / description |
BamHub copy → e.g. bambuserTitle / bambuserDescription |
state |
upcoming | scheduled | live | ended |
published / isTestShow |
Storefront lists: published && !isTestShow |
scheduledStartAt / startedAt / endedAt / createdAt |
ISO datetimes |
preview |
Preview image URL → e.g. previewUrl |
allowArchivedPlayback / isArchived / showLengthSeconds |
Playback / archive flags |
Products
ProductModel: publicUrl required; optional productReference, title, thumbnail, brand.
productReference is an external catalog identity (SKU / item id) aligned with whatever the BamHub catalog feed uses. Prefer catalog feed + BamHub for catalog sync; use REST for show/product attachment and admin automation.
Webhooks
POST /webhooks (WRITE_WEBHOOKS) body: name, url, topics, headers (all required).
Topics: show · product · user · product-highlight · broadcast
Event payload:
{
collection: 'show' | 'product' | 'user'
action: 'add' | 'update' | 'remove'
payload: object
eventId: string
timestamp: string // ISO
}
Verify origin/contents with GET /webhooks/{eventId} (READ_WEBHOOKS).
Integration boundaries
| Surface | Role |
|---|---|
| Live REST API | This skill — server-side shows, webhooks, admin automation |
| Embed / player SDK | Storefront player, cart bridge, product hydration — use bambuser-live |
| Product catalog feed | BamHub catalog ingest; often Bearer feed secret, not Token API key |
| CMS sync | Optional — map show fields into CMS documents when the project does that |
Do not put REST calls in storefront client components. Do not confuse Token API keys with the feed bearer secret.
Fetch template
const BAMBUUSER_API_BASE =
process.env.BAMBUUSER_API_BASE ?? 'https://liveshopping-api-eu.bambuser.com/v1'
async function bambuserFetch<T>(
path: string,
init: RequestInit & { apiKey: string },
): Promise<T> {
const { apiKey, ...rest } = init
const response = await fetch(`${BAMBUUSER_API_BASE}${path}`, {
...rest,
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: `Token ${apiKey}`,
...rest.headers,
},
})
if (response.status === 429) {
throw new Error('Bambuser rate limit (429). Back off and retry.')
}
if (!response.ok) {
const body = await response.text()
throw new Error(`Bambuser ${response.status}: ${body}`)
}
if (response.status === 204) {
return undefined as T
}
return (await response.json()) as T
}
// Example: get show
// await bambuserFetch<Show>(`/shows/${showId}`, { method: 'GET', apiKey })
Prefer Zod (or equivalent) at the system boundary when persisting into CMS or domain types.