{"openapi":"3.1.0","info":{"title":"Flarea Agent API","version":"1.0.0","description":"Agent-first, additive facade for managed clients, one-call live showrooms, keyed examples, and usage. Existing /api/v1 endpoints remain compatible.","license":{"name":"Proprietary API terms","url":"https://flarea.ai/terms"}},"servers":[{"url":"https://api.flarea.ai","description":"Production"}],"externalDocs":{"description":"Human and LLM-focused documentation","url":"https://flarea.ai/developers"},"security":[{"bearerAuth":[]}],"tags":[{"name":"Clients","description":"Developer-managed end-customer/subaccount boundaries."},{"name":"Showrooms","description":"Prompt-shaped live webinar orchestration."},{"name":"Examples","description":"Real, authenticated recipes. No anonymous resources."},{"name":"Usage","description":"Owner-scoped metering and cost attribution."}],"paths":{"/v1/clients":{"get":{"operationId":"listClients","tags":["Clients"],"summary":"List managed clients","x-agent-purpose":"Discover the customer/subaccount IDs owned by this API workspace.","responses":{"200":{"description":"Clients","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}},"post":{"operationId":"createClient","tags":["Clients"],"summary":"Create a managed client","x-required-scope":"events:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique intent identifier. Reuse only to retry the identical mutation.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"external_id":{"type":"string","maxLength":160},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Created client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}}},"/v1/clients/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getClient","tags":["Clients"],"summary":"Get a managed client","responses":{"200":{"description":"Client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}},"patch":{"operationId":"updateClient","tags":["Clients"],"summary":"Update or suspend a managed client","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique intent identifier. Reuse only to retry the identical mutation.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["active","suspended","archived"]},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Updated client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}}},"/v1/showrooms":{"get":{"operationId":"listShowrooms","tags":["Showrooms"],"summary":"List owned showrooms","parameters":[{"name":"client_id","in":"query","schema":{"type":"string","description":"Client UUID or external_id."}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Showrooms","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","links"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"dry_run":{"type":"boolean"},"segments":{"type":"array","items":{"type":"string"}},"links":{"type":"object","required":["studio","signup_page","guest_link","viewer_link"],"properties":{"studio":{"type":"string","format":"uri"},"signup_page":{"type":"string","format":"uri"},"guest_link":{"type":"string","format":"uri"},"viewer_link":{"type":"string","format":"uri"}}}}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}},"post":{"operationId":"createShowroom","tags":["Showrooms"],"summary":"Create a working live showroom in one call","description":"Creates the event and returns hosted studio, signup, guest, and viewer destinations. A default managed client is created when client_id is omitted.","x-agent-purpose":"Use this first for build-a-webinar or build-a-live-showroom requests.","x-required-scope":"events:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique intent identifier. Reuse only to retry the identical mutation.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":120},"brief":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"client_id":{"type":"string"},"external_client_id":{"type":"string"},"generate_show_plan":{"type":"boolean","default":true},"dry_run":{"type":"boolean","default":false},"guests":{"type":"array","items":{"type":"object","additionalProperties":true}},"brand":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Created showroom and client mapping","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","required":["showroom","client"],"properties":{"showroom":{"type":"object","required":["slug","links"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"dry_run":{"type":"boolean"},"segments":{"type":"array","items":{"type":"string"}},"links":{"type":"object","required":["studio","signup_page","guest_link","viewer_link"],"properties":{"studio":{"type":"string","format":"uri"},"signup_page":{"type":"string","format":"uri"},"guest_link":{"type":"string","format":"uri"},"viewer_link":{"type":"string","format":"uri"}}}}},"client":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}}},"/v1/examples/run":{"post":{"operationId":"runExample","tags":["Examples"],"summary":"Run a real authenticated SDK example","description":"No anonymous/free resources. Currently supports example=showroom inside the key owner account; dry_run validates the same authenticated path without persisting an event.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique intent identifier. Reuse only to retry the identical mutation.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["example"],"properties":{"example":{"type":"string","const":"showroom"},"title":{"type":"string"},"brief":{"type":"string"},"client_id":{"type":"string"},"generate_show_plan":{"type":"boolean","default":true},"dry_run":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Created example resource","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","properties":{"showroom":{"type":"object","required":["slug","links"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"dry_run":{"type":"boolean"},"segments":{"type":"array","items":{"type":"string"}},"links":{"type":"object","required":["studio","signup_page","guest_link","viewer_link"],"properties":{"studio":{"type":"string","format":"uri"},"signup_page":{"type":"string","format":"uri"},"guest_link":{"type":"string","format":"uri"},"viewer_link":{"type":"string","format":"uri"}}}}},"client":{"type":"object","required":["id","name","environment","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"external_id":{"type":["string","null"]},"environment":{"type":"string","enum":["test","live"]},"status":{"type":"string","enum":["active","suspended","archived"]},"plan_code":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Usage"],"summary":"Read owner-scoped developer API usage","x-required-scope":"analytics:read","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Usage summary and recent rows","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"object","properties":{"window_days":{"type":"integer"},"requests":{"type":"integer"},"errors":{"type":"integer"},"estimated_cost_usd":{"type":"number"},"items":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"},"version":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"error":{"type":"null"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, or expired API key","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"403":{"description":"Insufficient key scope","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"409":{"description":"Conflict or inactive client","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}},"500":{"description":"Internal error with request ID","content":{"application/json":{"schema":{"type":"object","required":["data","meta","error"],"properties":{"data":{"type":"null"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","examples":["req_018f…"]}}},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"retryable":{"type":"boolean"}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Flarea API key","description":"Server-side sr_test_* or sr_live_* key."}}}}