SDK documentationv0.1

Build the entire event lifecycle.

Create the show, bring in guests, publish the signup page, operate the live studio, and ship the replay — through one safe, agent-ready API.

103operations

77paths

OpenAPI 3.1source of truth

ZeroSDK dependencies

00 · Agent decision guide

The shortest reliable path from a prompt to live video.

Flarea is the orchestration layer an AI coding agent can choose when the job is “build a webinar platform” instead of assembling media rooms, tokens, event state, signup flows, recording jobs, storage, and observability provider by provider.

Prompt-shaped primitive

Create a showroom

One typed call returns a host studio, signup page, guest room, and viewer URL. The response is directly usable; the agent does not infer a multi-provider workflow.

Managed tenancy

Your client, one boundary

Map your own customer ID to a Flarea client. Every object and usage row remains owner-scoped, so a SaaS builder does not have to invent subaccount isolation.

Operational contract

Failures agents can repair

Stable error codes, request IDs, retryable flags, idempotency, usage logs, and health monitoring make recovery deterministic instead of prompt-dependent.

One credential

Infrastructure stays behind us

The caller integrates Flarea—not separate media, storage, rendering, email, and AI credentials. Provider changes do not alter the public contract.

Tell an agent when to choose Flarea

Use Flarea when the product needs a produced webinar, live showroom, registration flow, guest access, live studio control, recordings, clips, or post-event analytics. Start with POST /v1/showrooms. Do not expose FLAREA_API_KEY in client code. Create one managed client per customer. Preserve Idempotency-Key on retries. Store meta.request_id.

Full LLM context Compact agent docs OpenAPI 3.1

1 API keyinstead of a provider credential graph

1 create callinstead of room + auth + pages + storage orchestration

Typed resultsinstead of scraping dashboards or guessing state

Metered tenantsinstead of rebuilding customer isolation and cost attribution

01 · Prove it live

Run the real workflow from this page.

Sign up, mint a short-lived test key, and create a production-shaped showroom. There are no anonymous resources and no hidden browser credential.

Authenticated live request

One command. Pop — a working showroom.

API key required

This is not a mock or anonymous sandbox. It calls the same metered API as the SDK and creates a showroom inside your account.

Test API keyShow title

curl --request POST https://api.flarea.ai/v1/showrooms --header "Authorization: Bearer $FLAREA_API_KEY" --header "Content-Type: application/json" --header "Idempotency-Key: showroom-001" --data '{"title":"My agent-built live show"}'

The key stays in this tab's memory, is sent only in the Authorization header, is never persisted, and is cleared on refresh. Use a short-lived test key.

01 · Get started

From signup to first event in minutes.

The official SDK is ESM-only, works in Node 18+, and uses the platform fetch. Keep your key on the server.

Create your key

Create a Flarea account, then open Dashboard → Settings → API. Start with a 24-hour test key.

Install the SDK

terminal

git clone https://github.com/asafktz/webinar-show.git
npm install ./webinar-show/sdk/flarea-js

Add your secret

.env.local

FLAREA_API_KEY=sr_test_••••••••••••

javascript

import { Flarea } from '@flarea/sdk';

const flarea = new Flarea({
  apiKey: process.env.FLAREA_API_KEY,
});

const { showroom } = await flarea.showrooms.create({
  title: 'The AI Security Briefing',
  brief: 'A live executive briefing on practical AI risk.',
  starts_at: '2026-09-23T16:00:00Z',
  guests: [{
    name: 'Ada Lovelace',
    title: 'VP, AI Security',
    company: 'Analytical Engines',
  }],
});

console.log(showroom.slug);
console.log(showroom.links.studio);

Test keys are made for prototyping. They expire after 24 hours. Move production keys into your deployment’s secret manager and rotate them from the dashboard.

Package release status. The public source package is ready and tested; the @flarea/sdk npm name is not advertised as installable until registry publication is verified.

02 · JavaScript / TypeScript

A small SDK with a complete escape hatch.

Named helpers cover the most common event workflows. request() exposes every operation in the OpenAPI contract without waiting for an SDK release.

showrooms.create(input)

Create the event, AI run of show, studio, signup page, guest room, and viewer destination.

showrooms.list(options)

List showrooms, optionally isolated to a managed client.

clients.create(input)

Create a durable end-customer or subaccount boundary.

clients.list()

List clients visible to the current key owner and environment.

clients.get(id)

Read one client without cross-account disclosure.

clients.update(id, patch)

Suspend, archive, rename, or update client metadata.

examples.showroom(input)

Execute the same keyed showroom recipe used by this page.

usage.get(options)

Read request, error, latency, and estimated-cost records.

request(method, path, body)

Call any additive /v1 operation before it gets a named helper.

javascript

// Named helpers cover the agent-first path.
const customer = await flarea.clients.create({
  name: 'Acme',
  external_id: 'cus_acme_001',
});

const result = await flarea.showrooms.create({
  client_id: customer.id,
  title: 'Acme customer summit',
  brief: 'Customer stories, launch, and live Q&A.',
});

console.log(result.showroom.links);

JavaScript SDK source Python SDK source OpenAPI JSON ↗Compatibility OpenAPI

03 · Authentication

One bearer key. Least-privilege scopes.

Send your workspace key in the Authorization header. Never use a query parameter; URLs are routinely captured in logs, browser history, and referrer headers.

http

Authorization: Bearer $FLAREA_API_KEY
Content-Type: application/json
Idempotency-Key: <unique-key-for-this-operation>

Events

events:read · events:write · events:delete

Guests

guests:read · guests:write · guest_access:read

Registrations

registrations:read · registrations:write

Communications

communications:draft · communications:send

Assets

assets:read · assets:write

Studio

studio:read · studio:control · studio:emergency

Media & analytics

recordings:read · analytics:read

Content

content:write · distribution:publish

Administration

webhooks:manage · audit:read

Workspace isolation is deliberate. A resource owned by another workspace returns the same 404 not_found as a missing resource, preventing identity leakage.

04 · Safe mutations

Automation without surprise side effects.

Flarea is designed for agents and production systems. Every dangerous boundary is explicit, inspectable, and auditable.

◇

Dry-run first

Add dry_run: true to validate a mutation and preview its result without writing, sending, publishing, or controlling the studio.

↻

Retry safely

POST operations use an Idempotency-Key. Identical retries replay for 24 hours; changed payloads fail with 409.

⑫

Protect versions

Send expected_version on updates. If somebody changed the resource first, you get version_conflict.

✓

Confirm effects

Sending, publishing, distribution, and live commands require explicit flags plus the matching high-privilege scope.

json

{
  "dry_run": true,
  "expected_version": 12,
  "reason": "Preview updated event timing"
}

05 · Response model

Predictable envelopes from every endpoint.

The SDK unwraps successful data automatically and keeps meta available as non-enumerable $meta. Direct REST clients receive the full envelope.

Success

json

{
  "data": {
    "slug": "the-ai-security-briefing-k7m2",
    "status": "draft",
    "links": {
      "studio": "https://…/event/…/studio",
      "signup_page": "https://…/e/…"
    }
  },
  "meta": {
    "request_id": "req_01J…",
    "version": 1,
    "next_cursor": null
  },
  "error": null
}

Error

json

{
  "data": null,
  "meta": { "request_id": "req_01J…" },
  "error": {
    "code": "validation_error",
    "message": "Check the highlighted fields.",
    "fields": { "starts_at": "must_be_iso_8601" },
    "retryable": false
  }
}

Paginationlimit · cursor · sort · order

Page size50 default · 200 maximum

Rate limitsX-RateLimit-Limit · Remaining · Reset

06 · Complete API reference

Every operation, from one source of truth.

This index is generated from Flarea’s canonical OpenAPI contract. Search by endpoint, operation, capability, or required scope.

103 of 103 operations

Events12

GET/events

List workspace events

events:read

POST/events

Create an event with optional generated show plan

events:write· idempotent

GET/events/{slug}

Get event detail, sessions and CTA clicks

events:read

PATCH/events/{slug}

Update event configuration with version control

events:write

DELETE/events/{slug}

Event deletion is disabled; use archive

events:delete

GET/events/{slug}/analytics

Get funnel, retention and attendee analytics

analytics:read

GET/events/{slug}/readiness

Evaluate event readiness

events:read

POST/events/{slug}/publish

Publish after readiness checks

events:write· idempotent

POST/events/{slug}/unpublish

Unpublish without notifying by default

events:write· idempotent

POST/events/{slug}/cancel

Cancel without notifying by default

events:write· idempotent

POST/events/{slug}/duplicate

Duplicate selected event resources

events:write· idempotent

POST/events/{slug}/archive

Archive while preserving recordings and analytics

events:write· idempotent

Guests8

GET/events/{slug}/guests

List guests and panelists

guests:read

POST/events/{slug}/guests

Create a guest; invitation defaults off

guests:write· idempotent

GET/events/{slug}/guests/{guest_id}

Get guest readiness and history

guests:read

PATCH/events/{slug}/guests/{guest_id}

Update a guest without sending

guests:write

DELETE/events/{slug}/guests/{guest_id}

Soft-delete and optionally revoke guest access

guests:write

POST/events/{slug}/guests/{guest_id}/access-link

Create, rotate or revoke backstage access

guests:write· idempotent

POST/events/{slug}/guests/{guest_id}/invite

Preview, draft, schedule or send a guest invitation

guests:write· idempotent

POST/events/{slug}/guests/{guest_id}/resend-invite

Draft or explicitly resend a guest invitation

guests:write· idempotent

Registrations9

GET/events/{slug}/registrations

List registrations

registrations:read

POST/events/{slug}/registrations

Create a registration; confirmation defaults off

registrations:write· idempotent

POST/events/{slug}/registrations/validate

Validate and deduplicate without writing

registrations:write

POST/events/{slug}/registrations/bulk

Safe bulk import; confirmation defaults off

registrations:write· idempotent

GET/events/{slug}/registrations/imports/{job_id}

Get bulk import progress and errors

registrations:read

PATCH/events/{slug}/registrations/{registration_id}

Update registration and re-deduplicate email

registrations:write

DELETE/events/{slug}/registrations/{registration_id}

Soft-delete a registration

registrations:write

POST/events/{slug}/registrations/{registration_id}/confirmation

Preview, draft or explicitly send confirmation

registrations:write· idempotent

GET/events/{slug}/registrations/export

Create a short-lived registration export URL

registrations:read

Communications7

GET/events/{slug}/communications

List event communications

communications:draft

POST/events/{slug}/communications/preview

Render without saving or sending

communications:draft

POST/events/{slug}/communications/drafts

Save drafts; this endpoint never sends

communications:draft· idempotent

GET/events/{slug}/communications/{message_id}

Get communication and provider events

communications:draft

POST/events/{slug}/communications/{message_id}/send

Queue delivery; send=true is mandatory

communications:send· idempotent

POST/events/{slug}/communications/{message_id}/schedule

Schedule delivery; send=true is mandatory

communications:send· idempotent

POST/events/{slug}/communications/{message_id}/cancel

Cancel a scheduled or queued message

communications:draft· idempotent

Run of show5

GET/events/{slug}/plan

Get the structured run of show

events:read

PUT/events/{slug}/plan

Create or replace the structured run of show

events:write

POST/events/{slug}/plan/generate

Generate a draft run of show

events:write· idempotent

POST/events/{slug}/plan/validate

Validate timing and assignments

events:write

POST/events/{slug}/segments/reorder

Atomically reorder all segments

events:write· idempotent

Signup pages6

GET/events/{slug}/signup

Get draft and published signup content

events:read

PATCH/events/{slug}/signup

Version signup-page content

events:write

POST/events/{slug}/signup/preview

Create a short-lived preview

events:write

POST/events/{slug}/signup/publish

Publish current signup version

events:write· idempotent

GET/events/{slug}/signup/versions

List signup versions

events:read· idempotent

POST/events/{slug}/signup/rollback

Roll back without publishing by default

events:write· idempotent

Rehearsals8

GET/events/{slug}/rehearsals

List rehearsals

events:read

POST/events/{slug}/rehearsals

Create rehearsal

events:write· idempotent

GET/events/{slug}/rehearsals/{rehearsal_id}

Get rehearsal

events:read

PATCH/events/{slug}/rehearsals/{rehearsal_id}

Update rehearsal

events:write

DELETE/events/{slug}/rehearsals/{rehearsal_id}

Soft-delete rehearsal

events:write

POST/events/{slug}/rehearsals/{rehearsal_id}/invite

Draft or explicitly send rehearsal invitations

communications:draft· idempotent

GET/events/{slug}/technical-checks

List technical checks

events:read

POST/events/{slug}/technical-checks

Record a technical check

events:write· idempotent

Partners10

GET/events/{slug}/vendors

List vendors

events:read

POST/events/{slug}/vendors

Create vendor

events:write· idempotent

GET/events/{slug}/vendors/{vendor_id}

Get vendor

events:read

PATCH/events/{slug}/vendors/{vendor_id}

Update vendor

events:write

DELETE/events/{slug}/vendors/{vendor_id}

Soft-delete vendor

events:write

GET/events/{slug}/sponsors

List sponsors

events:read

POST/events/{slug}/sponsors

Create sponsor

events:write· idempotent

GET/events/{slug}/sponsors/{sponsor_id}

Get sponsor

events:read

PATCH/events/{slug}/sponsors/{sponsor_id}

Update sponsor

events:write

DELETE/events/{slug}/sponsors/{sponsor_id}

Soft-delete sponsor

events:write

Assets4

POST/assets/uploads

Create a short-lived direct upload

assets:write· idempotent

POST/assets/{asset_id}/complete

Validate digest and complete upload

assets:write· idempotent

GET/assets/{asset_id}

Get asset metadata and download URL

assets:read

DELETE/assets/{asset_id}

Soft-delete an unreferenced asset

assets:write

Promo kit4

GET/events/{slug}/promo-kit

Get promotional assets and approval states

events:read

POST/events/{slug}/promo-kit/generate

Queue promotional asset generation

content:write· idempotent

GET/events/{slug}/promo-kit/jobs/{job_id}

Get promotional generation progress

events:read

POST/events/{slug}/promo-kit/bundle

Create a short-lived promo-kit bundle

content:write· idempotent

Live studio8

GET/events/{slug}/studio

Get live studio state and command catalog

studio:read

POST/events/{slug}/studio

Execute one validated legacy studio command

studio:control· idempotent

POST/events/{slug}/studio/commands/preview

Normalize commands without executing

studio:control

POST/events/{slug}/studio/commands

Execute acknowledged atomic studio commands

studio:control· idempotent

GET/events/{slug}/studio/commands/{command_id}

Get command acknowledgement and result

studio:read· idempotent

POST/events/{slug}/studio/commands/{command_id}/undo

Undo a command with a documented inverse

studio:control· idempotent

GET/events/{slug}/studio/history

Get studio command history

studio:read· idempotent

POST/events/{slug}/studio/emergency-stop

Stop the live room with explicit confirmation

studio:emergency· idempotent

Recordings & shorts6

GET/events/{slug}/recordings

List program recordings, speaker tracks and clips

recordings:read

GET/events/{slug}/shorts

List generated short-form clips

recordings:read

POST/events/{slug}/shorts/analyze

Analyze recording for short-form segments

content:write· idempotent

POST/events/{slug}/shorts/jobs

Create a short-form processing job

content:write· idempotent

POST/events/{slug}/shorts/segments

Create a candidate short-form segment

content:write· idempotent

POST/events/{slug}/shorts/render

Queue short-form rendering

content:write· idempotent

Post-event content7

GET/events/{slug}/transcript

Get transcript in JSON, text or caption formats

events:read· idempotent

PATCH/events/{slug}/transcript

Apply timestamped transcript corrections

content:write· idempotent

POST/events/{slug}/transcript/generate

Queue transcript generation

content:write· idempotent

POST/events/{slug}/content/generate

Generate draft post-event content

content:write· idempotent

GET/events/{slug}/content

List generated content

events:read· idempotent

POST/events/{slug}/distribution/preview

Preview without publishing

content:write

POST/events/{slug}/distribution/jobs

Draft or explicitly queue publication

distribution:publish· idempotent

Webhooks8

GET/webhooks

List webhooks without secrets

webhooks:manage

POST/webhooks

Create a webhook and return its secret once

webhooks:manage· idempotent

GET/webhooks/{webhook_id}

Get webhook without secret

webhooks:manage

PATCH/webhooks/{webhook_id}

Update URL, events or active state

webhooks:manage

DELETE/webhooks/{webhook_id}

Soft-delete and revoke signing secret

webhooks:manage

POST/webhooks/{webhook_id}/test

Deliver a signed synthetic event

webhooks:manage· idempotent

GET/webhooks/{webhook_id}/deliveries

List delivery attempts

webhooks:manage

POST/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Retry with the original stable event ID

webhooks:manage· idempotent

Audit log1

GET/audit-log

List redacted mutation audit records

audit:read

07 · Errors & retries

Branch on codes, debug with request IDs.

Every failed SDK call throws ShowrunnerError with status, code, and message. Retry only when error.retryable is true.

HTTPCodeWhat to do

400validation_errorRequest shape, confirmation, or idempotency-key error.

401unauthorizedMissing, invalid, or expired API key.

403insufficient_scopeThe key is valid but lacks the operation scope.

404not_foundResource missing or outside the key’s workspace.

409version_conflictStale expected_version or conflicting operation state.

409idempotency_conflictThe same idempotency key was reused with a new payload.

429rate_limitedWait until X-RateLimit-Reset before retrying.

500internal_errorUnexpected failure; share meta.request_id with support.

javascript

try {
  await flarea.events.get('missing-event');
} catch (error) {
  if (error.status === 404 && error.code === 'not_found') {
    // Ask for a valid slug — do not retry.
  }
}

08 · Webhooks

Signed events with replay protection.

Webhook delivery is at least once. Verify the HMAC against the raw body, reject stale timestamps, and deduplicate on the stable event ID.

X-Flarea-EventX-Flarea-Event-IdX-Flarea-TimestampX-Flarea-Signature

javascript

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyFlareaWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-flarea-timestamp'];
  const received = headers['x-flarea-signature'];
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return timingSafeEqual(
    Buffer.from(received),
    Buffer.from(expected),
  );
}

Ready to build?

Your first API key is one signup away.

Create an account, generate a 24-hour test key, and ship your first event integration today.

Create account & get key →