{ "openapi": "3.1.0", "info": { "title": "Application API", "description": "OpenAPI specification for the HTTP API.", "version": "1.0.0" }, "servers": [ { "url": "https://api.moosky.ai/api", "description": "Base API server (bare host — routes are mounted at the root, no /api prefix)." } ], "paths": { "/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List the current user's API keys", "operationId": "b35df5b76a65bb259446547c3fd61f45", "responses": { "200": { "description": "API keys owned by the authenticated user, newest first (secret never included). Each key includes mcpGrant (null for general keys).", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyDto" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create an API key (plaintext secret is revealed once, here only)", "operationId": "00e1dccc554b23180adddc619a8b3c0d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 60, "example": "production-automation" }, "type": { "description": "Defaults to general. An mcp key requires the mcp block.", "type": "string", "enum": [ "general", "mcp" ] }, "mcp": { "description": "Only valid when type is mcp. Omit servers (or send null) to allow all nine MCP servers. mcp:project-video is not issuable.", "properties": { "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp:read", "mcp:write", "mcp:generate" ] } }, "servers": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "platform", "video", "image-edit", "music-generate", "text-to-image", "text-to-speech", "upscale-video", "upscale-image", "utilities" ] } }, "rate_limit_per_minute": { "description": "Optional per-key requests per minute. Null falls back to services.mcp.default_rate_limit_per_minute, then services.mcp.rate_limit_per_minute.", "type": [ "integer", "null" ], "maximum": 10000, "minimum": 1 }, "max_daily_generations": { "description": "Optional per-key daily generation cap. Null falls back to services.mcp.default_daily_generation_cap, then services.mcp.daily_generation_cap_per_key_default. Zero blocks every generation.", "type": [ "integer", "null" ], "maximum": 100000, "minimum": 0 } }, "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Key created; clientSecret is shown exactly once and cannot be retrieved again", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "apiKey": { "$ref": "#/components/schemas/ApiKeyDto" }, "clientSecret": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation failed or active-key cap (10) reached", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "429": { "description": "Too many key creations in the last minute", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/api-keys/{id}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key (kept for history; its minted tokens stop working)", "operationId": "1b44437ad6aa6798d9edc858c6ee98bc", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "apiKey": { "$ref": "#/components/schemas/ApiKeyDto" } }, "type": "object" } } } }, "404": { "description": "Key not found or not owned by the authenticated user", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/api-keys/webhooks": { "get": { "tags": [ "API Keys" ], "summary": "List webhook endpoints registered under the user's API keys", "description": "Read-only view of webhook endpoints registered under the current user's\nkeys (Tyler 2026-10-08: Webhooks card on the Option B /developer page).\nSecrets are never exposed (WebhookEndpoint model hides `secret`).", "operationId": "927bcc603b4e2c726b25c7b9726f2d23", "responses": { "200": { "description": "Webhook endpoints across all of the user's keys, newest first", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointDto" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new user", "operationId": "08136088c4862c313b35d6518bab8d3a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "password_confirmation": { "type": "string", "format": "password" }, "marketingOptIn": { "type": [ "boolean", "null" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "User registered", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User registered successfully" }, "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/attribution": { "post": { "tags": [ "Auth" ], "summary": "Record first-party signup attribution", "description": "ADO #5920 — record first-party signup attribution for the authenticated\nuser. Called by every signup path (email form, Google/Apple OAuth return)\nAFTER the session token exists, so the same endpoint works for all three\nand the target user always comes from the auth guard (never from the\nbody — a caller cannot forge another user's attribution). Idempotent: the\nfirst write sticks, later calls are no-ops.", "operationId": "87a888020ee1a1af70611b48c9446095", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "referrer": { "type": [ "string", "null" ] }, "utmSource": { "type": [ "string", "null" ] }, "utmMedium": { "type": [ "string", "null" ] }, "utmCampaign": { "type": [ "string", "null" ] }, "utmTerm": { "type": [ "string", "null" ] }, "utmContent": { "type": [ "string", "null" ] }, "gclid": { "type": [ "string", "null" ] }, "gbraid": { "type": [ "string", "null" ] }, "wbraid": { "type": [ "string", "null" ] }, "msclkid": { "type": [ "string", "null" ] }, "fbclid": { "type": [ "string", "null" ] }, "landingPath": { "type": [ "string", "null" ] }, "firstSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "signupMethod": { "type": [ "string", "null" ], "enum": [ "email", "google", "apple" ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Attribution recorded (or already present)" }, "401": { "description": "Unauthenticated" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Login and obtain token", "operationId": "99d66635c4992aeaa6aa44ff653d0563", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Authenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Login successful" }, "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Request a password reset link", "operationId": "fea89d2766defe4ad877001920e3f289", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } }, "type": "object" } } } }, "responses": { "202": { "description": "Reset request accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "If an account exists for that email, a password reset link has been sent." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Reset a password with a mailed token", "operationId": "b8d03d5b689dcb65d3771f62d4f90a24", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "token", "password", "password_confirmation" ], "properties": { "email": { "type": "string", "format": "email" }, "token": { "type": "string" }, "password": { "type": "string", "format": "password" }, "password_confirmation": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "202": { "description": "Password reset", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Your password has been reset. Please sign in." } }, "type": "object" } } } }, "400": { "description": "Invalid or expired reset link", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout and revoke token", "operationId": "6abf3b64a4bc7838d56346f05a5153af", "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/auth/user": { "get": { "tags": [ "Auth" ], "summary": "Get current user", "operationId": "32d03117b496ae02c2543b61438d24ad", "responses": { "200": { "description": "Current user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh the current token", "operationId": "e7ab7446393758bb71fd1946a349e500", "requestBody": { "required": false, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Token refreshed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Token refreshed successfully" }, "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/api-key/token": { "post": { "tags": [ "Auth" ], "summary": "Exchange API key credentials for a token", "operationId": "2f96ce47ee051c98ba94c079e893462f", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "API key authenticated successfully" }, "api_key_id": { "type": "integer" }, "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Missing credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/billing/config": { "get": { "tags": [ "Billing" ], "summary": "Get Stripe publishable configuration", "description": "Public route; when the caller presents a bearer credential its stored preferredCountry/preferredCurrency (Epic #3363) narrow the advertised paymentMethods list to the SAME country-gated set createPaymentIntent enforces (PR #868 review, thread 15051). Guests and unauthenticated visitors keep the currency-only list.", "operationId": "8fdd83555c4095f1cb63e83df05643a9", "responses": { "200": { "description": "Stripe configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConfig" } } } } }, "security": [] } }, "/billing/expiring-credits": { "get": { "tags": [ "Billing" ], "summary": "Soonest-expiring credit lot for the balance surface", "description": "Returns the soonest-expiring spendable lot that still holds credits and expires within the reminder window, so the portal can show 'X credits expire on DATE' (Epic #3500 wave 2). Null fields when nothing is expiring (e.g. on-demand-only accounts whose lots never expire).", "operationId": "d59c5ad795c33b93ef8c1617c2f25a13", "responses": { "200": { "description": "Expiring-lot summary", "content": { "application/json": { "schema": { "properties": { "credits": { "type": [ "integer", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } } } }, "/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Current subscription plan state for the balance surface", "description": "Returns the signed-in user's subscription so /credits can render the plan (Epic #3500 wave 3). `{ hasSubscription: false }` for on-demand-only accounts; an OPEN plan carries its slug, interval, monthly price, monthly grant, and period end. A canceled-but-most-recent plan is reported with hasSubscription:false but echoes the plan slug + status:'canceled' so the surface can acknowledge it rather than pretend no plan ever existed.", "operationId": "8cb6d2b79be3d8a669d9393d2a2435e4", "responses": { "200": { "description": "Subscription state", "content": { "application/json": { "schema": { "properties": { "hasSubscription": { "type": "boolean" }, "status": { "type": [ "string", "null" ] }, "planSlug": { "type": [ "string", "null" ] }, "interval": { "type": [ "string", "null" ] }, "priceCents": { "type": [ "integer", "null" ] }, "creditsGranted": { "type": [ "integer", "null" ] }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "cancellationAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } } } }, "/billing/capabilities": { "get": { "tags": [ "Billing" ], "summary": "Read-only country/currency capability matrix", "description": "Supported countries, their default and supported currencies, and the full currency registry (Epic #3363 country-currency-foundation). Drives checkout currency selection; prices remain USD until regional-pricing ships.", "operationId": "759f6c515500cc919047918c7a064a37", "responses": { "200": { "description": "Capability matrix", "content": { "application/json": { "schema": { "properties": { "defaultCurrency": { "type": "string" }, "currencies": { "type": "array", "items": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "minorUnits": { "type": "integer" } }, "type": "object" } }, "countries": { "type": "array", "items": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "defaultCurrency": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [] } }, "/billing/payment-capabilities": { "get": { "tags": [ "Billing" ], "summary": "Payment-capability resolver: allowed methods per country/currency", "description": "Epic #3363 payment-regionalization: resolves (country, currency) -> the Stripe payment methods a checkout may offer, and the per-country default matrix. allowedMethods null = regionalization off for the context (Stripe automatic payment methods decide); [] = regionalized with no method available (checkout refuses); a list = the exact payment_method_types the intent carries. Method enablement is region-gated behind billing.payment_regionalization config.", "operationId": "b6b6d8aa93f32e6344b202df72a4e908", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2, "minLength": 2 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 } } ], "responses": { "200": { "description": "Resolved capability + per-country matrix", "content": { "application/json": { "schema": { "properties": { "regionalizationEnabled": { "type": "boolean" }, "resolved": { "properties": { "country": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "regionalizationEnabled": { "type": "boolean" }, "allowedMethods": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "type": "object" }, "matrix": { "type": "array", "items": { "properties": { "country": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "regionalizationEnabled": { "type": "boolean" }, "allowedMethods": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "type": "object" } } }, "type": "object" } } } } }, "security": [] } }, "/billing/currency-preference": { "put": { "tags": [ "Billing" ], "summary": "Set the current user's preferred selling currency", "operationId": "e41dc4cc6de77d595a8308ddadbf87bd", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "currency" ], "properties": { "currency": { "description": "lower-case ISO 4217 code", "type": "string" }, "country": { "description": "optional ISO 3166-1 alpha-2 country; when sent the pair is validated", "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated user payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/billing/credit-packages": { "get": { "tags": [ "Billing" ], "summary": "List credit packages", "operationId": "19b9756e98e0280b26a2c2a40e3f6038", "responses": { "200": { "description": "Available packages", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPackageDto" } } } } } } } }, "/billing/priced-packages": { "get": { "tags": [ "Billing" ], "summary": "List credit packages priced for a selling context", "description": "Server-authoritative regional pricing (Epic #3363 regional-pricing): resolves the country price-book row, then the global per-currency row, then the USD invariant book. The client supplies only a CURRENCY intent at most; the charged figure always comes from the server's purchasable row. fx figures are display estimates only and only when the config policy allows. USD/no-context responses are byte-identical to /credit-packages.", "operationId": "c1259119c0e046e04fe4733abde1dd2c", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2, "minLength": 2 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 } } ], "responses": { "200": { "description": "Priced packages", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "numCredits": { "type": "integer" }, "priceCents": { "type": "integer" }, "currency": { "type": "string" }, "sellingAmountMinor": { "type": "integer" }, "chargeAuthority": { "type": "string" } }, "type": "object" } } } } } }, "security": [] } }, "/admin/v1/billing/regional-price-books/publish": { "post": { "tags": [ "Billing" ], "summary": "Publish a regional price-book row from the USD cost", "description": "Ops publishing for Epic #3363 regional-pricing. The selling amount is DERIVED server-side from the package's fixed USD cost * fx and refused outside the profit band — callers cannot hand in an independent per-market price. Idempotent on (package, country, currency).", "operationId": "443ace8bef977df9aa41351894ab378c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "creditPackageId", "currency", "fxRate" ], "properties": { "creditPackageId": { "type": "integer" }, "country": { "description": "ISO alpha-2; omit/null for the global per-currency book", "type": [ "string", "null" ] }, "currency": { "type": "string" }, "fxRate": { "description": "USD -> currency reference snapshot", "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "Published row" }, "422": { "description": "Validation error (unsupported pair / outside profit band)" } } } }, "/billing/create-payment-intent": { "post": { "tags": [ "Billing" ], "summary": "Create payment intent", "operationId": "5e9bb636c5f6054c8e2d5c8381b8b0e3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amountCents" ], "properties": { "amountCents": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/billing/payment-intents/{paymentIntentId}/calculate-tax": { "post": { "tags": [ "Billing" ], "summary": "Calculate tax for a payment intent", "operationId": "70401c74ee761b55b82a63f594e77b57", "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "address" ], "properties": { "address": { "required": [ "line1", "city", "country" ], "properties": { "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tax calculation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCalculationDto" } } } }, "404": { "description": "Tax not enabled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/billing/subscription-checkout-sessions": { "post": { "tags": [ "Billing" ], "summary": "Create a Stripe Checkout Session for a subscription", "operationId": "1c97027bc2f38a089dfe5c763b2b3257", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "planSlug", "interval", "consentAccepted", "disclosureTextKey" ], "properties": { "planSlug": { "type": "string", "maxLength": 64 }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "consentAccepted": { "description": "ADO #7468 California ARL: express affirmative consent to auto-renewal; must be true", "type": "boolean" }, "disclosureTextKey": { "description": "Catalog key of the disclosure text the user saw", "type": "string", "enum": [ "credits.autoRenewalDisclosure" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/billing/subscription-plans": { "get": { "tags": [ "Billing" ], "summary": "List active subscription plans", "description": "Active plans with computed savings vs the on-demand 100-credits-per-$1 invariant (Epic #3500 wave 3). Public surface like /billing/credit-packages — plan prices are not secret. Returns 404 when the subscriptions flags are off so the experiment is invisible (Epic CLOSE-WHEN: plans hidden via config without deploying).", "operationId": "6effdbb9b7e1c661ab0154c69b394e48", "responses": { "200": { "description": "Plan catalog", "content": { "application/json": { "schema": { "properties": { "plans": { "type": "array", "items": { "properties": { "slug": { "type": "string" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "priceCents": { "type": "integer" }, "creditsGranted": { "type": "integer" }, "onDemandCentsForCredits": { "type": "integer" }, "savingsCents": { "type": "integer" }, "savingsPercent": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Subscriptions disabled or not configured" } }, "security": [] } }, "/billing/subscription/cancel": { "post": { "tags": [ "Billing" ], "summary": "Cancel the active subscription at period end", "description": "Sets cancel_at_period_end on the Stripe subscription (Epic #3500 wave 3). The plan stays usable until the current period end; already-granted credits are not clawed back and expire on their own schedule. Idempotent — cancelling an already-pending cancellation succeeds.", "operationId": "d1eae991fcd4473b07da3f3199dc0d56", "responses": { "200": { "description": "Cancellation scheduled", "content": { "application/json": { "schema": { "properties": { "canceledAtPeriodEnd": { "type": "boolean" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Subscriptions disabled or not configured" }, "422": { "description": "No active subscription to cancel", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/billing/subscription/portal": { "post": { "tags": [ "Billing" ], "summary": "Open the Stripe billing portal", "description": "Creates a Stripe-hosted billing-portal session so the user can manage payment methods and invoices (Epic #3500 wave 3). Returns the session url; the caller redirects the browser there. Returns 404 when the subscriptions flags are off and 422 when no Stripe customer exists yet (user never reached checkout) or the portal return URL is unconfigured.", "operationId": "98b19d83e5cc356e6a9d6d630b94175a", "responses": { "200": { "description": "Billing portal session", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "format": "uri" } }, "type": "object" } } } }, "404": { "description": "Subscriptions disabled or not configured" }, "422": { "description": "No billing account yet or portal not configured", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/billing/purchase-tracked": { "post": { "tags": [ "Billing" ], "summary": "Acknowledge a client-side GA4 purchase event", "description": "ADO #5920 — client-side GA4 purchase ack.\n\nThe portal calls this right after its gtag purchase event fires, so the\ndelayed server-side Measurement Protocol fallback can tell a blocked\nbrowser (no gtag ever loaded -> purchase missing from GA4) from a\nnormal one (event already reported). The ack just flips a short-lived\ncache gate keyed by PaymentIntent id; no DB write, no user data.", "operationId": "c6f6446eb2c4f5010b51e49c10246abe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "paymentIntentId" ], "properties": { "paymentIntentId": { "type": "string", "example": "pi_abc123" } }, "type": "object" } } } }, "responses": { "204": { "description": "Ack recorded" }, "422": { "description": "Missing or unknown paymentIntentId" } } } }, "/billing/webhook": { "post": { "tags": [ "Billing" ], "summary": "Stripe webhook endpoint", "operationId": "11555829615560b0bb90fdb32e18b7f0", "responses": { "200": { "description": "Event received", "content": { "application/json": { "schema": { "properties": { "received": { "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Invalid payload or signature", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } }, "503": { "description": "Subscription money event deferred for Stripe retry because the billing rollout flags are off (ADO #6779). Stripe re-delivers with a fresh signature once it retries; the replayed event is granted idempotently once the flags are restored.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "billing.webhook_deferred" }, "message": { "type": "string" }, "eventId": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels", "operationId": "c43decf13e02f8a8f9bdbaaa39dd39ba", "responses": { "200": { "description": "Channels for the current user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelDto" } } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Create channel", "operationId": "13fbfe5c22d49eab95e82850d1ab5d9a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "platformIds": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Channel created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/channels/{id}": { "get": { "tags": [ "Channels" ], "summary": "Get a channel", "operationId": "84d131fb39b296eada0c295fa8c689fc", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Channel details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDto" } } } }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "put": { "tags": [ "Channels" ], "summary": "Update a channel", "operationId": "b40ae6cd630e07a8c57a74d7aae43b70", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Channel updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDto" } } } }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Delete a channel", "operationId": "83b92ac2716fd1d5777168bb27db5bd0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Channel deleted" }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/channels/{id}/platforms/{platformId}": { "post": { "tags": [ "Channels" ], "summary": "Link platform to channel", "operationId": "d9b7cc509b706cd173ddda3ddbb5c74c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "platformId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Platform linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDto" } } } }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Channels" ], "summary": "Unlink platform from channel", "operationId": "2032b06f60f8bff98b13c22267d74f5f", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "platformId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Platform unlinked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelDto" } } } }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/channels/{channelId}/platforms/{platformId}/upload": { "post": { "tags": [ "Channels" ], "summary": "Upload project to a platform", "operationId": "ef93a1626e62973860987a1e912440eb", "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "platformId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "projectId", "config" ], "properties": { "projectId": { "type": "integer" }, "config": { "properties": { "privacyStatus": { "type": "string", "enum": [ "public", "private", "unlisted" ] } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Upload result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUploadResultDto" } } } }, "404": { "description": "Channel or platform not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "500": { "description": "Upload failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/scenes/{sceneId}/executions/clip-cuts": { "post": { "tags": [ "Scene Executions" ], "summary": "Queue a clip-cut derived take", "description": "Queue a clip-cut derived take for a completed source video execution.", "operationId": "633900a9365ad6474fe2ee5195fdecbd", "parameters": [ { "name": "sceneId", "in": "path", "description": "Scene identifier", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sourceExecutionId", "editSpec" ], "properties": { "sourceExecutionId": { "type": "integer" }, "editSpec": { "required": [ "segments" ], "properties": { "segments": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "responses": { "202": { "description": "Clip-cut execution queued", "content": { "application/json": { "schema": { "properties": { "executionId": { "type": "integer" }, "status": { "type": "string", "example": "queued" } }, "type": "object" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Invalid source execution or edit spec", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/auth/verify-email": { "post": { "tags": [ "Auth" ], "summary": "Verify an email address with a mailed token", "operationId": "abc151ee593efc8cc4c18b27cf3da379", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "userid", "token" ], "properties": { "userid": { "type": "integer" }, "token": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Your email has been verified." } }, "type": "object" } } } }, "422": { "description": "Invalid or expired verification link", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/auth/verify-email/resend": { "post": { "tags": [ "Auth" ], "summary": "Request another email verification link", "operationId": "f462b5651be8ce6e9e600cab227d6d0b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } }, "type": "object" } } } }, "responses": { "202": { "description": "Resend request accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "If an account exists for that email, a verification link has been sent." } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/platforms": { "get": { "tags": [ "Platforms" ], "summary": "List platforms", "operationId": "c397dfee0139e771a11c0cc8560f5de9", "responses": { "200": { "description": "Supported platforms", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDto" } } } } } } } }, "/automaters": { "get": { "tags": [ "Project Automaters" ], "summary": "List project automaters", "operationId": "9c215a4900a3b08de2fbef2f99594fd5", "responses": { "200": { "description": "Available automaters", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectAutomaterDto" } } } } } } } }, "/channels/{id}/automaters/{automaterId}": { "post": { "tags": [ "Project Automaters" ], "summary": "Trigger project automation", "operationId": "75f2b4ddbd47efc13b7d364e585bb9b4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "automaterId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Automation triggered", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/project-composers": { "get": { "tags": [ "Project Composers" ], "summary": "List project composers", "operationId": "b5d8bd818fa2feaac73d312c44bd5fe4", "responses": { "200": { "description": "Project composer collection", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectComposerDto" } } } } } } } }, "/project-composers/{id}": { "get": { "tags": [ "Project Composers" ], "summary": "Get a project composer by ID", "operationId": "cb551daf3f79fa9dc5a9b5b5bf7132da", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project composer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectComposerDto" } } } }, "404": { "description": "Project composer not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/project-composers/slug/{slug}": { "get": { "tags": [ "Project Composers" ], "summary": "Get a project composer by slug", "operationId": "07af4a35533ff42fb176603acf6da0e1", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project composer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectComposerDto" } } } }, "404": { "description": "Project composer not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "Get all projects", "description": "Get all projects.", "operationId": "396c68608410ed95aae50335aa1fa8a9", "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Project" }, "description": { "type": [ "string", "null" ], "example": "A description of my project" }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/SceneDto" } } }, "type": "object" } } } } } } }, "post": { "tags": [ "Projects" ], "summary": "Create a new project", "description": "Store a newly created project.", "operationId": "3e5e24c249cabe95d4c10927fda15c42", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "My Project" }, "description": { "type": [ "string", "null" ], "example": "A description of my project" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Project created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The name field is required." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get a specific project", "description": "Get a specific project.", "operationId": "72e71445a0072c7dedc46d1d60d36473", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } } } }, "put": { "tags": [ "Projects" ], "summary": "Update a project", "description": "Update the specified project.", "operationId": "cb0265885b60ef4107c9b46487995d73", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255, "example": "Updated Project Name" }, "description": { "type": [ "string", "null" ], "example": "Updated description" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Project updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The name field is required." }, "errors": { "type": "object" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a project", "description": "Delete a project.", "operationId": "6f4a452ac9173b54e596e9453c21f9b6", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Project deleted successfully" }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } } } } }, "/projects/{id}/scenes": { "patch": { "tags": [ "Projects" ], "summary": "Update project scenes", "description": "Update the scenes associated with a project.", "operationId": "1acaecfcbdcbf95c7b508dcc275d4f9a", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "scenes": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "order": { "type": "integer", "example": 0 } }, "type": "object" }, "example": [ { "id": 1, "order": 0 }, { "id": 2, "order": 1 } ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Project scenes updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The scenes field must be present." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/projects/{id}/generate-video": { "post": { "tags": [ "Projects" ], "summary": "Queue a video render for a project", "description": "Queue a video render for a project (combines all selected scene executions).\nThe render runs on the Horizon queue; poll GET /projects/{id}/video-render-status.", "operationId": "96237870221cce94ccffe31dac79c607", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "musicMuted": { "type": "boolean" }, "musicAssetId": { "type": [ "integer", "null" ] }, "timelineFingerprint": { "description": "Portal digest of the timeline editor content being rendered (render staleness)", "type": [ "string", "null" ], "example": "v2:0123456789abcdef" } }, "type": "object" } } } }, "responses": { "202": { "description": "Render queued (or already in flight); poll video-render-status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectVideoRenderStatusDto" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } }, "409": { "description": "Scenes are still rendering; no credits are charged on this path", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Your scenes are still being made. Please wait until every scene has finished rendering, then try again." } }, "type": "object" } } } } } } }, "/projects/{id}/video-render-status": { "get": { "tags": [ "Projects" ], "summary": "Status of the latest queued video render for a project", "operationId": "c59e7b87bfa27c20f7800645382a9985", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "idle | queued | rendering | completed (with project) | failed (with message)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectVideoRenderStatusDto" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/projects/{id}/channels": { "post": { "tags": [ "Projects" ], "summary": "Link a channel to a project", "operationId": "1172cca6403688c503f9e782ecf89f9b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channelId" ], "properties": { "channelId": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Channel linked", "content": { "application/json": { "schema": { "properties": { "project": { "$ref": "#/components/schemas/ProjectDto" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Unlink a channel from a project", "operationId": "077f75f1f79b50145de30db14912ebb1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channelId" ], "properties": { "channelId": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Channel unlinked", "content": { "application/json": { "schema": { "properties": { "project": { "$ref": "#/components/schemas/ProjectDto" } }, "type": "object" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/projects/{projectId}/executions": { "get": { "tags": [ "Project Executions" ], "summary": "List project executions", "description": "List executions for a project.", "operationId": "529ecdb4772d3713bfe797355a4b85a9", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Executions for the project", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectExecutionDto" } } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } }, "post": { "tags": [ "Project Executions" ], "summary": "Create a new execution", "description": "Create a project execution (preview or render).", "operationId": "6c5f2dfa8ce1cbd10c437337ae874039", "parameters": [ { "name": "projectId", "in": "path", "description": "Project identifier", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "projectComposerSlug", "selections", "mode" ], "properties": { "id": { "type": [ "integer", "null" ] }, "projectComposerSlug": { "type": "string" }, "selections": { "type": "array", "items": { "properties": { "optionSlug": { "type": "string" }, "value": { "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" } }, "type": "object" } }, "type": "object" } }, "mode": { "description": "preview: generate scene breakdown only, render: queue executions", "type": "string", "enum": [ "preview", "render" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Execution created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectExecutionDto" } } } }, "404": { "description": "Project or project composer not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/projects/{projectId}/executions/{executionId}": { "get": { "tags": [ "Project Executions" ], "summary": "Get execution status", "description": "Get a specific execution status.", "operationId": "91aa493f5fe40cd2559ecb361807b219", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "executionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectExecutionDto" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Project Executions" ], "summary": "Delete execution", "description": "Cancel/delete a project execution.", "operationId": "6fff7a5d75c5c4584cfc5bd0a8bfdbd6", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "executionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution cancelled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Execution cancelled successfully" } }, "type": "object" } } } }, "500": { "description": "Failed to cancel execution", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/scene-composers": { "get": { "tags": [ "Scene Composers" ], "summary": "List scene composers", "operationId": "20470ee52ee869fdf5bab75842fec81f", "responses": { "200": { "description": "Scene composer collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneComposerCollectionDto" } } } } } } }, "/scene-composers/{id}": { "get": { "tags": [ "Scene Composers" ], "summary": "Get a scene composer", "operationId": "58f1d98cd3eeef4ff9ebeaea6f34c350", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Scene composer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneComposerDto" } } } }, "404": { "description": "Scene composer not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/scenes": { "get": { "tags": [ "Scenes" ], "summary": "Get all scenes", "description": "Get all scenes for a video.", "operationId": "c98f9a79d83e9de085aa576288e0fa4f", "parameters": [ { "name": "projectId", "in": "query", "description": "Optional Project ID to filter scenes", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of scenes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SceneDto" } } } } }, "404": { "description": "Project not found (if projectId is provided)", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Project not found" } }, "type": "object" } } } } } }, "post": { "tags": [ "Scenes" ], "summary": "Create a new scene", "description": "Store a newly created scene.", "operationId": "57e7cf1dbcb4cd16e745afbe279ea0c9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "projectId": { "type": [ "integer", "null" ], "example": 1 }, "name": { "type": "string", "example": "Sunset Scene" }, "order": { "type": [ "integer", "null" ], "minimum": 0, "example": 1 }, "description": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Scene created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The name field is required." }, "errors": { "type": "object" } }, "type": "object" } } } } } } }, "/scenes/{id}": { "get": { "tags": [ "Scenes" ], "summary": "Get a specific scene", "description": "Get a specific scene.", "operationId": "096cc12ad31a429f77e03f4b3ea599c4", "parameters": [ { "name": "id", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Scene details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneDto" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Scene not found" } }, "type": "object" } } } } } }, "put": { "tags": [ "Scenes" ], "summary": "Update a scene", "description": "Update the specified scene.", "operationId": "d1136f8b53e6aea18583a9d50845f020", "parameters": [ { "name": "id", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Scene Name" }, "order": { "type": [ "integer", "null" ], "minimum": 0, "example": 2 }, "description": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Scene updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneDto" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Scene not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The name field is required." }, "errors": { "type": "object" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Scenes" ], "summary": "Delete a scene", "description": "Delete a scene.", "operationId": "f912d6b2158b6fced18ffdfea04b31f5", "parameters": [ { "name": "id", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Scene deleted successfully" }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Scene not found" } }, "type": "object" } } } } } } }, "/scenes/{sceneId}/executions": { "get": { "tags": [ "Scene Executions" ], "summary": "List scene executions", "description": "List executions for a scene.", "operationId": "993188d9c6a712a84c1e8a94fddccfd7", "parameters": [ { "name": "sceneId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Executions for the scene", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SceneExecutionDto" } } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } }, "post": { "tags": [ "Scene Executions" ], "summary": "Queue a new execution", "description": "Queue a scene execution for a scene.", "operationId": "9b143ee85a97bab0111b09421551a28b", "parameters": [ { "name": "sceneId", "in": "path", "description": "Scene identifier", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "sceneComposerSlug", "selections" ], "properties": { "id": { "type": [ "integer", "null" ] }, "sceneComposerSlug": { "type": "string" }, "selections": { "type": "array", "items": { "properties": { "optionSlug": { "type": "string" }, "value": { "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" } }, "type": "object" } }, "type": "object" } }, "file": { "description": "Optional upload used by some scene composers", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Execution queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneExecutionDto" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "Scene or scene composer not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/scenes/{sceneId}/executions/{executionId}": { "get": { "tags": [ "Scene Executions" ], "summary": "Get execution status", "description": "Get a specific execution status.", "operationId": "0f48291f59995ddd762237b94c77d8f7", "parameters": [ { "name": "sceneId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "executionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneExecutionDto" } } } }, "404": { "description": "Execution not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/executions": { "get": { "tags": [ "Scene Executions" ], "summary": "List executions", "description": "List all executions with an optional status filter.", "operationId": "754bc5396f1ab0b66edad1cc26ad4c55", "parameters": [ { "name": "statuses", "in": "query", "description": "Comma-separated list of statuses to filter by", "required": false, "schema": { "type": "string", "example": "queued,processing,completed" } } ], "responses": { "200": { "description": "Executions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SceneExecutionDto" } } } } } } } }, "/executions/{executionId}": { "delete": { "tags": [ "Scene Executions" ], "summary": "Delete execution", "description": "Cancel/delete a scene execution.", "operationId": "ba988bad9de183b2dba3cbe3fdefc8a7", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution cancelled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Execution cancelled successfully" } }, "type": "object" } } } }, "500": { "description": "Failed to cancel execution", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/executions/estimate-cost": { "post": { "tags": [ "Scene Executions" ], "summary": "Estimate execution cost", "description": "Estimate the credit cost for a scene execution without queuing it.", "operationId": "4f49842ea74d611c2647eefbec49f473", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sceneComposerSlug", "selections" ], "properties": { "sceneComposerSlug": { "type": "string" }, "selections": { "type": "array", "items": { "properties": { "optionSlug": { "type": "string" }, "value": { "properties": { "value": {}, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Estimated credit cost", "content": { "application/json": { "schema": { "properties": { "credits": { "type": "integer" } }, "type": "object" } } } }, "404": { "description": "Scene composer not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "91193654887d260858477c0e28986aac", "responses": { "200": { "description": "Webhook endpoints for the current API key", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointDto" } } }, "type": "object" } } } }, "403": { "description": "Only available for API key tokens", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "operationId": "5c31ba93f1b10f759a449de48e3c8ba0", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "endpoint": { "$ref": "#/components/schemas/WebhookEndpointDto" }, "secret": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Only available for API key tokens", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "409": { "description": "An active webhook endpoint for this URL already exists for this API key", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "webhook.duplicate_endpoint" }, "message": { "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Disable webhook endpoint", "operationId": "15ae3ed7a8c0499b618f7e81d5226d84", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Webhook endpoint disabled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "403": { "description": "Only available for API key tokens", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/permissions": { "get": { "tags": [ "Admin" ], "summary": "List all permissions", "operationId": "46517a0d4cd0b35e565b726497571bb5", "responses": { "200": { "description": "Permissions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Create a permission", "operationId": "2439d4f4a1c42686bf0a3153a830608b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "slug" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionDto" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/admin/v1/permissions/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a permission", "operationId": "e233c34acd816e9804e049e753900cd0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionDto" } } } } } }, "put": { "tags": [ "Admin" ], "summary": "Update a permission", "operationId": "c62bf19531528d9810b6c4543e3ba4c6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionDto" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a permission", "operationId": "36a8d8f9a5a502fc1d72b33f914f5696", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/admin/v1/roles": { "get": { "tags": [ "Admin" ], "summary": "List all roles", "operationId": "8ef9ea663f172b36de922a8d910f5269", "responses": { "200": { "description": "Roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDto" } } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Create a role", "operationId": "7a442557c6e8a6e764976d70531bf8e3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "slug" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permission_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDto" } } } } } } }, "/admin/v1/roles/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a role", "operationId": "23a42329a7723834e09dbaf52cfc5f3d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDto" } } } } } }, "put": { "tags": [ "Admin" ], "summary": "Update a role", "operationId": "9bf818b3a5e4fad687536e03a6263865", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDto" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a role", "operationId": "bfd520c07fd137de2798fee68d993a55", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/admin/v1/roles/{id}/permissions": { "post": { "tags": [ "Admin" ], "summary": "Assign permissions to a role", "operationId": "334d5af85f388ce8e43c34e8bea3c17c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "permission_ids" ], "properties": { "permission_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDto" } } } } } } }, "/admin/v1/roles/{id}/permissions/{permissionId}": { "delete": { "tags": [ "Admin" ], "summary": "Remove a permission from a role", "operationId": "bf4f82a1ab500c37ca85b5e612ffb5b0", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "permissionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDto" } } } } } } }, "/admin/v1/users/{userId}/permissions": { "get": { "tags": [ "Admin" ], "summary": "List direct permissions for a user", "operationId": "670f3d3127c103f3adadad69372ee116", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Permissions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Grant a permission to a user", "operationId": "00152dc0e48c9242da2c43bd17cb9075", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "permission_id" ], "properties": { "permission_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Granted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/users/{userId}/permissions/{permissionId}": { "delete": { "tags": [ "Admin" ], "summary": "Revoke a permission from a user", "operationId": "94ecf567bd4cc62cc52e820962919424", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "permissionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/users/{userId}/roles": { "get": { "tags": [ "Admin" ], "summary": "List roles for a user", "operationId": "d01773d1acc7634a567df8c9fb290083", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleDto" } } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Assign a role to a user", "operationId": "36e023d51f865bbd2007a4adcdaf189a", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role_id" ], "properties": { "role_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Assigned", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/users/{userId}/roles/{roleId}": { "delete": { "tags": [ "Admin" ], "summary": "Remove a role from a user", "operationId": "68383d7210dcd7cca74051465545bce2", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/users": { "get": { "tags": [ "Admin" ], "summary": "List users (paginated)", "operationId": "3cdb63779f21279b21577a0852d199c6", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "role", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "id" } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated users", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserDto" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Create a user", "operationId": "dfdb090d7faaf22a3e029c2fa550270d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } } } } }, "/admin/v1/users/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a user", "operationId": "79bdb126f82b9952d8f3af62bdc81f20", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } } } }, "put": { "tags": [ "Admin" ], "summary": "Update a user (full)", "operationId": "4667c5d102c7c6ace28507b9860c8280", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a user", "operationId": "ec392189fcb37395845903456daf3623", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } }, "patch": { "tags": [ "Admin" ], "summary": "Partially update a user", "operationId": "5a5d23bf91b0c947dcfb586b42c18b8d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } } } } }, "/admin/v1/users/{id}/reset-password": { "post": { "tags": [ "Admin" ], "summary": "Reset a user password", "operationId": "f45a0d413611d76624212ed80862c03b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reset", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/users/{id}/verify-email": { "post": { "tags": [ "Admin" ], "summary": "Manually verify a user email", "operationId": "e370d0a2cfc69c48fba11713078dc4fa", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" } }, "type": "object" } } } } } } }, "/admin/v1/users/{id}/credit-balance": { "patch": { "tags": [ "Admin" ], "summary": "Update user credit balance", "operationId": "37a8ffd435d32a3566203f5313188b16", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "credit_balance" ], "properties": { "credit_balance": { "type": "integer", "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" } }, "type": "object" } } } } } } }, "/admin/v1/users/{id}/ban": { "post": { "tags": [ "Admin" ], "summary": "Manually ban a user", "operationId": "8c77e5a4dc1880a7507814572a6c469c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Banned", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" } }, "type": "object" } } } } } } }, "/admin/v1/users/{id}/reinstate": { "post": { "tags": [ "Admin" ], "summary": "Reinstate a banned user", "operationId": "497307dd878c12a7ea9ab09e0e3d69d8", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reinstated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" } }, "type": "object" } } } } } } }, "/admin/v1/users/{id}/token": { "post": { "tags": [ "Admin" ], "summary": "Generate impersonation token for a user", "operationId": "65e248bffb69c46599009604e7e6e8d6", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Impersonation token", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" }, "impersonated_by": { "type": "object" } }, "type": "object" } } } } } } }, "/admin/v1/featured-content": { "post": { "tags": [ "Admin" ], "summary": "Mark content as featured", "operationId": "5681664ef4f4be4cd62b4aa814d06ea4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "project", "scene_execution" ] }, "id": { "type": "integer" }, "tagIds": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Featured", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/v1/featured-content/{type}/{id}": { "delete": { "tags": [ "Admin" ], "summary": "Unmark featured content", "operationId": "48884651d124db738735bfd9feb02b3a", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unfeatured", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } } } } } }, "/admin/v1/banners": { "get": { "tags": [ "Admin" ], "summary": "List all banners", "operationId": "0652f8d655cb64f7bf0298c762c0bb02", "responses": { "200": { "description": "Banners", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BannerDto" } } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Create a banner", "operationId": "1c0019fb4c81a5663b0c7420ed1bc3d3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "media_url" ], "properties": { "title": { "type": "string" }, "media_url": { "type": "string" }, "target_url": { "type": [ "string", "null" ] }, "sort": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BannerDto" } } } } } } }, "/admin/v1/banners/{id}": { "put": { "tags": [ "Admin" ], "summary": "Update a banner", "operationId": "bca98a0731c578520b2d6e19b3dd2b59", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "media_url": { "type": "string" }, "target_url": { "type": [ "string", "null" ] }, "sort": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BannerDto" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a banner", "operationId": "92e16085d96dbc2facf6fac60e0c721d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/admin/v1/scene-composers/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get scene composer (including hidden options)", "operationId": "da066ac10c28b025da893371744087ec", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Scene composer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SceneComposerDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/admin/v1/scene-composers/{id}/configuration": { "put": { "tags": [ "Admin" ], "summary": "Update scene composer configuration option", "operationId": "9da847b351b2e5ce5a47c2f682a61d5a", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/v1/scene-composer-functions": { "get": { "tags": [ "Admin" ], "summary": "List scene composer functions", "operationId": "25e718b8b8c2470d66c0a8bcbac85a54", "responses": { "200": { "description": "Functions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SceneComposerFunctionDto" } } } } } } } }, "/admin/v1/scene-composer-functions/{id}": { "put": { "tags": [ "Admin" ], "summary": "Update a scene composer function", "operationId": "cfb4b0c5f438d62ea11026b8ea89ed6b", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "name", "icon" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string" }, "sort": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a scene composer function", "operationId": "19f753d7471812ce405d7ddfc0b1986c", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/admin/v1/scene-composer-functions/{id}/move-scene-composer/{scene_composer_id}": { "put": { "tags": [ "Admin" ], "summary": "Move a scene composer to a different function", "operationId": "ce6e541f37b2b7eed0b84383da93fe0d", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "scene_composer_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/stream/{path}": { "get": { "tags": [ "Media" ], "summary": "Stream a media file with range request support", "operationId": "de954c77c0b65a2f7bfb08e29b470bb9", "parameters": [ { "name": "path", "in": "path", "description": "Relative path within the outputs storage disk", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "Byte range for partial content (e.g. bytes=0-1023)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full file content" }, "206": { "description": "Partial content (range request)" }, "404": { "description": "File not found" }, "416": { "description": "Range not satisfiable" } }, "security": [] } }, "/project-orchestrator/projects/{projectId}/converse": { "post": { "tags": [ "Project Orchestrator" ], "summary": "Send a message to the project orchestrator agent", "operationId": "ef018e3e8f1dd1cc21610d1d677718ff", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 5000 }, "threadId": { "type": [ "string", "null" ] }, "selections": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Agent response", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/project-orchestrator/projects/{projectId}/stream": { "post": { "tags": [ "Project Orchestrator" ], "summary": "Stream agent response via Server-Sent Events", "operationId": "9a116aca130109ec68ed071fe8ccd3a8", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 5000 }, "threadId": { "type": [ "string", "null" ] }, "selections": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "SSE stream (text/event-stream)", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads": { "get": { "tags": [ "Project Orchestrator" ], "summary": "List conversation threads for a project", "operationId": "0c44ea6f2ae66a9f146892e71bbd539e", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Thread list", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/chat-history": { "get": { "tags": [ "Project Orchestrator" ], "summary": "Get chat history for a project thread", "operationId": "6eaf58cb5f4e26479c8ccb5c9d4b799c", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chat history", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads/{threadId}/research-bundles": { "get": { "tags": [ "Project Orchestrator" ], "summary": "List research bundles for a thread", "operationId": "9dc5433c3a2db3c6e877ea303f7f34dc", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Research bundles", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads/{threadId}/suggested-assets": { "get": { "tags": [ "Project Orchestrator" ], "summary": "List suggested assets for a research bundle", "operationId": "d10a76ca7c02df5b653864578c2110e5", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bundleId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Suggested assets", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads/{threadId}/suggested-assets/{suggestedAssetId}/preview": { "get": { "tags": [ "Project Orchestrator" ], "summary": "Preview a suggested asset file", "operationId": "16c5a0130ddb04552a5bfd882bf358e9", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "suggestedAssetId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset stream" }, "502": { "description": "Preview failed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads/{threadId}/decision-requests": { "get": { "tags": [ "Project Orchestrator" ], "summary": "List pending decision requests for a thread", "operationId": "ac3997d08c64ed01167c8e5a4d18070e", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Decision requests", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/projects/{projectId}/threads/{threadId}/decision-requests/{decisionRequestId}": { "get": { "tags": [ "Project Orchestrator" ], "summary": "Get a single decision request", "operationId": "9fd5929234e10e7f010c99ddf8d2a91c", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "decisionRequestId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Decision request", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/project-orchestrator/executions/{executionId}/pause": { "post": { "tags": [ "Project Orchestrator" ], "summary": "Pause a project execution", "operationId": "816b686d08c64b3861f57af9965898dd", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution paused", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Cannot pause", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } } } }, "/scene-composers/licenses": { "get": { "tags": [ "Scene Composer Licenses" ], "summary": "List all scene composer licenses", "operationId": "03d4ec4f56c8a7e4206a64b374056e61", "responses": { "200": { "description": "Licenses", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "security": [] } }, "/scene-composers/{id}/licenses": { "get": { "tags": [ "Scene Composer Licenses" ], "summary": "Get licenses for a scene composer", "operationId": "e55bcc5eba7dbb15397a2024399cc374", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Licenses", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } }, "security": [] } }, "/licenses/{licenseType}": { "get": { "tags": [ "Scene Composer Licenses" ], "summary": "Get full license text by type", "operationId": "38453284cf46146e28c095ba40a48ce9", "parameters": [ { "name": "licenseType", "in": "path", "required": true, "schema": { "type": "string", "example": "MIT" } } ], "responses": { "200": { "description": "License text", "content": { "application/json": { "schema": { "properties": { "license_type": { "type": "string" }, "text": { "type": "string" } }, "type": "object" } } } }, "404": { "description": "License type not found", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/auth/google/redirect": { "get": { "tags": [ "Social Auth" ], "summary": "Get Google OAuth redirect URL", "operationId": "9b94f0ce936f6071abe002462df39052", "parameters": [ { "name": "return_url", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redirect URL", "content": { "application/json": { "schema": { "properties": { "redirectUrl": { "type": "string", "format": "uri" } }, "type": "object" } } } } }, "security": [] } }, "/auth/google/callback": { "get": { "tags": [ "Social Auth" ], "summary": "Google OAuth callback (redirects to frontend)", "operationId": "f1a755910575bc78a466c492bc728f2c", "responses": { "302": { "description": "Redirect to frontend with token or error" } }, "security": [] } }, "/auth/apple/redirect": { "get": { "tags": [ "Social Auth" ], "summary": "Get Apple OAuth redirect URL", "operationId": "957bd9e60f5013207702543fd4cd2d77", "parameters": [ { "name": "return_url", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redirect URL", "content": { "application/json": { "schema": { "properties": { "redirectUrl": { "type": "string", "format": "uri" } }, "type": "object" } } } } }, "security": [] } }, "/auth/apple/callback": { "get": { "tags": [ "Social Auth" ], "summary": "Apple OAuth callback (redirects to frontend)", "operationId": "1f92acf503114b0c986a204aeb7c35fd", "responses": { "302": { "description": "Redirect to frontend with token or error" } }, "security": [] } }, "/auth/social-accounts": { "get": { "tags": [ "Social Auth" ], "summary": "List linked social accounts for the authenticated user", "operationId": "c08cda7d0668a057559dad6c8143dfc2", "responses": { "200": { "description": "Social accounts", "content": { "application/json": { "schema": { "properties": { "social_accounts": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } } } }, "/auth/social-accounts/{provider}/link": { "post": { "tags": [ "Social Auth" ], "summary": "Link a social account to the authenticated user", "operationId": "1df86089e8f29c011be946f9b1fa19a1", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } } ], "responses": { "200": { "description": "Linked", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string" }, "provider": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Link failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } }, "/auth/social-accounts/{provider}/unlink": { "delete": { "tags": [ "Social Auth" ], "summary": "Unlink a social account from the authenticated user", "operationId": "4a92911183f8784a1d0920c1579077d1", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google", "apple" ] } } ], "responses": { "200": { "description": "Unlinked", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Unlink failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } } } } } }, "components": { "schemas": { "UserDto": { "properties": { "id": { "description": "Central OpenAPI schemas for DTO-based responses and requests.", "type": "integer", "format": "int64" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "emailVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creditBalance": { "type": "integer", "format": "int32", "example": 1000 }, "marketingOptIn": { "type": "boolean" } }, "type": "object" }, "AuthResponseDto": { "properties": { "user": { "$ref": "#/components/schemas/UserDto" }, "token": { "type": "string", "example": "1|abcdef..." } }, "type": "object" }, "ConfigValueDto": { "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" }, "credits": { "type": [ "integer", "null" ] }, "isDefault": { "type": [ "boolean", "null" ] }, "isAgentDefault": { "type": [ "boolean", "null" ] }, "isDynamic": { "type": [ "boolean", "null" ] }, "agentGuidance": { "description": "Optional per-value hint for MCP/agent tool schema (SELECT options)", "type": [ "string", "null" ] }, "isAgentHidden": { "description": "When true, excluded from MCP/agent tool enum and agent-only schema defaults", "type": [ "boolean", "null" ] } }, "type": "object" }, "ConfigOptionUiDto": { "description": "Layout and client flags for a config option (nested under option.ui)", "properties": { "visibilityType": { "type": "string", "example": "compact" }, "iconReference": { "type": "string", "example": "prompt" }, "verticalPosition": { "type": "string", "example": "bottom" }, "horizontalPosition": { "type": "string", "example": "left" }, "order": { "type": "integer", "format": "int32", "example": 0 }, "hideInAgent": { "description": "When true, omit from conversational Video Director form", "type": "boolean", "example": false } }, "type": "object" }, "ConfigOptionDto": { "properties": { "slug": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "agentGuidance": { "description": "Optional override for MCP/agent tool schema property descriptions; UI uses description", "type": [ "string", "null" ] }, "type": { "type": "string" }, "defaultValues": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigValueDto" } }, "constraints": { "type": "object" }, "ui": { "$ref": "#/components/schemas/ConfigOptionUiDto" }, "component": { "type": [ "string", "null" ] }, "dependsOn": { "type": [ "array", "null" ], "items": { "type": "string" } }, "required": { "type": "boolean" }, "visibility": { "type": "string" } }, "type": "object" }, "SceneComposerConfigDto": { "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigOptionDto" } } }, "type": "object" }, "SceneComposerFunctionDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "sort": { "type": "integer", "format": "int32" } }, "type": "object" }, "SceneComposerSelectionDto": { "properties": { "optionSlug": { "type": "string" }, "value": { "$ref": "#/components/schemas/ConfigValueDto" } }, "type": "object" }, "MetadataValueDto": { "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "metadata": { "type": "object" } }, "type": "object" }, "ExecutionMetadataDto": { "properties": { "label": { "type": "string" }, "key": { "type": "string" }, "value": { "$ref": "#/components/schemas/MetadataValueDto" } }, "type": "object" }, "SceneExecutionDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "sceneId": { "type": "integer", "format": "int64" }, "prompt": { "type": [ "string", "null" ] }, "negativePrompt": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "queued" }, "storagePath": { "type": [ "string", "null" ] }, "previewPath": { "type": [ "string", "null" ] }, "thumbnailPath": { "type": [ "string", "null" ] }, "lastFramePath": { "type": [ "string", "null" ] }, "lastFrameThumbnailPath": { "type": [ "string", "null" ] }, "statusMsg": { "type": [ "string", "null" ] }, "sceneComposerSlug": { "type": [ "string", "null" ] }, "config": { "$ref": "#/components/schemas/SceneComposerConfigDto" }, "selections": { "type": "array", "items": { "$ref": "#/components/schemas/SceneComposerSelectionDto" } }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionMetadataDto" } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "parentId": { "type": [ "integer", "null" ] }, "jobId": { "type": [ "string", "null" ] }, "creditsCharged": { "type": [ "integer", "null" ] }, "isPublic": { "type": [ "boolean", "null" ] } }, "type": "object" }, "SceneDto": { "properties": { "id": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "order": { "type": [ "integer", "null" ], "format": "int32" }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/SceneExecutionDto" } }, "selectedExecution": { "oneOf": [ { "$ref": "#/components/schemas/SceneExecutionDto" }, { "type": "null" } ] }, "projectIds": { "type": "array", "items": { "type": "integer" } }, "userId": { "type": [ "integer", "null" ] } }, "type": "object" }, "SceneComposerDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "config": { "$ref": "#/components/schemas/SceneComposerConfigDto" }, "function": { "$ref": "#/components/schemas/SceneComposerFunctionDto" }, "providerId": { "type": [ "integer", "null" ] }, "baseCreditsCost": { "type": "integer", "format": "int32" }, "selectionGuidance": { "type": [ "string", "null" ] }, "sort": { "type": "integer", "format": "int32" } }, "type": "object" }, "SceneComposerCollectionDto": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SceneComposerDto" } } }, "type": "object" }, "PlatformDto": { "properties": { "id": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "metadata": { "type": "object" } }, "type": "object" }, "ChannelDto": { "properties": { "id": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformDto" } }, "userId": { "type": [ "integer", "null" ] } }, "type": "object" }, "ProjectDto": { "properties": { "id": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "storage_path": { "type": [ "string", "null" ] }, "isPublic": { "type": [ "boolean", "null" ] }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/SceneDto" } }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelDto" } }, "userId": { "type": [ "integer", "null" ] } }, "type": "object" }, "ProjectVideoRenderStatusDto": { "properties": { "state": { "type": "string", "enum": [ "idle", "queued", "rendering", "completed", "failed" ] }, "message": { "type": [ "string", "null" ] }, "updatedAt": { "description": "Unix seconds", "type": [ "integer", "null" ] }, "project": { "oneOf": [ { "$ref": "#/components/schemas/ProjectDto" }, { "type": "null" } ] } }, "type": "object" }, "CreditPackageDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "numCredits": { "type": "integer" }, "priceCents": { "type": "integer" }, "metadata": { "type": "object" } }, "type": "object" }, "PaymentIntentDto": { "properties": { "id": { "type": "string" }, "clientSecret": { "type": "string" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "metadata": { "type": "object" } }, "type": "object" }, "PromoCodeDiscount": { "properties": { "discountCents": { "type": "integer" }, "message": { "type": [ "string", "null" ] } }, "type": "object" }, "StripeConfig": { "properties": { "publishableKey": { "type": "string" }, "currency": { "type": "string", "example": "usd" }, "socialSignupCredits": { "type": "integer" }, "marketingOptInCredits": { "description": "ADO #7123: marketing email opt-in bonus (config MARKETING_OPTIN_CREDIT_AMOUNT). Reported unconditionally — region gating only affects the grant.", "type": "integer" }, "maxSignupCredits": { "description": "ADO #7123: signup + opt-in combined maximum, server-computed. Deliberate design (Skyball thread 26984): collapses to socialSignupCredits globally whenever MARKETING_OPTIN_GDPR_ENABLED (auth.marketing_optin_gdpr_enabled) is off, even though the grant (SocialAuthCreditsService::grantCreditsForMarketingOptIn) withholds the opt-in only for GDPR-region visitors — so with the flag off a non-GDPR signup can still be paid signup+opt-in while every hero quotes 'up to {socialSignupCredits}'. This UNDER-promises on purpose: the landing payload is cacheable and NOT region-specific, so it can never promise a bonus some visitors can never receive; the consent checkbox copy (MarketingConsentService::creditAmount) still quotes the true opt-in amount.", "type": "integer" }, "productionMinCredits": { "type": "integer" }, "subscriptionUi": { "description": "Epic #3500 wave 4: the /credits plans-section gate. Both flags are server-computed by SubscriptionManagementService (plansEnabled = subscriptionsAvailable(); portalConfigured = subscriptionsAvailable() AND the billing-portal return URL is set) so the UI never renders an action that 404s/422s.", "properties": { "plansEnabled": { "type": "boolean" }, "portalConfigured": { "type": "boolean" } }, "type": "object" }, "terms": { "description": "ADO #7468 (California ARL): the Terms identity the auto-renewal consent acknowledges — version is stamped onto every consent row, url anchors the checkout disclosure's Terms link (config-owned).", "properties": { "version": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object" }, "ApiKeyDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "userId": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "mcpGrant": { "description": "Null for general keys. servers null means all nine MCP servers.", "properties": { "scopes": { "type": "array", "items": { "type": "string" } }, "servers": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "platform", "video", "image-edit", "music-generate", "text-to-image", "text-to-speech", "upscale-video", "upscale-image", "utilities" ] } } }, "type": [ "object", "null" ] } }, "type": "object" }, "WebhookEndpointDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "apiKeyId": { "type": "integer", "format": "int64" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "type": "object" }, "ProjectAutomaterDto": { "properties": { "id": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" } }, "type": "object" }, "PlatformUploadResultDto": { "properties": { "contentId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "platformId": { "type": "string" } }, "type": "object" }, "PermissionDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "type": "object" }, "RoleDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "type": "object" }, "BannerDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "media_url": { "type": "string" }, "target_url": { "type": [ "string", "null" ] }, "sort": { "type": "integer", "format": "int32" }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } }, "type": "object" }, "ValidationError": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "object" } }, "type": "object" }, "PaginationMeta": { "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" }, "TaxCalculationDto": { "properties": { "amountCents": { "type": "integer" }, "taxCents": { "type": "integer" }, "totalCents": { "type": "integer" }, "currency": { "type": "string" } }, "type": "object" }, "ProjectComposerDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object" }, "function": { "$ref": "#/components/schemas/SceneComposerFunctionDto" }, "previewCreditsCost": { "type": "integer" }, "minCreditsRequired": { "type": [ "integer", "null" ] }, "sort": { "type": "integer", "format": "int32" } }, "type": "object" }, "ProjectExecutionDto": { "properties": { "id": { "type": "integer", "format": "int64" }, "projectId": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "statusMsg": { "type": [ "string", "null" ] }, "storagePath": { "type": [ "string", "null" ] }, "previewPath": { "type": [ "string", "null" ] }, "projectComposerSlug": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } }, "securitySchemes": { "jwt": { "type": "http", "description": "Use Authorization: Bearer {token} with a JWT token. New logins return JWT tokens by default.", "bearerFormat": "JWT", "scheme": "bearer" }, "sanctum": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum", "description": "Use the Authorization header with a Bearer Sanctum token." } } }, "tags": [ { "name": "Scene Composers", "description": "Available scene composers and their configuration" }, { "name": "Auth", "description": "Authentication endpoints" }, { "name": "Billing", "description": "Credit packages, payments, and Stripe webhooks" }, { "name": "Channels", "description": "Manage channels and linked platforms" }, { "name": "Scene Executions", "description": "Queue and manage scene executions" }, { "name": "Platforms", "description": "Platform metadata" }, { "name": "Project Automaters", "description": "Automated workflows for projects" }, { "name": "Project Composers", "description": "Available project composers and their configuration" }, { "name": "Projects", "description": "API Endpoints for managing projects" }, { "name": "Project Executions", "description": "Queue and manage project executions" }, { "name": "Scenes", "description": "API Endpoints for managing video scenes" }, { "name": "Webhooks", "description": "Manage webhook endpoints for API key tokens" }, { "name": "Admin", "description": "Admin API (JWT auth, permission-gated)" }, { "name": "Media", "description": "Media file streaming" }, { "name": "Project Orchestrator", "description": "Conversational project director agent (converse, stream, threads, research)" }, { "name": "Scene Composer Licenses", "description": "Public license information for scene composers" }, { "name": "Social Auth", "description": "Google and Apple OAuth and social account management" }, { "name": "API Keys", "description": "API Keys" } ], "security": [ { "sanctum": [] } ] }