# Flarea SDK and developer API

Flarea is the shortest server-side path from "build a webinar or live showroom" to a working product. One authenticated POST /v1/showrooms creates the event, AI run of show, host studio, signup page, receive-only stage-request door, and viewer destination. Scheduled speakers use personal backstage access links; the shared guest_link never grants publishing by itself. Flarea operates the media, event, recording, storage, and reliability layers behind one stable contract.

Base URL: https://api.flarea.ai
Canonical website SDK documentation: https://flarea.ai/developers
Full agent context: https://flarea.ai/llms-full.txt
OpenAPI 3.1 primary reference: https://api.flarea.ai/v1/openapi.json
OpenAPI 3.1 compatibility reference: https://api.flarea.ai/api/v1/openapi.json
JavaScript SDK source: https://github.com/asafktz/webinar-show/tree/main/sdk/flarea-js
Python SDK source: https://github.com/asafktz/webinar-show/tree/main/sdk/python
Start free with Google: https://flarea.ai/auth?mode=signup&developer=1&next=%2Fdevelopers%2Fstart

https://api.flarea.ai is the active canonical API hostname. The legacy https://webinar-show.vercel.app hostname remains compatible.

## Authenticated Free tier

Free is for real integration testing, not anonymous production traffic. Google OAuth is required before Flarea provisions a developer account. Free includes 20 build credits (a hard $0.20 monthly reserved-internal-cost ceiling), 1,000 API requests, 3 showroom creates, 2 managed clients per calendar month, and short-lived test keys. It does not issue production keys. Every resource remains owner-scoped, metered, rate-limited, and visible to Flarea operations.

Build credits weight operations by conservative worst-case cost before provider work starts. One build credit represents up to $0.01 of reserved internal cost; it is not money or a bill. Ordinary request overhead uses 0.0002 credit per request, an AI showroom plan uses 1 credit, a clip-analysis cache miss uses 8 credits, and one clip render or re-edit up to 120 seconds uses 10 credits. Cached analysis is free. Automatic transcription and other unbounded media jobs are dry-run-only on Free. Cost-bearing mutations require Idempotency-Key. Concurrent reservations are atomic; a request that would cross $0.20 fails before provider work with HTTP 402 cost_credit_exhausted. Read cost_budget from GET /v1/usage or X-Flarea-Cost-Remaining-USD from response headers.

## Agent quickstart

1. Ask the user for FLAREA_API_KEY or direct them to Start free with Google. Never invent a key and never put it in browser code.
2. Create one client per customer: POST /v1/clients {"name":"Acme","external_id":"your_customer_id"}.
3. Create a showroom: POST /v1/showrooms with title, brief, and client_id. Send Authorization: Bearer, Content-Type: application/json, and Idempotency-Key.
4. Persist data.showroom.slug, links, meta.request_id, and the client mapping.
5. Retry only retryable failures and reuse the same Idempotency-Key for the same mutation.
6. Read GET /v1/usage for cost/error attribution.

There is no anonymous sandbox. The website playground and every live example require an authenticated, metered API key.

## Additive /v1 facade

- GET/POST /v1/clients
- GET/PATCH /v1/clients/{id}
- GET/POST /v1/showrooms
- POST /v1/examples/run {"example":"showroom", ...}
- GET /v1/usage?days=30

Existing /api/v1/** operations and the legacy SDK package ID remain backward compatible.