Booth.Events API

Automate your events from your own tools — or let an AI agent do it for you. Available on Pro+ plans.

Authentication

Create an API key in the dashboard under Account → Sharing Settings → API Keys (it is shown exactly once). Send it on every request:

curl https://api.booth.events/v1/events \
  -H "Authorization: Bearer be_live_..."

Keys are read or read-write scoped. Treat them like passwords: server-side only, revoke from the dashboard if leaked.

Versioning

The API is date-versioned. Every API key is pinned to the version that was current when the key was created and keeps that behavior for as long as it lives — new API versions never change what an existing key's requests mean, and rotating a key keeps its pin. To adopt a newer version, create a new key (new keys always pin to the current version) or re-pin the existing one; pin changes take up to a minute to apply. The current version is 2026-08-04.

Override the version per request with the Booth-Events-Version header:

curl https://api.booth.events/v1/events \
  -H "Authorization: Bearer be_live_..." \
  -H "Booth-Events-Version: 2026-08-04"

Every response echoes the version that served it in the same header. MCP connectors (which cannot send custom headers) can append ?version=2026-08-04 to the connector URL. The machine-readable spec for any version is at /v1/openapi.json?version=….

Changelog

• 2026-08-04 — initial version.

Connect an AI agent (MCP)

The same API is exposed as a hosted MCP server at https://api.booth.events/mcp.

Claude Code

claude mcp add booth-events --transport http https://api.booth.events/mcp \
  --header "Authorization: Bearer be_live_..."

Cursor / VS Code / Windsurf (mcp.json)

{
  "mcpServers": {
    "booth-events": {
      "url": "https://api.booth.events/mcp",
      "headers": { "Authorization": "Bearer be_live_..." }
    }
  }
}

claude.ai / ChatGPT (web connectors)

Add a custom connector with the URL https://api.booth.events/mcp. A Booth.Events authorization page opens — paste an API key once and the connector stays linked to it (OAuth 2.1 under the hood; revoking the key disconnects the connector too).

Trimming the tool list (optional)

The full surface is 70+ tools; agents pick tools more reliably from smaller lists. Append ?toolsets= to the MCP URL to expose only what your integration needs, e.g. https://api.booth.events/mcp?toolsets=events,templates,ai,analytics (the core CRM loop). Groups: events (events, gallery settings/URL, event⇄template assignment), templates (templates, imports, scenes, uploads, attract screens, sticker sets), ai (prompts, portraits, credits), media (guest media, sessions, survey export), analytics (stats, client reports), account (audit log, webhooks, communication settings, devices), team, payments.

Image & preview URLs — three kinds, know which you hold

Every image URL the API returns is directly fetchable by any browser with no auth — but their lifetimes differ. If you are generating an app against this API (human or AI): render image URLs promptly and re-fetch the list to refresh them; never persist them as long-lived data.

Where	Kind	Lifetime
Public AI portrait / prompt catalog previews	Stable public URL	Never expires — safe to cache
Template / attract screen / sticker set thumbnailUrl	Stable upload-time URL (signed fallback when absent)	Stable; fallback expires in 7 days
Gallery media originalUrl/thumbnailUrl, event-stats topMedia, private catalog previews	Signed URL	Up to 7 days; media URLs are normally refreshed to ≥24 h when served; a legacy item without a stored path can still hand back an expired one — re-list to refresh

Uploading files

Binary uploads (PDF/ZIP template imports, AI reference images, scenes) are a two-step flow:

1. POST /v1/uploads (create_upload) with a purpose — returns a short-lived signed uploadUrl plus the headers you must send back exactly.
2. HTTP PUT the raw bytes to uploadUrl (no auth header), then pass the returned storagePath as uploadPath to the consuming operation.

No PUT? Use sourceUrl instead. Every consuming operation alternatively accepts a public https URL it fetches server-side (must not redirect) — ideal when your assets already live on your own storage/CDN, and the only option for AI agents over MCP, which cannot upload binaries.

Build a CRM integration

The intended loop for booking platforms (CheckCherry, HoneyBook, BoothBook, …). Set idUser to your booking id everywhere — it is the correlation key: list_events filters by it, and create_event is retry-safe with it (an existing event with the same idUser is returned with alreadyExisted instead of duplicating or burning quota).

1. Create the event — create_event with name, date, templateIds (from list_templates), and idUser.
2. Bring the client's design — create_template_from_pdf or create_template_from_images (PNG/JPG/ZIP): same pipeline as the dashboard's "Upload design", photo areas detected automatically. Then add_event_template.
3. Set up AI — create_ai_prompt (+ add_ai_prompt_reference_image for style), or pick portrait styles via list_ai_portraits; attach both with update_template. Check get_ai_credits before the event.
4. Green screen — add_template_scene per background.
5. After the event — get_event_stats for engagement (leaderboards come with names + preview images), then update_event_report + publish_event_report and email the returned reportUrl to your client — a white-label-ready report page, no sign-in needed.

Rate limits & errors

At least 120 requests/min per key (burst 40); expensive operations (creates, duplicates) count extra. 429 responses carry Retry-After. Errors always look like:

{ "error": { "code": "validation_failed", "message": "...", "details": [...], "requestId": "..." } }

Reference

Full endpoint reference below. The machine-readable spec is at /v1/openapi.json.