{ "components": { "parameters": { "Cursor": { "description": "The previous page's `nextCursor`. Opaque.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, "IdempotencyKey": { "description": "1–128 characters, unique to this request. A retry with the same key and the same body returns the STORED response with `Idempotent-Replayed: true`; the same key with a different body is 409 `idempotency_conflict`; a duplicate still in flight is 409 `idempotency_in_progress`. Claims expire after 24 hours.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, "Limit": { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, "XRequestId": { "description": "Your own correlation id. Echoed on the response and present in every error body. Accepted when it matches `^[A-Za-z0-9._-]{1,64}$`.", "in": "header", "name": "X-Request-Id", "required": false, "schema": { "pattern": "^[A-Za-z0-9._-]{1,64}$", "type": "string" } } }, "responses": { "conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`conflict` — That request conflicts with the current state." }, "forbidden_scope": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "insufficient_seconds": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "internal_error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "not_found": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "payload_too_large": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "rate_limited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "service_unavailable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`service_unavailable` — That service is temporarily unavailable." }, "unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "validation_failed": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." } }, "schemas": { "Error": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "description": "The machine-readable refusal. Branch on this.", "enum": [ "abuse_check_unavailable", "account_blocked", "account_deleted", "account_pending_deletion", "ai_rate_limited", "already_settled", "anon_lifetime_cap", "assistant_conversation_full", "assistant_daily_limit", "assistant_unavailable", "avatar_unavailable", "avatar_unknown", "background_unknown", "body_invalid", "brand_kit_required", "brand_logo_not_retained", "brand_logo_source_mismatch", "budget_exhausted", "campaign_copy_overflow", "campaign_logo_aspect_unsupported", "campaign_speed_breaks_music_ending", "campaign_speed_breaks_narration_fit", "campaign_speed_not_offered", "campaign_unsupported_claim", "campaign_visuals_insufficient", "caption_style_unknown", "capture_incompatible", "capture_unknown", "conflict", "conversation_closed", "conversation_not_found", "credentials_required", "description_invalid", "edit_not_understood", "email_unverified", "expected_revision_required", "expired", "export_in_flight", "feature_disabled", "forbidden_scope", "gallery_example", "generation_busy", "generation_idempotency_conflict", "generation_not_found", "generation_not_retryable", "gone", "handoff_failed", "handoff_limit", "hint_improve_failed", "hint_required", "hint_too_long", "idempotency_conflict", "idempotency_in_progress", "idempotency_key_required", "idempotency_key_unscoped", "insufficient_seconds", "internal_error", "invalid_brand_kit", "invalid_campaign_narration", "invalid_cover_text", "invalid_cursor", "invalid_revision", "language_unknown", "length_below_minimum", "login_origins_invalid", "login_url_invalid", "login_url_required", "missing_required_footage", "name_invalid", "no_beats", "no_revision", "not_finished", "not_found", "not_ready", "options_invalid", "orientation_unknown", "origin_daily_cap", "paid_account_required", "payload_too_large", "preview_failed", "project_not_found", "queue_unavailable", "rate_limited", "reservation_failed", "revision_configuration_mismatch", "revision_conflict", "service_unavailable", "settings_invalid", "site_not_allowed", "source_deleted", "source_expired", "source_export_in_flight", "source_idempotency_conflict", "source_inspection_busy", "source_inspection_stopping", "source_kind_mismatch", "source_not_found", "source_not_ready", "source_owner_not_found", "source_owner_unavailable", "source_refresh_url_mismatch", "source_render_not_found", "source_unreadable", "source_version_expired", "source_version_mismatch", "source_version_not_found", "storage_unavailable", "storyboard_empty", "storyboard_expired", "storyboard_in_flight", "template_limit", "template_not_found", "template_unknown", "too_many_endpoints", "too_many_in_flight", "tts_unavailable", "unauthorized", "unknown_beat", "unknown_template", "unsupported_audio_mode", "unsupported_duration", "unsupported_export", "unsupported_format", "unsupported_media_type", "url_bare_host", "url_blocked", "url_credentials", "url_dns", "url_invalid", "url_malformed", "url_missing", "url_no_host", "url_private", "url_scheme", "validation_failed", "vault_unavailable", "verification_required", "voice_language", "voice_unknown", "wallet_unavailable", "webhook_endpoint_disabled", "webhook_host_denied", "webhook_url_blocked", "webhook_url_invalid", "website_demo_invalid" ], "type": "string" }, "details": { "additionalProperties": true, "description": "The structured half: the fields that failed, the seconds needed, the statuses offered. A refusal you can act on may also carry `missing`: one entry per thing to put right, each `{ field, section, message }`, where `section` is the part of the editor that owns the field (story, style, sound or export) and `message` is the sentence a person is shown for it. It is the same list the dashboard draws beside its Export button.", "type": "object" }, "message": { "description": "A sentence written for a person. Never contains what you sent.", "type": "string" }, "requestId": { "description": "Quote this when reporting a failure.", "type": [ "string", "null" ] } }, "required": [ "code", "message", "requestId" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "JobResource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" }, "WebhookEvent": { "additionalProperties": false, "description": "The body of a webhook delivery. Verify `Gogoscreen-Signature` over the raw bytes before parsing this.", "properties": { "apiVersion": { "description": "The contract `data` is written to.", "enum": [ "v1" ], "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "data": { "description": "The resource, as `GET` would answer it: the job envelope for every `.succeeded`/`.failed`/`.cancelled` event, plus `requestId` when the work was started through this API. A `webhook.test` event carries `{ endpointId, message, sentAt }` instead.", "oneOf": [ { "$ref": "#/components/schemas/JobResource" }, { "additionalProperties": true, "type": "object" } ] }, "id": { "description": "The event's id, also sent as `Gogoscreen-Event-Id`. Delivery is at-least-once: dedupe on this.", "type": "string" }, "type": { "description": "Which event this is. Only the types the endpoint subscribed to are ever sent.", "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" } }, "required": [ "id", "type", "createdAt", "apiVersion", "data" ], "type": "object" } }, "securitySchemes": { "ApiKey": { "bearerFormat": "gsk_…", "description": "An API key, created in the dashboard's developer console. Also accepted as `X-API-Key`.", "scheme": "bearer", "type": "http" }, "DashboardSession": { "bearerFormat": "JWT", "description": "A dashboard session token, the credential the dashboard itself holds.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "support@gogoscreen.com", "name": "GogoScreen support", "url": "https://gogoscreen.com/support" }, "description": "Every operation is defined once, and this document and the MCP tool list are both built from that one definition, so they cannot disagree.\n\n**Authentication.** `Authorization: Bearer gsk_…` (an API key) or `X-API-Key: gsk_…`. A dashboard session token in the same Bearer header is accepted so the dashboard's developer console can call this API with the session it already has.\n\n**Pagination.** Cursor only. Pass `limit` (1–100, default 20) and the previous page's `nextCursor`; a null `nextCursor` is the end of the walk. Cursors are opaque — do not build one.\n\n**Errors.** Every non-2xx answers `{ error: { code, message, details?, requestId } }`. Branch on `code`; quote `requestId` when reporting a failure.\n\n**Rate limits.** Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). Each operation belongs to a class — read 600/min, write 120/min, expensive 20/min, charge 20/min — counted per credential, and a key may carry a lower per-minute or per-day limit of its own. Above those there is one ceiling per ACCOUNT, shared by every key and every class, so holding more keys does not raise what an account can do. A refusal is `429 rate_limited` with `Retry-After` and `details.scope` naming which ceiling it was: `minute`, `day` or `account`.\n\n**Long work.** Renders, storyboards, scans, generations and exports are jobs: they answer a resource with a `state` of queued/running/succeeded/failed/cancelled and a `pollAfterMs`. Poll until the state is terminal, or subscribe to a webhook.\n\n**Idempotency.** Every mutating operation takes an `Idempotency-Key` header; a replay with the same body returns the stored response.\n\n**Webhooks.** Register an endpoint with `POST /webhooks` and you are told when work finishes instead of polling for it. The secret is returned once, at registration.\n\nEvery delivery is a `POST` of a `WebhookEvent` with these headers: `Gogoscreen-Event-Id`, `Gogoscreen-Event-Type`, `Gogoscreen-Delivery-Id`, `Gogoscreen-Delivery-Attempt` and `Gogoscreen-Signature`.\n\nThe signature is `t=,v1=`, where the hex is `HMAC-SHA256(secret, \".\" + rawBody)`. **Verify it against the RAW body you received**, not against a re-serialised object — key order and whitespace are not guaranteed to survive a parse. Reject a `t` more than 300 seconds from your own clock, and compare the hex in constant time.\n\nDelivery is **at-least-once**: six attempts on an exponential backoff, a redirect is refused rather than followed, and only a 2xx within 10 seconds counts as delivered. Dedupe on `Gogoscreen-Event-Id`, and treat a repeat as the same event. After 20 consecutive failed deliveries an endpoint is disabled and has to be turned back on.\n\nThe webhooks guide at https://gogoscreen.com/docs/webhooks has a short verifier example.", "license": { "name": "GogoScreen API Terms", "url": "https://gogoscreen.com/terms" }, "summary": "Make product walkthroughs and marketing videos from a URL.", "title": "GogoScreen API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/account": { "get": { "description": "Who this credential acts for, and the account's video-time balance. The fields an integration needs, not the whole account record.", "operationId": "account.me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "deletionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "emailVerified": { "description": "Read from the credential, which is the authority on verification.", "type": "boolean" }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "email", "name", "emailVerified", "role", "createdAt", "deletionStatus" ], "type": "object" }, "credential": { "additionalProperties": false, "properties": { "apiKeyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "enum": [ "user", "api_key" ], "type": "string" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "null means a user credential, which carries every scope." } }, "required": [ "kind", "apiKeyId", "scopes" ], "type": "object" }, "wallet": { "anyOf": [ { "additionalProperties": false, "properties": { "availableSeconds": { "description": "What a new render or export may be reserved against, right now.", "type": "number" }, "freeSeconds": { "type": "number" }, "paygSeconds": { "type": "number" }, "planActive": { "type": "boolean" }, "planExpiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "planId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "planSeconds": { "type": "number" }, "reservedSeconds": { "type": "number" } }, "required": [ "planSeconds", "planId", "planExpiresAt", "planActive", "paygSeconds", "freeSeconds", "reservedSeconds", "availableSeconds" ], "type": "object" }, { "type": "null" } ], "description": "null only when the balance could not be read; a status question never fails on the wallet." } }, "required": [ "account", "wallet", "credential" ], "type": "object" } } }, "description": "The account behind this credential", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "account:read" ] }, { "DashboardSession": [] } ], "summary": "The account behind this credential", "tags": [ "account" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "account_me", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "account:read" ] } }, "/assistant/conversations/current": { "get": { "description": "This account's most recently used open conversation with the support assistant, or null when there is none. The panel calls it on open so a customer who closed the tab mid-question comes back to their thread rather than to an empty box. It never creates one: a conversation exists because a question was asked.", "operationId": "assistant.conversations.current", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conversation": { "anyOf": [ { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "description": "The conversation's id. Pass it as `conversationId` to keep asking in the same thread.", "type": "string" }, "lastMessageAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "When the thread was last written to. Null on a conversation with no messages yet." }, "messageCount": { "description": "How many questions the customer has asked in this thread. The per-conversation cap counts this, not the replies.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "status": { "description": "`open` takes another question. `closed` and `handed_off` both refuse one with 409 `conversation_closed`; start a new conversation.", "enum": [ "open", "closed", "handed_off" ], "type": "string" } }, "required": [ "id", "status", "messageCount", "lastMessageAt", "createdAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "conversation" ], "type": "object" } } }, "description": "The conversation to resume", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "The conversation to resume", "tags": [ "assistant" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": null, "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "assistant:use" ] } }, "/assistant/conversations/{id}": { "get": { "description": "One conversation of this account with its last fifty messages, oldest first. A conversation belonging to another account is a 404, never a 403: this surface does not answer whether an id exists.", "operationId": "assistant.conversations.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conversation": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "description": "The conversation's id. Pass it as `conversationId` to keep asking in the same thread.", "type": "string" }, "lastMessageAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "When the thread was last written to. Null on a conversation with no messages yet." }, "messageCount": { "description": "How many questions the customer has asked in this thread. The per-conversation cap counts this, not the replies.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "status": { "description": "`open` takes another question. `closed` and `handed_off` both refuse one with 409 `conversation_closed`; start a new conversation.", "enum": [ "open", "closed", "handed_off" ], "type": "string" } }, "required": [ "id", "status", "messageCount", "lastMessageAt", "createdAt" ], "type": "object" }, "messages": { "items": { "additionalProperties": false, "properties": { "content": { "description": "Plain text. The assistant writes no HTML, no markdown headings and no links off this product.", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "handoffSuggested": { "description": "The assistant believes a person should take this. Offer the hand-off; it is never taken automatically.", "type": "boolean" }, "id": { "type": "string" }, "role": { "enum": [ "user", "assistant" ], "type": "string" }, "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The assistant's own label for what the question was about — one of product, billing, account, api, troubleshooting, escalation, off_topic. Null on a customer's turn." } }, "required": [ "id", "role", "content", "topic", "handoffSuggested", "createdAt" ], "type": "object" }, "type": "array" } }, "required": [ "conversation", "messages" ], "type": "object" } } }, "description": "One conversation and its messages", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `conversation_not_found` — No such conversation." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "One conversation and its messages", "tags": [ "assistant" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": null, "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "assistant:use" ] } }, "/assistant/conversations/{id}/close": { "post": { "description": "End a conversation. It keeps its messages and can still be read; it takes no further questions, and the next one starts a new thread. Closing a conversation that is already closed answers the same thing, so a double click is not an error.", "operationId": "assistant.conversations.close", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conversation": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "description": "The conversation's id. Pass it as `conversationId` to keep asking in the same thread.", "type": "string" }, "lastMessageAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "When the thread was last written to. Null on a conversation with no messages yet." }, "messageCount": { "description": "How many questions the customer has asked in this thread. The per-conversation cap counts this, not the replies.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "status": { "description": "`open` takes another question. `closed` and `handed_off` both refuse one with 409 `conversation_closed`; start a new conversation.", "enum": [ "open", "closed", "handed_off" ], "type": "string" } }, "required": [ "id", "status", "messageCount", "lastMessageAt", "createdAt" ], "type": "object" } }, "required": [ "conversation" ], "type": "object" } } }, "description": "Close a conversation", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `conversation_not_found` — No such conversation." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "Close a conversation", "tags": [ "assistant" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": null, "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "assistant:use" ] } }, "/assistant/handoffs": { "post": { "description": "Send a message to a human support agent, optionally with the assistant conversation attached. The assistant never does this by itself: it can say a person should take over, and this is the customer pressing the button. The request is WRITTEN DOWN before the email is attempted, so a mail outage delays it rather than losing it — `ticket.status` is `sent` when the support inbox already has it and `queued` when it is still being delivered, and in both cases the reference is final and the request needs no resending. The transcript, when attached, is the conversation as the SERVER stored it, not as the client claims it happened. A successful same-key retry reads the original ticket's current delivery state without submitting it again; failed means automatic retries have ended.", "operationId": "assistant.handoffs.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "category": { "description": "What the request is about. It routes the email and is the customer's choice, never the assistant's.", "enum": [ "billing", "bug", "account", "feature_request", "other" ], "type": "string" }, "conversationId": { "description": "Attach this conversation. A conversation of another account is a 404. Omit for a request that started outside the assistant.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "includeTranscript": { "default": false, "description": "Attach the conversation's last fifty turns to the ticket. Absent means NO: a conversation is only ever copied into a support ticket because the customer asked for it.", "type": "boolean" }, "message": { "description": "What the customer wants to say, in their own words. Stored and emailed as text.", "maxLength": 5000, "minLength": 0, "type": "string" }, "subject": { "maxLength": 200, "minLength": 3, "type": "string" } }, "required": [ "category", "subject", "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "contactEmail": { "description": "Where the reply will go — the address on the signed-in account, echoed back so the panel can say so.", "type": "string" }, "expectedReply": { "description": "How long an answer usually takes.", "type": "string" }, "ticket": { "additionalProperties": false, "properties": { "category": { "enum": [ "billing", "bug", "account", "feature_request", "other" ], "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "type": "string" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What to quote when you write to support about this: `GS-` and eight characters." }, "status": { "description": "`sent` means the support inbox has it. `queued` means it is written down and being retried. `failed` means delivery is unconfirmed and automatic retries have ended; contact support directly with the reference.", "enum": [ "queued", "sent", "failed" ], "type": "string" }, "subject": { "type": "string" } }, "required": [ "id", "reference", "status", "category", "subject", "createdAt" ], "type": "object" } }, "required": [ "ticket", "contactEmail", "expectedReply" ], "type": "object" } } }, "description": "Ask a person", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `conversation_not_found` — No such conversation." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly. · `handoff_limit` — You have sent support several messages in the last hour. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`handoff_failed` — Your message could not be sent just now. Try again shortly." } }, "security": [ { "DashboardSession": [] } ], "summary": "Ask a person", "tags": [ "assistant" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "support_handoff", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": null, "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "assistant:use" ] } }, "/assistant/messages": { "post": { "description": "Ask a question about GogoScreen and get an answer, in the same call. Without `conversationId` a new conversation is started; with one, the question continues that thread. The answer is plain text written from a knowledge base built out of this product's own limits; the assistant has no tools, cannot see anything about any other customer, and cannot change, refund or decide anything about an account — when a question needs a person it says so and sets `handoffSuggested`. `remainingToday` is how many more questions this account may ask before the daily cap; null when the cap is off.", "operationId": "assistant.messages.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conversationId": { "description": "Continue this conversation. Omit to start a new one. A conversation of another account is a 404.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "message": { "description": "The question, as the customer typed it. Treated as text throughout: it is never part of the assistant's instructions, and credentials or card numbers in it are removed before it is stored.", "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "conversation": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "description": "The conversation's id. Pass it as `conversationId` to keep asking in the same thread.", "type": "string" }, "lastMessageAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "When the thread was last written to. Null on a conversation with no messages yet." }, "messageCount": { "description": "How many questions the customer has asked in this thread. The per-conversation cap counts this, not the replies.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "status": { "description": "`open` takes another question. `closed` and `handed_off` both refuse one with 409 `conversation_closed`; start a new conversation.", "enum": [ "open", "closed", "handed_off" ], "type": "string" } }, "required": [ "id", "status", "messageCount", "lastMessageAt", "createdAt" ], "type": "object" }, "remainingToday": { "anyOf": [ { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, { "type": "null" } ] }, "reply": { "additionalProperties": false, "properties": { "content": { "description": "Plain text. The assistant writes no HTML, no markdown headings and no links off this product.", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "handoffSuggested": { "description": "The assistant believes a person should take this. Offer the hand-off; it is never taken automatically.", "type": "boolean" }, "id": { "type": "string" }, "role": { "enum": [ "user", "assistant" ], "type": "string" }, "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The assistant's own label for what the question was about — one of product, billing, account, api, troubleshooting, escalation, off_topic. Null on a customer's turn." } }, "required": [ "id", "role", "content", "topic", "handoffSuggested", "createdAt" ], "type": "object" } }, "required": [ "conversation", "reply", "remainingToday" ], "type": "object" } } }, "description": "Ask the assistant", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `feature_disabled` — That feature is not available." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `conversation_not_found` — No such conversation." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `conversation_closed` — That conversation is closed. Start a new one. · `assistant_conversation_full` — This conversation has run as long as it can. Start a new one." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly. · `assistant_daily_limit` — You have reached today's limit for the assistant. You can still send a message to a person. · `ai_rate_limited` — You have asked a lot in the last hour. Try again shortly, or send a message to a person." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`assistant_unavailable` — The assistant is unavailable right now. A person can still help." } }, "security": [ { "DashboardSession": [] } ], "summary": "Ask the assistant", "tags": [ "assistant" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": null, "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "assistant:use" ] } }, "/catalog/marketing/templates": { "get": { "description": "The marketing video designs this deployment can make, by family. `walkthrough` designs cut a recorded walkthrough into a promo; `website` designs build one from a scanned site and need no recording. Each entry carries its formats, its lengths, its audio modes, its copy roles and what an export of it costs in seconds.", "operationId": "catalog.marketing.templates.list", "parameters": [ { "description": "Which catalogue: designs that cut a recording, or designs built from a website scan.", "in": "query", "name": "family", "required": false, "schema": { "default": "walkthrough", "enum": [ "walkthrough", "website" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "family": { "enum": [ "walkthrough", "website" ], "type": "string" }, "narration": { "anyOf": [ { "additionalProperties": {}, "description": "What a narrated design may be asked for: cadences, speed range and languages. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "templates": { "items": { "additionalProperties": {}, "properties": { "audioModes": { "items": { "type": "string" }, "type": "array" }, "description": { "type": "string" }, "formats": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "name": { "type": "string" }, "secondsPerExport": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "What one export of each format and length costs in seconds, at 1x speed." }, "version": { "type": "string" } }, "required": [ "id", "name", "description", "version", "formats", "audioModes" ], "type": "object" }, "type": "array" }, "tracks": { "items": { "additionalProperties": {}, "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "mood": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title", "mood", "collection" ], "type": "object" }, "type": "array" } }, "required": [ "family", "templates" ], "type": "object" } } }, "description": "The marketing designs", "headers": { "Cache-Control": { "description": "Always `public, max-age=300`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "catalog:read" ] }, { "DashboardSession": [] } ], "summary": "The marketing designs", "tags": [ "catalog" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "catalog_marketing_templates_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "catalog:read" ] } }, "/catalog/plans": { "get": { "description": "The monthly plans and the top up rate, in SECONDS of finished video. Plans are monthly subscriptions: each paid month fills the plan time, which ends with the billing period. Top up time never expires. Prices are in US dollars. Buying is not part of this API: this read exists so an integration can tell a customer what a plan or a top up gives them.", "operationId": "catalog.plans.list", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "freeSecondsOnSignup": { "type": "number" }, "payg": { "additionalProperties": {}, "description": "The top up rate: seconds per dollar, the minimum in whole dollars, and the preset amounts. Top up time never expires.", "properties": {}, "type": "object" }, "planMonths": { "description": "How long one paid period of plan time lasts, in months: 1 (plans renew monthly).", "type": "number" }, "plans": { "items": { "additionalProperties": {}, "properties": { "id": { "type": "string" }, "interval": { "description": "How often the plan renews: month.", "type": "string" }, "name": { "type": "string" }, "priceUsd": { "type": "number" }, "rank": { "type": "number" }, "seconds": { "type": "number" } }, "required": [ "id", "name", "seconds", "priceUsd", "rank", "interval" ], "type": "object" }, "type": "array" } }, "required": [ "plans", "payg", "planMonths", "freeSecondsOnSignup" ], "type": "object" } } }, "description": "The plans and the top up rate", "headers": { "Cache-Control": { "description": "Always `public, max-age=300`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "catalog:read" ] }, { "DashboardSession": [] } ], "summary": "The plans and the top up rate", "tags": [ "catalog" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "catalog_plans_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "catalog:read" ] } }, "/catalog/render-options": { "get": { "description": "Every choice a walkthrough render accepts: the look templates, the voices, the orientations, the capture sizes (with the pixel size each records at), the length presets, the languages, the backgrounds, and the caption styles (each with the style block it is drawn from, so a client can show a faithful sample). The ids here are the ids `renders.create` and `storyboards.create` take. `avatars` is present and EMPTY while the presenter circle is switched off on this deployment; an `avatarId` is not a field those operations take then.", "operationId": "catalog.renderOptions", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "autoMaxSeconds": { "additionalProperties": false, "properties": { "default": { "type": "number" }, "max": { "type": "number" }, "min": { "type": "number" } }, "required": [ "min", "max", "default" ], "type": "object" }, "avatars": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "backgrounds": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "captionStyles": { "description": "How burned-in captions look, for the look templates that burn them. Each row carries `look`, the style block the captions are actually drawn with.", "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "captures": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "languages": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "lengths": { "items": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "narration": { "type": "boolean" }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "seconds", "narration" ], "type": "object" }, "type": "array" }, "minTargetSeconds": { "type": "number" }, "orientations": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "templates": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "voices": { "items": { "additionalProperties": {}, "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" } }, "required": [ "templates", "voices", "orientations", "captures", "avatars", "captionStyles", "lengths", "minTargetSeconds", "autoMaxSeconds", "languages", "backgrounds" ], "type": "object" } } }, "description": "The walkthrough render options", "headers": { "Cache-Control": { "description": "Always `public, max-age=300`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "catalog:read" ] }, { "DashboardSession": [] } ], "summary": "The walkthrough render options", "tags": [ "catalog" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "catalog_renderOptions", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "catalog:read" ] } }, "/catalog/voices": { "get": { "description": "Every voice a render or a marketing export may be narrated by: its id, its name, the languages it reads and how it sounds.", "operationId": "catalog.voices.list", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "voices": { "items": { "additionalProperties": {}, "properties": { "description": { "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "languages": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "id", "name", "description", "isDefault", "languages", "gender" ], "type": "object" }, "type": "array" } }, "required": [ "voices" ], "type": "object" } } }, "description": "The narration voices", "headers": { "Cache-Control": { "description": "Always `public, max-age=300`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "catalog:read" ] }, { "DashboardSession": [] } ], "summary": "The narration voices", "tags": [ "catalog" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "catalog_voices_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "catalog:read" ] } }, "/keys": { "get": { "description": "Every key this account holds, newest first — active, revoked and expired. The key material itself is never returned: a key is shown once, when it is created.", "operationId": "keys.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's API keys", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "The account's API keys", "tags": [ "keys" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "api_key_management", "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "keys_list", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "keys:manage" ] }, "post": { "description": "Mint a key for this account. The plaintext is in the response and nowhere else: it is never stored in readable form and cannot be recovered. A key may hold any scope except `keys:manage`: a credential that could create credentials would outlive its own revocation. At most 25 active keys per account.", "operationId": "keys.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "When the key stops working. Omit for a key that does not expire." }, "name": { "description": "What this key is for. Shown in the console and in the account's audit trail.", "maxLength": 120, "minLength": 1, "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 864000, "type": "integer" }, { "type": "null" } ], "description": "A daily request cap for this key alone (up to 864000, the per-minute ceiling run for 24 hours)." }, "rateLimitPerMinute": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, { "type": "null" } ], "description": "A ceiling below the rate class's own. Cannot raise it." }, "scopes": { "description": "What the key may do. At least one, and from this list only: two scopes are never on it. `keys:manage` is withheld because a key that could mint keys would outlive its own revocation, and `assistant:use` because the in-app assistant is for people in the dashboard, not for integrations.", "items": { "enum": [ "catalog:read", "account:read", "wallet:read", "usage:read", "storyboards:read", "storyboards:write", "renders:read", "renders:write", "marketing:read", "marketing:write", "marketing:export", "webhooks:manage" ], "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array" } }, "required": [ "name", "scopes" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "apiKey": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" }, "key": { "description": "THE KEY. This is the only time it is shown: it is never stored in readable form and cannot be recovered. Save it now; if it is lost, rotate.", "type": "string" } }, "required": [ "key", "apiKey" ], "type": "object" } } }, "description": "Create an API key", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "Create an API key", "tags": [ "keys" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "api_key_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "keys_create", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "keys:manage" ] } }, "/keys/{id}": { "get": { "description": "One key of this account, by id. A key belonging to another account is a 404, never a 403.", "operationId": "keys.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "apiKey": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" } }, "required": [ "apiKey" ], "type": "object" } } }, "description": "One API key", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "One API key", "tags": [ "keys" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "api_key_management", "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "keys_get", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "keys:manage" ] } }, "/keys/{id}/revoke": { "post": { "description": "Kill a key. It stops working everywhere within a second. Revoking an already-revoked key succeeds: making sure a credential is dead must always be possible.", "operationId": "keys.revoke", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "apiKey": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" } }, "required": [ "apiKey" ], "type": "object" } } }, "description": "Revoke an API key", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "Revoke an API key", "tags": [ "keys" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "api_key_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "keys_revoke", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "keys:manage" ] } }, "/keys/{id}/rotate": { "post": { "description": "Replace a key with a new one carrying the same name, scopes and limits. The new plaintext is in the response and nowhere else. With `graceSeconds`, the old key keeps working for that long so a fleet can pick the new value up without an outage; with 0 it dies now. A grace window never extends a key that was already expiring sooner.", "operationId": "keys.rotate", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "graceSeconds": { "default": 0, "description": "How long the old key keeps working, up to a day. 0 revokes it immediately.", "maximum": 86400, "minimum": 0, "type": "integer" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "apiKey": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" }, "key": { "description": "THE KEY. This is the only time it is shown: it is never stored in readable form and cannot be recovered. Save it now; if it is lost, rotate.", "type": "string" }, "previous": { "additionalProperties": false, "description": "The key that was replaced, as it now stands.", "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "last4": { "description": "The last four characters, for telling two keys apart in a list.", "type": "string" }, "lastUsedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ], "description": "Written at most once a minute, so it is accurate to the minute and not to the request." }, "name": { "type": "string" }, "prefix": { "description": "`gsk_live_` plus the first eight characters of the secret. Enough to recognise a key; not enough to use one.", "type": "string" }, "rateLimitPerDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key daily cap. Null means uncapped by the key itself." }, "rateLimitPerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "A per-key ceiling. Null means the rate class's own limit applies; a number can only ever lower it." }, "revokedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "name", "prefix", "last4", "scopes", "status", "rateLimitPerMinute", "rateLimitPerDay", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ], "type": "object" } }, "required": [ "key", "apiKey", "previous" ], "type": "object" } } }, "description": "Rotate an API key", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "DashboardSession": [] } ], "summary": "Rotate an API key", "tags": [ "keys" ], "x-actors": [ "user" ], "x-async-kind": null, "x-audit": "api_key_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "keys_rotate", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "keys:manage" ] } }, "/marketing/brand-kit": { "get": { "description": "The brand a marketing video signs with. `null` when the account has never saved one — which is not an error: every design has a default derived from the source.", "operationId": "marketing.brandKit.get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "brandKit": { "anyOf": [ { "additionalProperties": false, "properties": { "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyLanguage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "font": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hasLogo": { "type": "boolean" }, "logoType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "palette": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "accent", "defaultCta", "palette", "font", "copyLanguage", "tone", "hasLogo", "logoType", "updatedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "brandKit" ], "type": "object" } } }, "description": "The account's brand kit", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "The account's brand kit", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_brandKit_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] }, "put": { "description": "Set the brand a marketing video signs with: the name on the pill, the accent colour, the default closing line, and optionally a palette, a font, a copy language and a tone. The whole kit is REPLACED, not merged — `name` and `accent` are always required, and a half left out of `palette`/`font`/`copyLanguage`/`tone` keeps what the row already had. The house copy rule is enforced here: no dashes in the name or the call to action, because the designs set them in type that has no dash. The logo is not set here: files are not part of v1.0.", "operationId": "marketing.brandKit.put", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accent": { "description": "The accent colour as #rrggbb.", "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "copyLanguage": { "anyOf": [ { "maxLength": 35, "type": "string" }, { "type": "null" } ], "description": "A language tag such as en or fr-CA." }, "defaultCta": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ], "description": "The closing line when a video does not name one. No dashes." }, "font": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "A font id from the marketing catalogue." }, "name": { "description": "The name on the brand pill. No dashes.", "maxLength": 60, "minLength": 1, "type": "string" }, "palette": { "anyOf": [ { "items": { "maxLength": 16, "type": "string" }, "maxItems": 4, "type": "array" }, { "type": "null" } ], "description": "Up to four colours. The accent leads it; two entries are the band and the panel." }, "tone": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "accent" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "brandKit": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "brandKit" ], "type": "object" } } }, "description": "Save the account's brand kit", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `invalid_brand_kit` — That brand kit is not valid. `details.errors` names each problem." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Save the account's brand kit", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_brandKit_put", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] } }, "/marketing/exports": { "get": { "description": "Every marketing export this account owns, newest first, as a cursor page. Narrow to one project with `projectId`.", "operationId": "marketing.exports.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, { "description": "The resource `id`, from a create answer or the matching list.", "in": "query", "name": "projectId", "required": false, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": {}, "properties": { "audioMode": { "type": "string" }, "durationSeconds": { "type": "number" }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "hasCaptions": { "type": "boolean" }, "hasCover": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "id": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "maximum": 100, "minimum": 0, "type": "integer" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "The last progress reading while the export runs: the current step and a whole percent. null once it has settled, and null when no reading was recorded." }, "projectId": { "type": "string" }, "qa": { "anyOf": [ { "additionalProperties": false, "properties": { "notes": { "description": "What the export did that a person may want to know, as codes: `font_missing`, `cover_drawn`, `cover_not_drawn`, `narration_fitted`, `transcript_written`, `transcript_not_written`. A note is not a failure.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Whether the automated checks on the finished file passed.", "type": "boolean" } }, "required": [ "ok", "notes" ], "type": "object" }, { "type": "null" } ], "description": "The outcome of the automated checks, once they have run; null before. Why an export failed is `failureCode`." }, "revisionId": { "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" }, "watermark": { "type": "string" } }, "required": [ "id", "projectId", "revisionId", "format", "durationSeconds", "audioMode", "status", "state", "secondsReserved", "secondsCharged", "watermark", "failureCode", "progress", "hasCover", "hasCaptions", "hasTranscript", "qa" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's marketing exports", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "The account's marketing exports", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_exports_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/exports/quote": { "post": { "description": "How many seconds an export of this design, format and length would reserve — the same arithmetic the reservation does, divided by the speed the revision plays at — and what the account has available. Nothing is created and nothing is spent.", "operationId": "marketing.exports.quote", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "durationSeconds": { "description": "One the design offers at this format. The six-second edition is retired and is refused here.", "maximum": 600, "minimum": 7, "type": "integer" }, "format": { "description": "landscape | portrait | square | four-five.", "maxLength": 32, "minLength": 1, "type": "string" }, "speed": { "default": 1, "description": "The playback speed the revision records; the cost is the delivered length.", "exclusiveMinimum": 0, "maximum": 4, "type": "number" }, "templateId": { "description": "A design id from catalog.marketing.templates.list.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "templateId", "format", "durationSeconds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "availableSeconds": { "type": "number" }, "needed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "seconds": { "description": "What `marketing.exports.create` would reserve.", "type": "number" }, "sufficient": { "type": "boolean" } }, "required": [ "seconds", "availableSeconds", "sufficient", "needed" ], "type": "object" } } }, "description": "What an export would cost", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `unsupported_export` — That design does not offer that format at that length. `details` lists what it does offer." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `template_not_found` — No such template." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "What an export would cost", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_exports_quote", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/exports/{id}": { "get": { "description": "What an export is doing, what it cost in seconds, and which sidecars it produced (cover image, captions, approved transcript). A succeeded export whose files were deleted at the end of the retention period still reads `succeeded`, with `failureCode: \"expired\"` — the outcome stands, the download is gone.", "operationId": "marketing.exports.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "credit": { "anyOf": [ { "additionalProperties": {}, "description": "The music credit this export's bed owes, when it plays one. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "export": { "additionalProperties": {}, "properties": { "audioMode": { "type": "string" }, "durationSeconds": { "type": "number" }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "hasCaptions": { "type": "boolean" }, "hasCover": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "id": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "maximum": 100, "minimum": 0, "type": "integer" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "The last progress reading while the export runs: the current step and a whole percent. null once it has settled, and null when no reading was recorded." }, "projectId": { "type": "string" }, "qa": { "anyOf": [ { "additionalProperties": false, "properties": { "notes": { "description": "What the export did that a person may want to know, as codes: `font_missing`, `cover_drawn`, `cover_not_drawn`, `narration_fitted`, `transcript_written`, `transcript_not_written`. A note is not a failure.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Whether the automated checks on the finished file passed.", "type": "boolean" } }, "required": [ "ok", "notes" ], "type": "object" }, { "type": "null" } ], "description": "The outcome of the automated checks, once they have run; null before. Why an export failed is `failureCode`." }, "revisionId": { "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" }, "watermark": { "type": "string" } }, "required": [ "id", "projectId", "revisionId", "format", "durationSeconds", "audioMode", "status", "state", "secondsReserved", "secondsCharged", "watermark", "failureCode", "progress", "hasCover", "hasCaptions", "hasTranscript", "qa" ], "type": "object" } }, "required": [ "export", "credit" ], "type": "object" } } }, "description": "One marketing export", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "One marketing export", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_exports_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/exports/{id}/cancel": { "post": { "description": "Stop an export that has not finished and hand the reserved video time back whole. An export that has already succeeded, failed or been cancelled is 409 `already_settled` and nothing changes — the settlement is one conditional update, so a cancel racing a finish never moves the money twice.", "operationId": "marketing.exports.cancel", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "export": { "additionalProperties": {}, "properties": { "audioMode": { "type": "string" }, "durationSeconds": { "type": "number" }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "hasCaptions": { "type": "boolean" }, "hasCover": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "id": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "maximum": 100, "minimum": 0, "type": "integer" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "The last progress reading while the export runs: the current step and a whole percent. null once it has settled, and null when no reading was recorded." }, "projectId": { "type": "string" }, "qa": { "anyOf": [ { "additionalProperties": false, "properties": { "notes": { "description": "What the export did that a person may want to know, as codes: `font_missing`, `cover_drawn`, `cover_not_drawn`, `narration_fitted`, `transcript_written`, `transcript_not_written`. A note is not a failure.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Whether the automated checks on the finished file passed.", "type": "boolean" } }, "required": [ "ok", "notes" ], "type": "object" }, { "type": "null" } ], "description": "The outcome of the automated checks, once they have run; null before. Why an export failed is `failureCode`." }, "revisionId": { "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" }, "watermark": { "type": "string" } }, "required": [ "id", "projectId", "revisionId", "format", "durationSeconds", "audioMode", "status", "state", "secondsReserved", "secondsCharged", "watermark", "failureCode", "progress", "hasCover", "hasCaptions", "hasTranscript", "qa" ], "type": "object" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "export" ], "type": "object" } } }, "description": "Stop an export", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `unsupported_audio_mode` — That design does not offer that audio mode. `details.audioModes` lists what it does. · `invalid_cover_text` — Those cover words are not valid for this design and shape. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `no_revision` — That project has no revision to export yet. `details.missing` says what to put right. · `revision_conflict` — That revision is no longer the project's current one. · `revision_configuration_mismatch` — That export does not match the revision's own shape, length or audio. `details.missing` says what to put right. · `too_many_in_flight` — Too many operations are already running on this account. · `already_settled` — That operation has already finished." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_expired` — That source is past its retention window." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_speed_not_offered` — That version is saved at a speed we do not offer. `details.missing` says what to put right. · `campaign_speed_breaks_music_ending` — At that version's saved speed the music would not end with the film. `details.missing` says what to put right. · `campaign_speed_breaks_narration_fit` — At that version's saved speed a spoken line would no longer fit its shot. `details.missing` says what to put right." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`reservation_failed` — Video time could not be reserved. Try again shortly. · `queue_unavailable` — That work cannot be queued right now. Try again shortly." } }, "security": [ { "ApiKey": [ "marketing:export" ] }, { "DashboardSession": [] } ], "summary": "Stop an export", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_exports_cancel", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:export" ] } }, "/marketing/exports/{id}/download": { "get": { "description": "A short-lived signed URL for the export's MP4 (`asset=video`, the default) or one of its sidecars: the cover JPEG, the SRT captions, or the approved transcript. 409 while the export is not finished; 410 once the file was deleted at the end of the retention period; 404 when the export never produced that sidecar.", "operationId": "marketing.exports.download", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "description": "Which file to download: the video itself, its cover image, its captions or the narration transcript.", "in": "query", "name": "asset", "required": false, "schema": { "default": "video", "enum": [ "video", "cover", "captions", "transcript" ], "type": "string" } }, { "description": "Ask the signed URL to download rather than play.", "in": "query", "name": "attachment", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "description": "When the URL stops working.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "A signed URL. Short-lived, single-purpose, and not shareable.", "type": "string" } }, "required": [ "url", "expiresAt" ], "type": "object" } } }, "description": "A link to a finished export or one of its sidecars", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_finished` — That export is not finished yet." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`expired` — That file is past its retention window and has been deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "A link to a finished export or one of its sidecars", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_exports_download", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/generations": { "get": { "description": "Every generation this account has started, newest first, as a cursor page.", "operationId": "marketing.generations.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's generations", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "The account's generations", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_generations_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] }, "post": { "description": "Build a marketing video from a scanned website: the scan is turned into planned scenes and words, and the result is a project with a first revision to edit and export. Send `assist: true` with `assetUseConsent: true` to have the words written for you, or a `review` block to use words a person already approved. Generating costs no video time — the EXPORT charges — but the account must be able to afford the film. Answers 202 with a `Location`; poll until `state` is terminal, then read `projectId`. One generation at a time.", "operationId": "marketing.generations.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assetUseConsent": { "const": true, "description": "Your consent to use the pictures the scan found on your own site.", "type": "boolean" }, "assist": { "const": true, "description": "Have the words written for you. Requires `assetUseConsent`.", "type": "boolean" }, "audioMode": { "enum": [ "music", "silent", "voice", "voice-music" ], "type": "string" }, "brandChoice": { "enum": [ "saved", "website" ], "type": "string" }, "brandName": { "maxLength": 40, "minLength": 1, "type": "string" }, "brief": { "additionalProperties": {}, "description": "{ audience, objective, mustSay } — what the words should aim at.", "properties": {}, "type": "object" }, "durationSeconds": { "description": "One the design offers at this format, from `catalog.marketing.templates.list`. The six-second edition is retired and is refused here.", "maximum": 600, "minimum": 7, "type": "integer" }, "expectedRevisionId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "format": { "enum": [ "portrait", "landscape", "square", "four-five" ], "type": "string" }, "music": { "additionalProperties": {}, "description": "{ trackId } from the design's own catalogue.", "properties": {}, "type": "object" }, "narration": { "anyOf": [ { "additionalProperties": {}, "properties": {}, "type": "object" }, { "type": "null" } ], "description": "The voice the words are written FOR: { voiceId, language, cadence, synthesisSpeed? }. Absent means no spoken narration." }, "projectId": { "description": "Re-generate INTO an existing project; requires `expectedRevisionId`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "review": { "additionalProperties": {}, "description": "The approved copy and scene choices. Judged by the campaign contract's own schema.", "properties": {}, "type": "object" }, "source": { "additionalProperties": false, "description": "Which scanned website and which manifest version this is made from.", "properties": { "kind": { "const": "website", "description": "Always `website`. The only source kind this field takes.", "type": "string" }, "manifestHash": { "description": "The manifest's sha256, as `marketing.sources.get` answers it. Pins the exact scan this was planned against.", "pattern": "^[a-f0-9]{64}$", "type": "string" }, "sourceId": { "description": "The `id` of a scanned source from `marketing.sources.list`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "version": { "description": "Which manifest version of that source — `marketing.sources.get` answers the current one.", "exclusiveMinimum": 0, "maximum": 100000, "type": "integer" } }, "required": [ "kind", "sourceId", "version" ], "type": "object" }, "templateId": { "description": "A design id from catalog.marketing.templates.list (family=website).", "maxLength": 64, "minLength": 1, "type": "string" }, "templateVersion": { "maxLength": 16, "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "source", "templateId", "format", "durationSeconds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "generation", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "generation", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this marketing.generation, e.g. `/api/v1/marketing/generations/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `brand_logo_source_mismatch` — That logo choice does not match the source it names." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `generation_not_found` — No such generation. · `project_not_found` — No such project. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `generation_busy` — Another generation is already running for that source. · `generation_not_retryable` — That generation cannot be run again. · `generation_idempotency_conflict` — That idempotency key was already used with a different generation. · `brand_kit_required` — Save a brand kit first. · `brand_logo_not_retained` — The logo that choice needs is no longer held. · `source_owner_unavailable` — That account cannot start new work. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place. · `campaign_unsupported_claim` — One of those statements is not supported by anything the website says. · `invalid_campaign_narration` — That narration request is not valid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Turn a scanned website into a marketing project", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "marketing.generation", "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_generations_create", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/marketing/generations/preflight": { "post": { "description": "Judge a generation request without starting one: the design exists, the manifest has the pictures it needs, the words would fit the frames, the brand is resolvable. Allocates nothing, spends nothing, creates nothing — it is a read in every sense but the verb, which is a POST because the request is a body. A refusal names the field, so a form can point at it before a customer waits for a video.", "operationId": "marketing.generations.preflight", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assetUseConsent": { "const": true, "description": "Your consent to use the pictures the scan found on your own site.", "type": "boolean" }, "assist": { "const": true, "description": "Have the words written for you. Requires `assetUseConsent`.", "type": "boolean" }, "audioMode": { "enum": [ "music", "silent", "voice", "voice-music" ], "type": "string" }, "brandChoice": { "enum": [ "saved", "website" ], "type": "string" }, "brandName": { "maxLength": 40, "minLength": 1, "type": "string" }, "brief": { "additionalProperties": {}, "description": "{ audience, objective, mustSay } — what the words should aim at.", "properties": {}, "type": "object" }, "durationSeconds": { "description": "One the design offers at this format, from `catalog.marketing.templates.list`. The six-second edition is retired and is refused here.", "maximum": 600, "minimum": 7, "type": "integer" }, "expectedRevisionId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "format": { "enum": [ "portrait", "landscape", "square", "four-five" ], "type": "string" }, "music": { "additionalProperties": {}, "description": "{ trackId } from the design's own catalogue.", "properties": {}, "type": "object" }, "narration": { "anyOf": [ { "additionalProperties": {}, "properties": {}, "type": "object" }, { "type": "null" } ], "description": "The voice the words are written FOR: { voiceId, language, cadence, synthesisSpeed? }. Absent means no spoken narration." }, "projectId": { "description": "Re-generate INTO an existing project; requires `expectedRevisionId`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "review": { "additionalProperties": {}, "description": "The approved copy and scene choices. Judged by the campaign contract's own schema.", "properties": {}, "type": "object" }, "source": { "additionalProperties": false, "description": "Which scanned website and which manifest version this is made from.", "properties": { "kind": { "const": "website", "description": "Always `website`. The only source kind this field takes.", "type": "string" }, "manifestHash": { "description": "The manifest's sha256, as `marketing.sources.get` answers it. Pins the exact scan this was planned against.", "pattern": "^[a-f0-9]{64}$", "type": "string" }, "sourceId": { "description": "The `id` of a scanned source from `marketing.sources.list`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "version": { "description": "Which manifest version of that source — `marketing.sources.get` answers the current one.", "exclusiveMinimum": 0, "maximum": 100000, "type": "integer" } }, "required": [ "kind", "sourceId", "version" ], "type": "object" }, "templateId": { "description": "A design id from catalog.marketing.templates.list (family=website).", "maxLength": 64, "minLength": 1, "type": "string" }, "templateVersion": { "maxLength": 16, "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "source", "templateId", "format", "durationSeconds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": {}, "description": "What the request would be accepted as: validity, the template version it resolved to, and whether copy is required. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" } } }, "description": "Would this generation be accepted?", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `brand_logo_source_mismatch` — That logo choice does not match the source it names." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `generation_not_found` — No such generation. · `project_not_found` — No such project. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`generation_busy` — Another generation is already running for that source. · `generation_not_retryable` — That generation cannot be run again. · `generation_idempotency_conflict` — That idempotency key was already used with a different generation. · `brand_kit_required` — Save a brand kit first. · `brand_logo_not_retained` — The logo that choice needs is no longer held. · `source_owner_unavailable` — That account cannot start new work. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place. · `campaign_unsupported_claim` — One of those statements is not supported by anything the website says. · `invalid_campaign_narration` — That narration request is not valid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Would this generation be accepted?", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_generations_preflight", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/marketing/generations/{id}": { "get": { "description": "What a generation is doing and what it produced. Poll `state` until it is terminal; on `succeeded`, `projectId` and `revisionId` name the project that was made. `retryable` says whether a failure is worth asking again; work already completed is reused on a retry.", "operationId": "marketing.generations.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" } }, "required": [ "generation" ], "type": "object" } } }, "description": "One generation", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `generation_not_found` — No such generation." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "One generation", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_generations_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/generations/{id}/cancel": { "post": { "description": "Stop a generation that has not started being worked. One already in progress finishes its current step, so a cancel that arrives late is 200 with the generation unchanged. Read `state` to see which happened.", "operationId": "marketing.generations.cancel", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "generation" ], "type": "object" } } }, "description": "Stop a generation", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `brand_logo_source_mismatch` — That logo choice does not match the source it names." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `generation_not_found` — No such generation. · `project_not_found` — No such project. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `generation_busy` — Another generation is already running for that source. · `generation_not_retryable` — That generation cannot be run again. · `generation_idempotency_conflict` — That idempotency key was already used with a different generation. · `brand_kit_required` — Save a brand kit first. · `brand_logo_not_retained` — The logo that choice needs is no longer held. · `source_owner_unavailable` — That account cannot start new work. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place. · `campaign_unsupported_claim` — One of those statements is not supported by anything the website says. · `invalid_campaign_narration` — That narration request is not valid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Stop a generation", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_generations_cancel", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] } }, "/marketing/generations/{id}/retry": { "post": { "description": "Ask a failed generation to run again. Only some failures are worth retrying, such as a temporary outage, and `retryable` on the generation says which; anything else is 409 `generation_not_retryable`. Words the AI already wrote for this generation are reused, not written again, so a retry after the words were written resumes where it stopped. Answers 202 with a `Location`; poll `marketing.generations.get` until `state` is terminal.", "operationId": "marketing.generations.retry", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "generation", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "generation": { "additionalProperties": {}, "properties": { "assisted": { "type": "boolean" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "revisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageUpdatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status", "state", "assisted", "projectId", "revisionId", "errorCode", "retryable", "stage", "stageUpdatedAt" ], "type": "object" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "generation", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this marketing.generation, e.g. `/api/v1/marketing/generations/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `brand_logo_source_mismatch` — That logo choice does not match the source it names." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `generation_not_found` — No such generation. · `project_not_found` — No such project. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `generation_busy` — Another generation is already running for that source. · `generation_not_retryable` — That generation cannot be run again. · `generation_idempotency_conflict` — That idempotency key was already used with a different generation. · `brand_kit_required` — Save a brand kit first. · `brand_logo_not_retained` — The logo that choice needs is no longer held. · `source_owner_unavailable` — That account cannot start new work. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place. · `campaign_unsupported_claim` — One of those statements is not supported by anything the website says. · `invalid_campaign_narration` — That narration request is not valid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Run a failed generation again", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "marketing.generation", "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_generations_retry", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/marketing/projects": { "get": { "description": "Every marketing project this account owns, newest first, as a cursor page, each with what its newest export is doing.", "operationId": "marketing.projects.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "currentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "latestExport": { "anyOf": [ { "additionalProperties": {}, "properties": { "id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, { "type": "null" } ] }, "marketingSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceKind": { "enum": [ "walkthrough", "website" ], "type": "string" }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "templateId": { "type": "string" }, "templateVersion": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "sourceRenderId", "templateId", "templateVersion", "sourceKind", "marketingSourceId", "currentRevisionId", "status", "createdAt", "updatedAt", "latestExport" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's marketing projects", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "The account's marketing projects", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_projects_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] }, "post": { "description": "Make an editable marketing video from something this account already has: a finished WALKTHROUGH render (`renderId`), or a scanned WEBSITE (`source`). The project opens at its first revision, which you can rework with `marketing.revisions.create` and cut with `marketing.exports.create`. Nothing is charged here — the export is what spends video time. A walkthrough project needs its render's clean source to still be kept; 409 `source_not_ready` says it is not.", "operationId": "marketing.projects.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "durationSeconds": { "description": "The length the first revision opens at. Must be one the design offers, from `catalog.marketing.templates.list`; the six-second edition is retired and is refused here.", "maximum": 600, "minimum": 7, "type": "integer" }, "format": { "enum": [ "portrait", "landscape", "square", "four-five" ], "type": "string" }, "renderId": { "description": "A finished walkthrough render of this account's. Exclusive with `source`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "review": { "additionalProperties": {}, "description": "Website projects only: the approved copy and scene choices.", "properties": {}, "type": "object" }, "source": { "additionalProperties": false, "description": "A scanned website this project is made from. Exclusive with `renderId`.", "properties": { "kind": { "const": "website", "description": "Always `website`. The only source kind this field takes.", "type": "string" }, "manifestHash": { "description": "The manifest's sha256, as `marketing.sources.get` answers it. Pins the exact scan this was planned against.", "pattern": "^[a-f0-9]{64}$", "type": "string" }, "sourceId": { "description": "The `id` of a scanned source from `marketing.sources.list`.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "version": { "description": "Which manifest version of that source — `marketing.sources.get` answers the current one.", "exclusiveMinimum": 0, "maximum": 100000, "type": "integer" } }, "required": [ "kind", "sourceId", "version" ], "type": "object" }, "templateId": { "description": "A design id from catalog.marketing.templates.list.", "maxLength": 64, "minLength": 1, "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "templateId", "format" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "project": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "currentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "marketingSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceKind": { "enum": [ "walkthrough", "website" ], "type": "string" }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "templateId": { "type": "string" }, "templateVersion": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "sourceRenderId", "templateId", "templateVersion", "sourceKind", "marketingSourceId", "currentRevisionId", "status", "createdAt", "updatedAt" ], "type": "object" }, "revision": { "anyOf": [ { "additionalProperties": {}, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "document": { "additionalProperties": {}, "description": "The revision's own document: the scenes, the copy, the music and the timing. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "id": { "type": "string" }, "locks": { "additionalProperties": {}, "description": "The parts of this revision the customer has locked. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "number": { "type": "number" }, "parentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "projectId": { "type": "string" }, "restoredFromRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seed": { "type": "number" } }, "required": [ "id", "projectId", "number", "parentRevisionId", "restoredFromRevisionId", "document", "locks", "seed", "createdAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "project", "revision" ], "type": "object" } } }, "description": "Start a marketing project", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `invalid_revision` — That revision is not valid. `details.errors` says why. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw. · `edit_not_understood` — That change was not understood whole, so nothing was changed. `details` says why and what this editor does take." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_not_ready` — That source is not ready to be used yet. · `source_unreadable` — That source could not be read. · `missing_required_footage` — That design needs footage this recording does not have. `details.reasons` says which. · `revision_conflict` — That revision is no longer the project's current one. · `export_in_flight` — An export of that project is still running. · `gallery_example` — One of that project's exports is published as a gallery example. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Start a marketing project", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_projects_create", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] } }, "/marketing/projects/{id}": { "delete": { "description": "Remove a project, every revision it has and every export cut from it, files included. Refused with 409 `export_in_flight` while an export is still being made — cancel it first — and 409 `gallery_example` when one of its exports is published as a gallery example. Answers counts only.", "operationId": "marketing.projects.delete", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": {}, "description": "What was removed: the counts of revisions, exports and stored objects. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" } } }, "description": "Delete a marketing project", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `invalid_revision` — That revision is not valid. `details.errors` says why. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw. · `edit_not_understood` — That change was not understood whole, so nothing was changed. `details` says why and what this editor does take." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_not_ready` — That source is not ready to be used yet. · `source_unreadable` — That source could not be read. · `missing_required_footage` — That design needs footage this recording does not have. `details.reasons` says which. · `revision_conflict` — That revision is no longer the project's current one. · `export_in_flight` — An export of that project is still running. · `gallery_example` — One of that project's exports is published as a gallery example. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Delete a marketing project", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_projects_delete", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] }, "get": { "description": "The whole editor read for one project: the project row, its current revision (scenes, copy, music, timing), the state of its source and which slots still need a picture, the template at the version THIS project records — never the catalogue's newest — the music credit, and its exports newest first.", "operationId": "marketing.projects.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "credit": { "anyOf": [ { "additionalProperties": {}, "description": "The music credit this revision's bed owes. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "exports": { "items": { "additionalProperties": {}, "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "state", "status" ], "type": "object" }, "type": "array" }, "narration": { "anyOf": [ { "additionalProperties": {}, "description": "Whether this deployment can speak a written narration, and the sentence when it cannot. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "preview": { "anyOf": [ { "additionalProperties": {}, "description": "What a preview of the current revision would play. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "project": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "currentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "marketingSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceKind": { "enum": [ "walkthrough", "website" ], "type": "string" }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "templateId": { "type": "string" }, "templateVersion": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "sourceRenderId", "templateId", "templateVersion", "sourceKind", "marketingSourceId", "currentRevisionId", "status", "createdAt", "updatedAt" ], "type": "object" }, "revision": { "anyOf": [ { "additionalProperties": {}, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "document": { "additionalProperties": {}, "description": "The revision's own document: the scenes, the copy, the music and the timing. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "id": { "type": "string" }, "locks": { "additionalProperties": {}, "description": "The parts of this revision the customer has locked. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "number": { "type": "number" }, "parentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "projectId": { "type": "string" }, "restoredFromRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seed": { "type": "number" } }, "required": [ "id", "projectId", "number", "parentRevisionId", "restoredFromRevisionId", "document", "locks", "seed", "createdAt" ], "type": "object" }, { "type": "null" } ] }, "slots": { "description": "The picture slots of the design and what each could be filled with.", "items": { "additionalProperties": {}, "properties": {}, "type": "object" }, "type": "array" }, "source": { "anyOf": [ { "additionalProperties": {}, "description": "The state of what the project is made from. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "additionalProperties": {}, "description": "The template at the version this project records. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] } }, "required": [ "project", "revision", "source", "slots", "preview", "credit", "template", "exports", "narration" ], "type": "object" } } }, "description": "One marketing project", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "One marketing project", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_projects_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/projects/{id}/edits": { "post": { "description": "Describe a change in words — \"make the headline shorter\", \"swap scenes two and three\" — applied as an ordinary revision. Read DETERMINISTICALLY against this project's design and document: instant, free, and limited to a fixed vocabulary. `dryRun: true` parses only: it answers the changes, writes nothing, and says `guardsChecked: false` with the guards it did not run. NOTHING IS HALF APPLIED: a sentence not understood whole changes nothing, and 400 `edit_not_understood` carries the reason and the vocabulary that IS understood.", "operationId": "marketing.revisions.edit", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "dryRun": { "description": "Parse and report, write nothing.", "type": "boolean" }, "expectedRevisionId": { "description": "The resource `id`, from a create answer or the matching list.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "request": { "description": "The change, in a sentence.", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "request", "expectedRevisionId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "changes": { "items": { "additionalProperties": {}, "properties": {}, "type": "object" }, "type": "array" }, "currentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "guardsChecked": { "description": "False on a dry run: the limits, the locks and the compare-and-set were NOT run.", "type": "boolean" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "patch": { "anyOf": [ { "additionalProperties": {}, "description": "The patch the sentence resolved to. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "revision": { "anyOf": [ { "additionalProperties": {}, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "document": { "additionalProperties": {}, "description": "The revision's own document: the scenes, the copy, the music and the timing. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "id": { "type": "string" }, "locks": { "additionalProperties": {}, "description": "The parts of this revision the customer has locked. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "number": { "type": "number" }, "parentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "projectId": { "type": "string" }, "restoredFromRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seed": { "type": "number" } }, "required": [ "id", "projectId", "number", "parentRevisionId", "restoredFromRevisionId", "document", "locks", "seed", "createdAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "changes", "patch", "guardsChecked", "note", "revision", "currentRevisionId" ], "type": "object" } } }, "description": "Change a project with a sentence", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `invalid_revision` — That revision is not valid. `details.errors` says why. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw. · `edit_not_understood` — That change was not understood whole, so nothing was changed. `details` says why and what this editor does take." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_not_ready` — That source is not ready to be used yet. · `source_unreadable` — That source could not be read. · `missing_required_footage` — That design needs footage this recording does not have. `details.reasons` says which. · `revision_conflict` — That revision is no longer the project's current one. · `export_in_flight` — An export of that project is still running. · `gallery_example` — One of that project's exports is published as a gallery example. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Change a project with a sentence", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_revisions_edit", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/marketing/projects/{id}/exports": { "post": { "description": "Render one revision into a finished file, with cover, captions and transcript. THIS IS THE MARKETING OPERATION THAT SPENDS: time is reserved at the DELIVERED length (authored ÷ the revision's speed) and settled when the file is made; a cancelled or failed export is charged nothing. `expectedRevisionId` must be the current revision, or 409 `revision_conflict` with nothing reserved. Ask `marketing.exports.quote` first. Answers 202; at most three exports in flight.", "operationId": "marketing.exports.create", "parameters": [ { "description": "The project to export.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "audioMode": { "description": "Defaults to `music`.", "enum": [ "music", "silent", "voice", "voice-music" ], "type": "string" }, "coverText": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Words for the cover image, for THIS export only. Blank means none; it is never written back to the revision." }, "durationSeconds": { "description": "One the design offers at this format, and the one the named revision was saved with. The six-second edition is retired and is refused here.", "maximum": 600, "minimum": 7, "type": "integer" }, "expectedRevisionId": { "description": "The revision you are exporting. It must still be the project's current one.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "format": { "description": "One the design offers: landscape | portrait | square | four-five.", "maxLength": 32, "minLength": 1, "type": "string" } }, "required": [ "format", "durationSeconds", "expectedRevisionId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "export": { "additionalProperties": {}, "properties": { "audioMode": { "type": "string" }, "durationSeconds": { "type": "number" }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "hasCaptions": { "type": "boolean" }, "hasCover": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "id": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "maximum": 100, "minimum": 0, "type": "integer" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "The last progress reading while the export runs: the current step and a whole percent. null once it has settled, and null when no reading was recorded." }, "projectId": { "type": "string" }, "qa": { "anyOf": [ { "additionalProperties": false, "properties": { "notes": { "description": "What the export did that a person may want to know, as codes: `font_missing`, `cover_drawn`, `cover_not_drawn`, `narration_fitted`, `transcript_written`, `transcript_not_written`. A note is not a failure.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Whether the automated checks on the finished file passed.", "type": "boolean" } }, "required": [ "ok", "notes" ], "type": "object" }, { "type": "null" } ], "description": "The outcome of the automated checks, once they have run; null before. Why an export failed is `failureCode`." }, "revisionId": { "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" }, "watermark": { "type": "string" } }, "required": [ "id", "projectId", "revisionId", "format", "durationSeconds", "audioMode", "status", "state", "secondsReserved", "secondsCharged", "watermark", "failureCode", "progress", "hasCover", "hasCaptions", "hasTranscript", "qa" ], "type": "object" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "export", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "export": { "additionalProperties": {}, "properties": { "audioMode": { "type": "string" }, "durationSeconds": { "type": "number" }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "type": "string" }, "hasCaptions": { "type": "boolean" }, "hasCover": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "id": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "maximum": 100, "minimum": 0, "type": "integer" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "The last progress reading while the export runs: the current step and a whole percent. null once it has settled, and null when no reading was recorded." }, "projectId": { "type": "string" }, "qa": { "anyOf": [ { "additionalProperties": false, "properties": { "notes": { "description": "What the export did that a person may want to know, as codes: `font_missing`, `cover_drawn`, `cover_not_drawn`, `narration_fitted`, `transcript_written`, `transcript_not_written`. A note is not a failure.", "items": { "type": "string" }, "type": "array" }, "ok": { "description": "Whether the automated checks on the finished file passed.", "type": "boolean" } }, "required": [ "ok", "notes" ], "type": "object" }, { "type": "null" } ], "description": "The outcome of the automated checks, once they have run; null before. Why an export failed is `failureCode`." }, "revisionId": { "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "status": { "type": "string" }, "watermark": { "type": "string" } }, "required": [ "id", "projectId", "revisionId", "format", "durationSeconds", "audioMode", "status", "state", "secondsReserved", "secondsCharged", "watermark", "failureCode", "progress", "hasCover", "hasCaptions", "hasTranscript", "qa" ], "type": "object" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "export", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this marketing.export, e.g. `/api/v1/marketing/exports/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `unsupported_audio_mode` — That design does not offer that audio mode. `details.audioModes` lists what it does. · `invalid_cover_text` — Those cover words are not valid for this design and shape. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `no_revision` — That project has no revision to export yet. `details.missing` says what to put right. · `revision_conflict` — That revision is no longer the project's current one. · `revision_configuration_mismatch` — That export does not match the revision's own shape, length or audio. `details.missing` says what to put right. · `too_many_in_flight` — Too many operations are already running on this account. · `already_settled` — That operation has already finished." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_expired` — That source is past its retention window." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_speed_not_offered` — That version is saved at a speed we do not offer. `details.missing` says what to put right. · `campaign_speed_breaks_music_ending` — At that version's saved speed the music would not end with the film. `details.missing` says what to put right. · `campaign_speed_breaks_narration_fit` — At that version's saved speed a spoken line would no longer fit its shot. `details.missing` says what to put right." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`reservation_failed` — Video time could not be reserved. Try again shortly. · `queue_unavailable` — That work cannot be queued right now. Try again shortly." } }, "security": [ { "ApiKey": [ "marketing:export" ] }, { "DashboardSession": [] } ], "summary": "Cut the finished video", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "marketing.export", "x-audit": null, "x-idempotent": true, "x-kind": "charge", "x-mcp-tool": "marketing_exports_create", "x-rate-class": "charge", "x-rate-per-minute": 20, "x-scopes": [ "marketing:export" ] } }, "/marketing/projects/{id}/revisions": { "get": { "description": "The versions of one project, newest first: the headline, the length, the audio mode and the brand of each, so an integration can offer \"back to version n\". The full document of a revision comes with `marketing.projects.get`.", "operationId": "marketing.revisions.list", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "description": "How many to return (1–100). Newest first.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "currentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." }, "revisions": { "items": { "additionalProperties": false, "properties": { "audioMode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "number": { "type": "number" }, "parentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "restoredFromRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "number", "parentRevisionId", "restoredFromRevisionId", "headline", "durationSeconds", "audioMode", "brand", "createdAt" ], "type": "object" }, "type": "array" } }, "required": [ "revisions", "currentRevisionId", "nextCursor" ], "type": "object" } } }, "description": "A project's revisions", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "A project's revisions", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_revisions_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] }, "post": { "description": "Save a new version of a project: different words, different scenes, different music, a different speed or look, or a restore of an earlier version. `expectedRevisionId` is a compare-and-set against the project's CURRENT revision — if somebody else saved in the meantime it is 409 `revision_conflict` with the id that won, and nothing is written. Parts the customer has locked are not moved by a re-plan. Every version is kept, so every change is undoable.", "operationId": "marketing.revisions.create", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "copy": { "additionalProperties": {}, "description": "The words, by role.", "properties": {}, "type": "object" }, "expectedRevisionId": { "description": "The revision you are changing. A compare-and-set: 409 if it is no longer current.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "locks": { "additionalProperties": {}, "description": "The parts to pin against a re-plan.", "properties": {}, "type": "object" }, "music": { "additionalProperties": {}, "properties": {}, "type": "object" }, "narration": { "anyOf": [ { "additionalProperties": {}, "properties": {}, "type": "object" }, { "type": "boolean" }, { "type": "null" } ] }, "restoreRevisionId": { "description": "Restore an earlier version as a NEW one; the history is never rewritten.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "scenes": { "additionalProperties": {}, "description": "Which picture fills which slot.", "properties": {}, "type": "object" }, "speed": { "exclusiveMinimum": 0, "maximum": 4, "type": "number" }, "style": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "expectedRevisionId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "currentRevisionId": { "type": "string" }, "revision": { "additionalProperties": {}, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "document": { "additionalProperties": {}, "description": "The revision's own document: the scenes, the copy, the music and the timing. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "id": { "type": "string" }, "locks": { "additionalProperties": {}, "description": "The parts of this revision the customer has locked. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, "number": { "type": "number" }, "parentRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "projectId": { "type": "string" }, "restoredFromRevisionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seed": { "type": "number" } }, "required": [ "id", "projectId", "number", "parentRevisionId", "restoredFromRevisionId", "document", "locks", "seed", "createdAt" ], "type": "object" } }, "required": [ "revision", "currentRevisionId" ], "type": "object" } } }, "description": "Rework a project", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `unknown_template` — No such design. The catalogue is at GET /api/v1/catalog/marketing/templates. · `unsupported_format` — That design does not offer that shape. `details.formats` lists what it does. · `unsupported_duration` — That design does not offer that length. `details.durations` lists what it does. · `invalid_revision` — That revision is not valid. `details.errors` says why. · `expected_revision_required` — Name the revision you are changing, so a save cannot land on words you never saw. · `edit_not_understood` — That change was not understood whole, so nothing was changed. `details` says why and what this editor does take." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_version_not_found` — No such version of that website source." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_not_ready` — That source is not ready to be used yet. · `source_unreadable` — That source could not be read. · `missing_required_footage` — That design needs footage this recording does not have. `details.reasons` says which. · `revision_conflict` — That revision is no longer the project's current one. · `export_in_flight` — An export of that project is still running. · `gallery_example` — One of that project's exports is published as a gallery example. · `source_version_mismatch` — That version belongs to a different website source. · `source_kind_mismatch` — That project was not made from this kind of source." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_version_expired` — That version of the website source has been cleaned up. Scan the site again. · `source_expired` — That source is past its retention window. · `source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`campaign_copy_overflow` — Some of those words do not fit the frames they are for. `details.fields` names them. · `campaign_visuals_insufficient` — That design needs more pictures than the source has. `details` says how many and which scenes. · `campaign_logo_aspect_unsupported` — That logo's shape is not one the designs can place. · `campaign_speed_breaks_music_ending` — At that version's saved speed the music would not end with the film. `details.missing` says what to put right. · `campaign_speed_breaks_narration_fit` — At that version's saved speed a spoken line would no longer fit its shot. `details.missing` says what to put right." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Rework a project", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_revisions_create", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] } }, "/marketing/sources": { "get": { "description": "Every website this account has scanned, newest first, as a cursor page. A source the customer deleted is still listed, with `state: \"cancelled\"` — an integration reconciling its own records needs to see that it went rather than find a gap.", "operationId": "marketing.sources.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "currentVersion": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "internalStatus": { "type": "string" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "state", "internalStatus", "errorCode", "currentVersion", "createdAt", "expiresAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's website sources", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "The account's website sources", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_sources_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] }, "post": { "description": "Read a public website and keep what it found — the pages, the words and the pictures — as a versioned manifest a marketing video can be built from. Scanning costs no video time; the EXPORT is what charges. Answers 202 with a `Location` pointing at the source; poll it until `state` is terminal, then `marketing.generations.create` to turn it into a project. One scan at a time per account.", "operationId": "marketing.sources.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "demo": { "additionalProperties": {}, "description": "A demo account to sign in with, so the scan can see pages behind a login: { loginUrl, username, password, targetUrls[] }. Encrypted at rest and deleted after the scan.", "properties": {}, "type": "object" }, "url": { "description": "The website to read. Public addresses only.", "maxLength": 4096, "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "dispatched": { "description": "Whether the job has started. False means it is accepted and will start shortly; it is not a failure.", "type": "boolean" }, "operationId": { "description": "The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.", "type": "string" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "operationId", "dispatched", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "dispatched": { "description": "Whether the job has started. False means it is accepted and will start shortly; it is not a failure.", "type": "boolean" }, "operationId": { "description": "The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.", "type": "string" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "operationId", "dispatched", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this marketing.source_scan, e.g. `/api/v1/marketing/sources/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `url_malformed` — That address could not be read as a URL. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `source_refresh_url_mismatch` — A refresh must name the same address the source was created with. · `website_demo_invalid` — That demo login is not valid. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_owner_not_found` — No such account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_inspection_busy` — A scan is already running on this account. Wait for it, or cancel it. · `source_idempotency_conflict` — That idempotency key was already used with a different scan. · `source_owner_unavailable` — That account cannot start new work. · `source_export_in_flight` — An export is still being cut from that source. Cancel it first. · `source_inspection_stopping` — That scan is still stopping. Try again in a moment." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Scan a website", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "marketing.source_scan", "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_sources_create", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/marketing/sources/{id}": { "delete": { "description": "Remove a source, every manifest version it published and every still it kept. The row survives as `state: \"cancelled\"` so an integration reconciling its own records sees that it went rather than finding a gap. Refused with 409 while an export is still being cut from one of its versions — cancel that first.", "operationId": "marketing.sources.delete", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "Delete a website source", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `url_malformed` — That address could not be read as a URL. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `source_refresh_url_mismatch` — A refresh must name the same address the source was created with. · `website_demo_invalid` — That demo login is not valid. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_owner_not_found` — No such account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_inspection_busy` — A scan is already running on this account. Wait for it, or cancel it. · `source_idempotency_conflict` — That idempotency key was already used with a different scan. · `source_owner_unavailable` — That account cannot start new work. · `source_export_in_flight` — An export is still being cut from that source. Cancel it first. · `source_inspection_stopping` — That scan is still stopping. Try again in a moment." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_deleted` — That source has been deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Delete a website source", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_sources_delete", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] }, "get": { "description": "A scanned website: its state, the version number of the manifest that is current, and — once the scan has succeeded — the manifest itself: the pages, the copy and the pictures a website design can be built from. Ask for an older `version` to read what a previous scan found.", "operationId": "marketing.sources.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "description": "An earlier manifest version. Defaults to the current one.", "in": "query", "name": "version", "required": false, "schema": { "exclusiveMinimum": 0, "maximum": 100000, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "brandDefault": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name a video of this site signs with when nobody types one." }, "brandDefaultSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manifest": { "anyOf": [ { "additionalProperties": {}, "description": "The scan's pages, copy and pictures. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "manifestHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "currentVersion": { "type": "number" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "internalStatus": { "type": "string" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "state", "internalStatus", "errorCode", "currentVersion", "createdAt", "expiresAt" ], "type": "object" } }, "required": [ "source", "manifestHash", "brandDefault", "brandDefaultSource", "manifest" ], "type": "object" } } }, "description": "One website source", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:read" ] }, { "DashboardSession": [] } ], "summary": "One website source", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "marketing_sources_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "marketing:read" ] } }, "/marketing/sources/{id}/cancel": { "post": { "description": "Stop whatever scan of this source is queued or running. The source itself stays: if it had already published a manifest it goes back to `succeeded` with that manifest current, and if it had not it is `failed`. Answers how many scan attempts were stopped — zero is not an error, it means nothing was running.", "operationId": "marketing.sources.cancel", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cancelled": { "type": "number" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "cancelled", "resource" ], "type": "object" } } }, "description": "Stop a scan", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `url_malformed` — That address could not be read as a URL. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `source_refresh_url_mismatch` — A refresh must name the same address the source was created with. · `website_demo_invalid` — That demo login is not valid. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_owner_not_found` — No such account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_inspection_busy` — A scan is already running on this account. Wait for it, or cancel it. · `source_idempotency_conflict` — That idempotency key was already used with a different scan. · `source_owner_unavailable` — That account cannot start new work. · `source_export_in_flight` — An export is still being cut from that source. Cancel it first. · `source_inspection_stopping` — That scan is still stopping. Try again in a moment." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_deleted` — That source has been deleted." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Stop a scan", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_sources_cancel", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "marketing:write" ] } }, "/marketing/sources/{id}/refresh": { "post": { "description": "Read the same website again and publish a new manifest version beside the old ones. Projects already made keep the version they were built from; only new work sees the new one. The address must be the one the source was created with — a refresh that pointed somewhere else would silently replace a customer's site with a different one. Answers 202 with a `Location`; poll `marketing.sources.get` until `state` is terminal.", "operationId": "marketing.sources.refresh", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "demo": { "additionalProperties": {}, "properties": {}, "type": "object" }, "url": { "description": "The same address the source was created with.", "maxLength": 4096, "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "dispatched": { "description": "Whether the job has started. False means it is accepted and will start shortly; it is not a failure.", "type": "boolean" }, "operationId": { "description": "The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.", "type": "string" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "operationId", "dispatched", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "dispatched": { "description": "Whether the job has started. False means it is accepted and will start shortly; it is not a failure.", "type": "boolean" }, "operationId": { "description": "The scan attempt. Poll the SOURCE, not this: a source has many scans and one current manifest.", "type": "string" }, "resource": { "additionalProperties": {}, "properties": {}, "type": "object" } }, "required": [ "resource", "operationId", "dispatched", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this marketing.source_scan, e.g. `/api/v1/marketing/sources/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `url_malformed` — That address could not be read as a URL. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `source_refresh_url_mismatch` — A refresh must name the same address the source was created with. · `website_demo_invalid` — That demo login is not valid. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `source_not_found` — No such source. · `source_owner_not_found` — No such account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `source_inspection_busy` — A scan is already running on this account. Wait for it, or cancel it. · `source_idempotency_conflict` — That idempotency key was already used with a different scan. · `source_owner_unavailable` — That account cannot start new work. · `source_export_in_flight` — An export is still being cut from that source. Cancel it first. · `source_inspection_stopping` — That scan is still stopping. Try again in a moment." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`source_deleted` — That source has been deleted." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "marketing:write" ] }, { "DashboardSession": [] } ], "summary": "Scan a website again", "tags": [ "marketing" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "marketing.source_scan", "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "marketing_sources_refresh", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "marketing:write" ] } }, "/renders": { "get": { "description": "Every render this account owns, newest first, as a cursor page. A page only ever contains this account's renders. Walk it by passing the previous page's `nextCursor`; a null `nextCursor` is the end.", "operationId": "renders.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "internalStatus": { "type": "string" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "type": "number" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE RENDER HAS GOT, as last reported. Null once the render is terminal and null while nothing has been recorded. Draw the percent as it is: nothing here is interpolated." }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "steps": { "anyOf": [ { "additionalProperties": false, "properties": { "completed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "planned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "completed", "planned" ], "type": "object" }, { "type": "null" } ] }, "targetOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "watermark": { "type": "boolean" } }, "required": [ "id", "state", "internalStatus", "targetOrigin", "targetPath", "hint", "steps", "durationSeconds", "progress", "failureCode", "watermark", "secondsReserved", "secondsCharged", "createdAt", "finishedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's renders", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "The account's renders", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "renders_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] }, "post": { "description": "Work through a live website and turn the recording into a narrated video. Time is RESERVED when it is queued and settled at the finished file's measured length; a failed or cancelled render is charged nothing. This is the tool that records; `renders.quote` prices the same options and starts nothing. Answers 202 with a `Location`; poll until `state` is terminal, then `renders.download`. At most three renders in flight per account.", "operationId": "renders.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "background": { "description": "What sits around the recording: `studio` (the default) puts the whole window on a quiet backdrop, `none` lets it fill the frame. Ids from catalog.renderOptions.", "maxLength": 64, "type": "string" }, "captionStyle": { "description": "How burned-in captions look, as an id from `catalog.renderOptions.captionStyles`. It only reaches the frame on a look template that burns captions (`captioned`); on any other template the choice is recorded and nothing is drawn. Omit for the catalogue default.", "maxLength": 64, "type": "string" }, "capture": { "description": "The shape of the recording: a computer window or a phone view.", "maxLength": 64, "type": "string" }, "credentials": { "additionalProperties": false, "description": "A demo account to sign in with, and the page it signs in on. Encrypted, used for this render, then deleted.", "properties": { "additionalLoginOrigins": { "description": "Other exact https origins this account's sign-in may pass through, e.g. [\"https://login.example.com\"] for a single sign-on provider on its own host. At most 5. Nothing else — not a redirect, a link or a sibling subdomain — is ever approved on its own: a sign-in that moves to an origin not listed here stops before the account is typed. Ordinary same-origin sign-ins need none.", "items": { "maxLength": 2000, "type": "string" }, "maxItems": 5, "type": "array" }, "loginUrl": { "description": "REQUIRED whenever credentials are given: the page this demo account signs in on, e.g. https://app.example.com/login. Any origin — a product commonly signs in on a different host from its marketing site, and this is what tells the run where the app itself lives. Must be https; checked by the same guard as the site address. Its origin is the only place the account is typed unless `additionalLoginOrigins` names others.", "maxLength": 2000, "type": "string" }, "password": { "maxLength": 200, "minLength": 1, "type": "string" }, "username": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "username", "password", "loginUrl" ], "type": "object" }, "hint": { "description": "What to show, in a sentence: \"show the invoice creation flow\".", "maxLength": 1000, "minLength": 3, "type": "string" }, "language": { "maxLength": 16, "type": "string" }, "maxSeconds": { "description": "The ceiling an Auto video may grow to, 1–600 seconds.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "orientation": { "maxLength": 64, "type": "string" }, "targetSeconds": { "description": "A fixed length, 1–600 seconds. Omit for Auto, which sizes itself to what it finds and is capped by `maxSeconds`.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "templateId": { "description": "A saved or system template id from catalog.renderOptions.", "maxLength": 64, "type": "string" }, "url": { "description": "The page to start from. Public addresses only; a private or link-local address is refused.", "maxLength": 4096, "type": "string" }, "voiceId": { "maxLength": 64, "type": "string" } }, "required": [ "url", "hint" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this walkthrough.render, e.g. `/api/v1/renders/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `login_url_invalid` — That login page address is not one this API will fetch. · `login_url_required` — Credentials need the address of the page they sign in on. · `login_origins_invalid` — Additional sign-in addresses must be a short list of https addresses this API will fetch. · `idempotency_key_unscoped` — An idempotency key needs an account to belong to. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_in_flight` — Too many operations are already running on this account." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`queue_unavailable` — That work cannot be queued right now. Try again shortly. · `vault_unavailable` — Credentials cannot be stored right now. Try again shortly. · `wallet_unavailable` — Video time cannot be reserved right now. Try again shortly." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Make a walkthrough video from a URL", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "walkthrough.render", "x-audit": null, "x-idempotent": true, "x-kind": "charge", "x-mcp-tool": "renders_create", "x-rate-class": "charge", "x-rate-per-minute": 20, "x-scopes": [ "renders:write" ] } }, "/renders/quote": { "post": { "description": "How many seconds a render of these OPTIONS would reserve, whether it would carry the free-tier watermark, and what the account has available — creating nothing and spending nothing. It prices the options only: there is no `url` field and the address does not change the price, so this is not the tool that records anything. A POST because the options are a body, not a query string; it is a read, safe to call as often as you like.", "operationId": "renders.quote", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "background": { "maxLength": 64, "type": "string" }, "captionStyle": { "maxLength": 64, "type": "string" }, "capture": { "maxLength": 64, "type": "string" }, "language": { "maxLength": 16, "type": "string" }, "maxSeconds": { "description": "The ceiling an Auto render may grow to, 1–600 seconds.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "orientation": { "maxLength": 64, "type": "string" }, "targetSeconds": { "description": "A fixed length, 1–600 seconds. Omit for Auto, which sizes itself and is capped by `maxSeconds`.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "templateId": { "maxLength": 64, "type": "string" }, "voiceId": { "maxLength": 64, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "availableSeconds": { "type": "number" }, "capped": { "description": "True when the length asked for was reduced to fit the balance or the free-tier ceiling.", "type": "boolean" }, "maxSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "needed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsToReserve": { "description": "What `renders.create` would hold. Zero means nothing would be held (the free tier).", "type": "number" }, "sufficient": { "description": "False when the balance would refuse the render; `needed` says what it would take.", "type": "boolean" }, "targetSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "watermark": { "description": "Whether the video would carry the free-tier mark.", "type": "boolean" } }, "required": [ "secondsToReserve", "watermark", "capped", "targetSeconds", "maxSeconds", "sufficient", "needed", "availableSeconds" ], "type": "object" } } }, "description": "What a render would cost", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "What a render would cost", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "renders_quote", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] } }, "/renders/{id}": { "get": { "description": "The state of one render, as the standard job envelope: `state` is one of queued/running/succeeded/failed/cancelled whatever its finer-grained status, `progress` is the current step and whole percent while it runs, `cost` says what it held and what it was charged, and `pollAfterMs` says how long to wait before asking again. The video itself is not here — ask `renders.download` for a link.", "operationId": "renders.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "render": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "render" ], "type": "object" } } }, "description": "One render", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "One render", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "renders_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] } }, "/renders/{id}/cancel": { "post": { "description": "Stop a render and get the time back. A render that has not started is cancelled at once; one that is running stops at its next checkpoint, so it can take up to a minute of work to notice. Either way the reservation is RELEASED and nothing is charged: `cost.secondsCharged` is 0 and the balance is whole. A render that has already finished, failed or been cancelled is 409 `already_settled`, and nothing changes.", "operationId": "renders.cancel", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "released": { "description": "Whether a reservation was handed back. False for a render that held nothing.", "type": "boolean" }, "removedFromQueue": { "description": "Whether the render was cancelled before it started.", "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "released", "removedFromQueue" ], "type": "object" } } }, "description": "Stop a render", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `already_settled` — That operation has already finished." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Stop a render", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "renders_cancel", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "renders:write" ] } }, "/renders/{id}/download": { "get": { "description": "A short-lived signed URL for a finished render's MP4, and when it stops working. The bytes are never proxied through this API: fetch the URL directly. Requires a verified email address — an anonymous render is free to make and costs an email to keep.", "operationId": "renders.download", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "description": "When the URL stops working.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "A signed URL. Short-lived, single-purpose, and not shareable.", "type": "string" } }, "required": [ "url", "expiresAt" ], "type": "object" } } }, "description": "A link to the finished video", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_ready` — That video is not finished yet." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "A link to the finished video", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "renders_download", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] } }, "/storyboards": { "get": { "description": "Every storyboard this account owns, newest first, as a cursor page. Unlike the dashboard's own list — which shows only the last day's work in progress — this one walks the whole history, because an integration reconciling its own records needs all of it.", "operationId": "storyboards.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "appEntryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the walkthrough was actually recorded, when a sign-in proved the app is not at `targetOrigin` — a product at app.example.com for a site at example.com. Null means the two are the same place." }, "beatCount": { "type": "number" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "internalStatus": { "type": "string" }, "lengthAdjusted": { "description": "Whether this plan came back shorter than the request asked for, because the chosen length could not hold every step. `storyboards.get` carries the numbers and the sentence in `lengthFit`.", "type": "boolean" }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "type": "number" }, "stage": { "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE PLANNING HAS GOT, as last reported. Null once the storyboard is terminal and null while nothing has been recorded. Draw the percent as it is: nothing here is interpolated." }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" }, "targetOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "state", "internalStatus", "title", "targetOrigin", "targetPath", "appEntryUrl", "hint", "beatCount", "lengthAdjusted", "progress", "createdAt", "expiresAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's storyboards", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "storyboards:read" ] }, { "DashboardSession": [] } ], "summary": "The account's storyboards", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "storyboards_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "storyboards:read" ] }, "post": { "description": "Open a live website, work out how to show what the hint asks for, and prove every step by doing it. The result is a storyboard: beats with a screenshot each, which `renders.createFromStoryboard` turns into a video. PLANNING IS FREE and holds no video time, but an account must still afford the shortest video the plan could become. Steps are budgeted from the length; `lengthFit.adjusted` says when the plan was cut to fit. Answers 202 with a `Location`; poll until `state` is terminal. One plan at a time per account.", "operationId": "storyboards.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "background": { "description": "What sits around the recording: `studio` (the default) puts the whole window on a quiet backdrop, `none` lets it fill the frame. Ids from catalog.renderOptions.", "maxLength": 64, "type": "string" }, "captionStyle": { "description": "How burned-in captions look, as an id from `catalog.renderOptions.captionStyles`. It only reaches the frame on a look template that burns captions (`captioned`); on any other template the choice is recorded and nothing is drawn. Omit for the catalogue default.", "maxLength": 64, "type": "string" }, "capture": { "description": "The shape of the recording: a computer window or a phone view.", "maxLength": 64, "type": "string" }, "credentials": { "additionalProperties": false, "description": "A demo account to sign in with, and the page it signs in on. Kept encrypted for this storyboard's session, so its render can sign in again, and deleted at most two hours after their last use.", "properties": { "additionalLoginOrigins": { "description": "Other exact https origins this account's sign-in may pass through, e.g. [\"https://login.example.com\"] for a single sign-on provider on its own host. At most 5. Nothing else — not a redirect, a link or a sibling subdomain — is ever approved on its own: a sign-in that moves to an origin not listed here stops before the account is typed. Ordinary same-origin sign-ins need none.", "items": { "maxLength": 2000, "type": "string" }, "maxItems": 5, "type": "array" }, "loginUrl": { "description": "REQUIRED whenever credentials are given: the page this demo account signs in on, e.g. https://app.example.com/login. Any origin — a product commonly signs in on a different host from its marketing site, and this is what tells the run where the app itself lives. Must be https; checked by the same guard as the site address. Its origin is the only place the account is typed unless `additionalLoginOrigins` names others.", "maxLength": 2000, "type": "string" }, "password": { "maxLength": 200, "minLength": 1, "type": "string" }, "username": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "username", "password", "loginUrl" ], "type": "object" }, "hint": { "description": "What to show, in a sentence: \"show the invoice creation flow\". \"demo my app\" produces a demo of nothing in particular.", "maxLength": 1000, "minLength": 3, "type": "string" }, "language": { "maxLength": 16, "type": "string" }, "maxSeconds": { "description": "The ceiling an Auto video may grow to, 1–600 seconds.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "orientation": { "maxLength": 64, "type": "string" }, "targetSeconds": { "description": "A fixed length, 1–600 seconds. Omit for Auto, which sizes itself to what it finds and is capped by `maxSeconds`.", "exclusiveMinimum": 0, "maximum": 600, "type": "integer" }, "templateId": { "description": "A saved or system template id from catalog.renderOptions.", "maxLength": 64, "type": "string" }, "url": { "description": "The page to start from. Public addresses only; a private or link-local address is refused.", "maxLength": 4096, "type": "string" }, "voiceId": { "maxLength": 64, "type": "string" } }, "required": [ "url", "hint" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this walkthrough.storyboard, e.g. `/api/v1/storyboards/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `login_url_invalid` — That login page address is not one this API will fetch. · `login_url_required` — Credentials need the address of the page they sign in on. · `login_origins_invalid` — Additional sign-in addresses must be a short list of https addresses this API will fetch. · `idempotency_key_unscoped` — An idempotency key needs an account to belong to. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `storyboard_in_flight` — There is already a plan being made on this account. Wait for it, or cancel it." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly. · `anon_lifetime_cap` — That session has planned as many videos as it may. · `origin_daily_cap` — That website has been planned as many times today as it may be." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`budget_exhausted` — Planning is paused for today. Try again tomorrow. · `abuse_check_unavailable` — Planning is temporarily unavailable. · `queue_unavailable` — That work cannot be queued right now. Try again shortly. · `vault_unavailable` — Credentials cannot be stored right now. Try again shortly." } }, "security": [ { "ApiKey": [ "storyboards:write" ] }, { "DashboardSession": [] } ], "summary": "Plan a walkthrough", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "walkthrough.storyboard", "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "storyboards_create", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "storyboards:write" ] } }, "/storyboards/hint/improve": { "post": { "description": "Rewrite what a person wrote about the video they want into the form that plans most reliably: the pages and actions named in the order they should be shown, in concrete nouns. IT ADDS NOTHING — a feature, page, value or step the caller did not mention is never introduced, and none they did is dropped; the app's `url` only lets it use the product's real names. Bounded by the 1000 characters `storyboards.create` takes; `changed` is false when the words already read that way. Nothing is created, spent or stored.", "operationId": "storyboards.improveHint", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hint": { "description": "What the person wrote; the same field `storyboards.create` takes as `hint`.", "maxLength": 1000, "minLength": 3, "type": "string" }, "url": { "description": "Optional. Its landing page is read so the rewrite can use the product's own screen names. Public addresses only.", "maxLength": 4096, "type": "string" } }, "required": [ "hint" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "changed": { "description": "False when the rewrite is the text that was sent.", "type": "boolean" }, "hint": { "description": "The rewritten brief, ready to send as `storyboards.create`'s `hint`.", "type": "string" } }, "required": [ "hint", "changed" ], "type": "object" } } }, "description": "Rewrite a brief into a clearer plan request", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `url_scheme` — Only http and https addresses can be fetched. · `url_credentials` — Remove the username and password from the address. Use the credentials field instead. · `url_bare_host` — Use a full public hostname, for example https://example.com. · `url_dns` — That hostname could not be resolved. Check it is public and spelled correctly. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`hint_improve_failed` — That description could not be rewritten just now. The words you sent are unchanged." } }, "security": [ { "ApiKey": [ "storyboards:write" ] }, { "DashboardSession": [] } ], "summary": "Rewrite a brief into a clearer plan request", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "storyboards_improveHint", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "storyboards:write" ] } }, "/storyboards/suggestions": { "post": { "description": "Read the app's own landing page and answer five concrete briefs a demo video of it could be made from — the sort of sentence `storyboards.create` takes as its `hint` (\"Show how an invoice is created and sent\"), grounded in what the page really says. Nothing is created or spent, and the answer is cached for a day per site. If the site cannot be read or no suggestions can be made, the list is empty and `reason` says why, never an error: write your own hint when there are none. The page's words are data, not instructions.", "operationId": "storyboards.suggest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "url": { "description": "The app's address, as `storyboards.create` takes it. Public only: a private or link-local address is refused by name and never fetched.", "maxLength": 4096, "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cached": { "description": "True when this came from the day-long cache for this site.", "type": "boolean" }, "reason": { "anyOf": [ { "enum": [ "site_unreadable", "site_empty", "model_unavailable", "model_unusable" ], "type": "string" }, { "type": "null" } ], "description": "Why the list is empty; null when it is not." }, "suggestions": { "description": "Up to five briefs, most obvious first. Empty when `reason` says why.", "items": { "type": "string" }, "type": "array" } }, "required": [ "suggestions", "reason", "cached" ], "type": "object" } } }, "description": "Five things to show", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `url_scheme` — Only http and https addresses can be fetched. · `url_credentials` — Remove the username and password from the address. Use the credentials field instead. · `url_bare_host` — Use a full public hostname, for example https://example.com. · `url_dns` — That hostname could not be resolved. Check it is public and spelled correctly. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "storyboards:write" ] }, { "DashboardSession": [] } ], "summary": "Five things to show", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "storyboards_suggest", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "storyboards:write" ] } }, "/storyboards/{id}": { "get": { "description": "The plan a render can be made from: the job envelope (`state`, `pollAfterMs`, and `progress`, the current step and whole percent while it plans), the beats with a short-lived screenshot URL each, the steps the run could not resolve, the hint-coverage report — what the hint asked for that the beats do not show — and `lengthFit`, what the chosen length did to the plan. Poll until `state` is terminal, then read `beats`.", "operationId": "storyboards.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "appEntryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the walkthrough was actually recorded, when a sign-in proved the app is not at `targetOrigin` — a product at app.example.com for a site at example.com. Null means the two are the same place." }, "beats": { "items": { "additionalProperties": {}, "properties": { "beatId": { "type": "string" }, "narration": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screenshotUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "type": "array" }, "coverage": { "additionalProperties": false, "properties": { "uncovered": { "description": "What the hint asked for that the beats do not show.", "items": { "type": "string" }, "type": "array" }, "wider": { "description": "Pages wider than the recording viewport, clipped at the right edge on camera.", "items": { "additionalProperties": {}, "properties": {}, "type": "object" }, "type": "array" } }, "required": [ "uncovered", "wider" ], "type": "object" }, "credentialsHeld": { "description": "Whether the session credential the run used is still held server-side. The credential itself never leaves the server.", "type": "boolean" }, "hadCredentials": { "type": "boolean" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthFit": { "anyOf": [ { "additionalProperties": false, "properties": { "adjusted": { "description": "Whether the plan is shorter than the request asked for — steps trimmed, or the length's step budget used up with objectives still open. Plan again at a longer length to get the rest; planning is free.", "type": "boolean" }, "beatBudget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The steps that length can hold. An Auto plan derives it from `seconds`; a fixed length takes its own preset's." }, "beatsDropped": { "description": "Steps trimmed off the end because the length could not hold them.", "type": "number" }, "beatsKept": { "description": "Steps in `beats`, which is what the render will show.", "type": "number" }, "beatsPlanned": { "description": "Steps the run proved, before anything was trimmed.", "type": "number" }, "maxSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The ceiling an Auto plan was budgeted against, or null when a fixed length was chosen." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The sentence to show the customer, e.g. \"Plan adjusted to fit 60 seconds: 10 of 13 steps kept.\" Null when nothing was adjusted." }, "plannedSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "What the kept steps are worth in seconds — what the video will run to, before the read is measured." }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The length everything below was decided from: the fixed length, or the Auto ceiling." }, "targetSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The fixed length this plan was made for, or null when it was planned as Auto." } }, "required": [ "targetSeconds", "maxSeconds", "seconds", "plannedSeconds", "beatBudget", "beatsPlanned", "beatsKept", "beatsDropped", "adjusted", "note" ], "type": "object" }, { "type": "null" } ], "description": "WHAT THE PLAN DID ABOUT THE LENGTH. Null for a storyboard planned before this record existed, which is not the same as `adjusted: false`." }, "storyboard": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" }, "stuckSteps": { "items": { "additionalProperties": {}, "properties": {}, "type": "object" }, "type": "array" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "storyboard", "title", "summary", "hint", "targetOrigin", "targetPath", "appEntryUrl", "hadCredentials", "credentialsHeld", "beats", "stuckSteps", "coverage", "lengthFit" ], "type": "object" } } }, "description": "One storyboard", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "storyboards:read" ] }, { "DashboardSession": [] } ], "summary": "One storyboard", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "storyboards_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "storyboards:read" ] } }, "/storyboards/{id}/cancel": { "post": { "description": "Stop planning. A storyboard that has not started is cancelled at once; one that is running stops at its next step boundary, which is a few seconds. Planning holds no video time, so nothing is refunded — there was nothing to refund. A storyboard that has already finished, failed or been cancelled is 409 `already_settled`, and nothing changes.", "operationId": "storyboards.cancel", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "removedFromQueue": { "type": "boolean" }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "removedFromQueue" ], "type": "object" } } }, "description": "Stop a storyboard", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `already_settled` — That operation has already finished." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "storyboards:write" ] }, { "DashboardSession": [] } ], "summary": "Stop a storyboard", "tags": [ "storyboards" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "storyboards_cancel", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "storyboards:write" ] } }, "/storyboards/{id}/renders": { "post": { "description": "Turn a finished storyboard into a video: the beats it proved, in order, with the words you approve. Each beat may have its narration rewritten or be hidden altogether; everything else about a beat — what it clicks, where it goes, what it types — is the plan's own and is not accepted from a caller. The render inherits the storyboard's options, so the video matches what was planned. Answers 202 with a `Location`; the cost and the settlement are `renders.create`'s.", "operationId": "renders.createFromStoryboard", "parameters": [ { "description": "The storyboard to render.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "beats": { "description": "The beats to keep and what they say. Absent renders the plan as it stands.", "items": { "additionalProperties": false, "properties": { "beatId": { "maxLength": 64, "minLength": 1, "type": "string" }, "hidden": { "description": "Leave this beat out of the video.", "type": "boolean" }, "narration": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Replace this beat's line. Null or absent keeps the planned one." } }, "required": [ "beatId" ], "type": "object" }, "maxItems": 60, "type": "array" }, "credentials": { "additionalProperties": false, "description": "Only needed when the storyboard's own session credential has expired. They replace it: kept encrypted for that storyboard's session and deleted at most two hours after their last use.", "properties": { "additionalLoginOrigins": { "description": "Other exact https origins this account's sign-in may pass through, e.g. [\"https://login.example.com\"] for a single sign-on provider on its own host. At most 5. Nothing else — not a redirect, a link or a sibling subdomain — is ever approved on its own: a sign-in that moves to an origin not listed here stops before the account is typed. Ordinary same-origin sign-ins need none.", "items": { "maxLength": 2000, "type": "string" }, "maxItems": 5, "type": "array" }, "loginUrl": { "description": "REQUIRED whenever credentials are given: the page this demo account signs in on, e.g. https://app.example.com/login. Any origin — a product commonly signs in on a different host from its marketing site, and this is what tells the run where the app itself lives. Must be https; checked by the same guard as the site address. Its origin is the only place the account is typed unless `additionalLoginOrigins` names others.", "maxLength": 2000, "type": "string" }, "password": { "maxLength": 200, "minLength": 1, "type": "string" }, "username": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "username", "password", "loginUrl" ], "type": "object" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "credentialSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthFit": { "anyOf": [ { "additionalProperties": false, "properties": { "adjusted": { "description": "Whether this video is shorter than the storyboard's plan. Render at a longer length, or hide beats yourself, to choose what goes.", "type": "boolean" }, "beatBudget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The steps that length can hold." }, "beatsDropped": { "description": "Steps this render leaves out because the length cannot hold them. Taught extras yield their slot first; only then is the walkthrough itself cut, and always off the end.", "type": "number" }, "beatsKept": { "description": "Steps the video will actually show.", "type": "number" }, "beatsPlanned": { "description": "Steps the storyboard offered this render, after your own hidden beats were taken out and any taught steps put back.", "type": "number" }, "cappedFromSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The length asked for, when a shorter one was used instead. Null on this operation." }, "maxSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The ceiling an Auto render is sized against, or null when a fixed length was chosen." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The sentence to show, e.g. \"Plan adjusted to fit 60 seconds: 10 of 13 steps kept.\" Null when nothing was adjusted." }, "plannedSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "What the kept steps are worth in seconds — what the video will run to, before the read is measured." }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The length everything below was decided from: the fixed length, or the Auto ceiling." }, "targetSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The fixed length this render holds, or null when the storyboard was planned as Auto." } }, "required": [ "targetSeconds", "maxSeconds", "seconds", "plannedSeconds", "beatBudget", "beatsPlanned", "beatsKept", "beatsDropped", "cappedFromSeconds", "adjusted", "note" ], "type": "object" }, { "type": "null" } ], "description": "WHAT THIS RENDER DID ABOUT THE LENGTH. The storyboard's own `lengthFit` is about the PLAN; this one is about the video just queued, and the two differ exactly when the chosen length cannot hold every beat the plan proved. Null when the storyboard names no length at all, and null on a replayed request, which measured nothing." }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created", "credentialSource", "lengthFit" ], "type": "object" } } }, "description": "The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "credentialSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthFit": { "anyOf": [ { "additionalProperties": false, "properties": { "adjusted": { "description": "Whether this video is shorter than the storyboard's plan. Render at a longer length, or hide beats yourself, to choose what goes.", "type": "boolean" }, "beatBudget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The steps that length can hold." }, "beatsDropped": { "description": "Steps this render leaves out because the length cannot hold them. Taught extras yield their slot first; only then is the walkthrough itself cut, and always off the end.", "type": "number" }, "beatsKept": { "description": "Steps the video will actually show.", "type": "number" }, "beatsPlanned": { "description": "Steps the storyboard offered this render, after your own hidden beats were taken out and any taught steps put back.", "type": "number" }, "cappedFromSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The length asked for, when a shorter one was used instead. Null on this operation." }, "maxSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The ceiling an Auto render is sized against, or null when a fixed length was chosen." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The sentence to show, e.g. \"Plan adjusted to fit 60 seconds: 10 of 13 steps kept.\" Null when nothing was adjusted." }, "plannedSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "What the kept steps are worth in seconds — what the video will run to, before the read is measured." }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The length everything below was decided from: the fixed length, or the Auto ceiling." }, "targetSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The fixed length this render holds, or null when the storyboard was planned as Auto." } }, "required": [ "targetSeconds", "maxSeconds", "seconds", "plannedSeconds", "beatBudget", "beatsPlanned", "beatsKept", "beatsDropped", "cappedFromSeconds", "adjusted", "note" ], "type": "object" }, { "type": "null" } ], "description": "WHAT THIS RENDER DID ABOUT THE LENGTH. The storyboard's own `lengthFit` is about the PLAN; this one is about the video just queued, and the two differ exactly when the chosen length cannot hold every beat the plan proved. Null when the storyboard names no length at all, and null on a replayed request, which measured nothing." }, "resource": { "additionalProperties": false, "properties": { "artifactsExpired": { "description": "The work succeeded but its files were deleted at the end of the retention period.", "type": "boolean" }, "cancellable": { "type": "boolean" }, "cost": { "additionalProperties": false, "properties": { "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secondsReserved": { "type": "number" }, "watermark": { "type": "boolean" } }, "required": [ "secondsReserved", "secondsCharged", "watermark" ], "type": "object" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "additionalProperties": false, "properties": { "code": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable": { "type": "boolean" }, "terminal": { "type": "boolean" } }, "required": [ "code", "reason", "retryable", "terminal" ], "type": "object" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "idempotencyKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "internalStatus": { "description": "A finer-grained status word. Informational; branch on `state`.", "type": "string" }, "kind": { "description": "walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation", "type": "string" }, "pollAfterMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Wait this long before polling again; null once the state is terminal." }, "progress": { "anyOf": [ { "additionalProperties": false, "properties": { "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When it was reported. A reading that has stopped moving means the work has, not that the bar is broken." }, "percent": { "description": "0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.", "type": "number" }, "stage": { "description": "A short label for the current step. Show it; do not branch on it.", "type": "string" } }, "required": [ "stage", "percent", "at" ], "type": "object" }, { "type": "null" } ], "description": "HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw." }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "anyOf": [ { "additionalProperties": false, "properties": { "artifacts": { "items": { "additionalProperties": false, "properties": { "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "url", "expiresAt", "bytes", "sha256" ], "type": "object" }, "type": "array" }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "artifacts", "durationSeconds" ], "type": "object" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "state": { "description": "The five public states. Poll until one of succeeded/failed/cancelled.", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "id", "kind", "state", "internalStatus", "stage", "progress", "error", "result", "cost", "artifactsExpired", "cancellable", "idempotencyKey", "requestId", "createdAt", "startedAt", "finishedAt", "expiresAt", "pollAfterMs" ], "type": "object" } }, "required": [ "resource", "created", "credentialSource", "lengthFit" ], "type": "object" } } }, "description": "The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } }, "Location": { "description": "Where to read this walkthrough.render, e.g. `/api/v1/renders/{id}`. Present on the replay too.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `login_url_invalid` — That login page address is not one this API will fetch. · `login_url_required` — Credentials need the address of the page they sign in on. · `login_origins_invalid` — Additional sign-in addresses must be a short list of https addresses this API will fetch. · `idempotency_key_unscoped` — An idempotency key needs an account to belong to. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use \"Talk to a person\": support can allow a site by name. · `body_invalid` — Those edits are not valid. · `storyboard_empty` — That storyboard has no beats to render. · `unknown_beat` — One of the beats named is not on that storyboard. · `no_beats` — Every beat is hidden. Keep at least one. · `credentials_required` — That storyboard was planned signed in, so rendering it needs the demo credentials again." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`insufficient_seconds` — You do not have enough video time left. Buy more time to keep going." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_in_flight` — Too many operations are already running on this account. · `not_ready` — That video is not finished yet." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storyboard_expired` — That storyboard has expired. Plan it again; planning is free." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`queue_unavailable` — That work cannot be queued right now. Try again shortly. · `vault_unavailable` — Credentials cannot be stored right now. Try again shortly. · `wallet_unavailable` — Video time cannot be reserved right now. Try again shortly." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Make a video from a storyboard you approved", "tags": [ "renders" ], "x-actors": [ "user", "api_key" ], "x-async-kind": "walkthrough.render", "x-audit": null, "x-idempotent": true, "x-kind": "charge", "x-mcp-tool": "renders_createFromStoryboard", "x-rate-class": "charge", "x-rate-per-minute": 20, "x-scopes": [ "renders:write" ] } }, "/templates": { "get": { "description": "Every render template this account has saved, most recently updated first. System templates are not here — `catalog.renderOptions` lists those, and both kinds of id are accepted wherever a `templateId` is taken.", "operationId": "templates.list", "parameters": [ { "description": "How many to return (1–100). Defaults to 100, which is what this list answered before it was paged.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." }, "templates": { "items": { "additionalProperties": false, "properties": { "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captureId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom": { "description": "true for one of this account's saved templates, false for a system template.", "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthPreset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limits": { "anyOf": [ { "additionalProperties": {}, "description": "The engine limits this template pins. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "name": { "type": "string" }, "orientationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "speedFactor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "System templates only: a factor on the voice's own speed." }, "ttsSpeed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceStyle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "System templates only: the delivery the narrator reads in." } }, "required": [ "id", "name", "description", "isDefault", "custom", "limits", "voiceId", "lengthPreset", "orientationId", "captureId", "language", "background", "ttsSpeed" ], "type": "object" }, "type": "array" } }, "required": [ "templates", "nextCursor" ], "type": "object" } } }, "description": "The account's saved render templates", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "The account's saved render templates", "tags": [ "templates" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "templates_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] }, "post": { "description": "Save a set of render settings — the look, the voice, the length, the shape — under a name, so every render after this one can ask for it by id. Nothing here is a lock: a template is a set of DEFAULTS and any render may override any of them. At most 50 per account; the 51st is 409 `template_limit`.", "operationId": "templates.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "maxLength": 300, "type": "string" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "settings": { "additionalProperties": {}, "description": "Omit for a template that pins nothing but its name.", "propertyNames": { "type": "string" }, "type": "object" }, "sourceRenderId": { "description": "A finished render of this account's that these settings were taken from, for your own records. A render id that is not this account's is a 404.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "template": { "additionalProperties": false, "properties": { "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captureId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom": { "description": "true for one of this account's saved templates, false for a system template.", "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthPreset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limits": { "anyOf": [ { "additionalProperties": {}, "description": "The engine limits this template pins. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "name": { "type": "string" }, "orientationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "speedFactor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "System templates only: a factor on the voice's own speed." }, "ttsSpeed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceStyle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "System templates only: the delivery the narrator reads in." } }, "required": [ "id", "name", "description", "isDefault", "custom", "limits", "voiceId", "lengthPreset", "orientationId", "captureId", "language", "background", "ttsSpeed" ], "type": "object" } }, "required": [ "template" ], "type": "object" } } }, "description": "Save a render template", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `name_invalid` — That template name is not valid. · `description_invalid` — That template description is too long. · `settings_invalid` — Those template settings are not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `template_not_found` — No such template. · `source_render_not_found` — No such render on this account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `template_limit` — This account already holds the most templates it may. Delete one to save another." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`service_unavailable` — That service is temporarily unavailable." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Save a render template", "tags": [ "templates" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "templates_create", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "renders:write" ] } }, "/templates/{id}": { "delete": { "description": "Remove one of this account's templates. Renders already made with it are untouched — their settings were fixed when they were created — and a render in flight that named it is unaffected for the same reason. Answers `{ deleted: true }` rather than an empty 204: a body a client can parse is one fewer special case.", "operationId": "templates.delete", "parameters": [ { "description": "The template's id — the `id` a create call answered with, or one from `templates.list`. A template id is not a uuid.", "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "Delete a saved template", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `template_not_found` — No such template." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Delete a saved template", "tags": [ "templates" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "templates_delete", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "renders:write" ] }, "get": { "description": "One template by id: either one this account saved or one of the system templates. A template id belonging to another account answers 404, because ownership is part of the resolution rather than a check after it.", "operationId": "templates.get", "parameters": [ { "description": "The template's id — the `id` a create call answered with, or one from `templates.list`. A template id is not a uuid.", "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "template": { "additionalProperties": false, "properties": { "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captureId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom": { "description": "true for one of this account's saved templates, false for a system template.", "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthPreset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limits": { "anyOf": [ { "additionalProperties": {}, "description": "The engine limits this template pins. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "name": { "type": "string" }, "orientationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "speedFactor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "System templates only: a factor on the voice's own speed." }, "ttsSpeed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceStyle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "System templates only: the delivery the narrator reads in." } }, "required": [ "id", "name", "description", "isDefault", "custom", "limits", "voiceId", "lengthPreset", "orientationId", "captureId", "language", "background", "ttsSpeed" ], "type": "object" } }, "required": [ "template" ], "type": "object" } } }, "description": "One render template", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:read" ] }, { "DashboardSession": [] } ], "summary": "One render template", "tags": [ "templates" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "templates_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "renders:read" ] }, "put": { "description": "Change a template's name, description or settings. Every field is optional and an absent one is left alone; `settings` is replaced WHOLE when it is sent, not merged, so a partial settings object silently drops what it leaves out. A template belonging to another account is 404.", "operationId": "templates.update", "parameters": [ { "description": "The template's id — the `id` a create call answered with, or one from `templates.list`. A template id is not a uuid.", "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "maxLength": 300, "type": "string" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "settings": { "additionalProperties": {}, "description": "The render settings this template pins: limits, voice, length preset, orientation, capture, language, background, voice speed. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "template": { "additionalProperties": false, "properties": { "background": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captureId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom": { "description": "true for one of this account's saved templates, false for a system template.", "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lengthPreset": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limits": { "anyOf": [ { "additionalProperties": {}, "description": "The engine limits this template pins. Open shape, may gain keys; ≤65536 bytes, ≤16 deep.", "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ] }, "name": { "type": "string" }, "orientationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceRenderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "speedFactor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "System templates only: a factor on the voice's own speed." }, "ttsSpeed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceStyle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "System templates only: the delivery the narrator reads in." } }, "required": [ "id", "name", "description", "isDefault", "custom", "limits", "voiceId", "lengthPreset", "orientationId", "captureId", "language", "background", "ttsSpeed" ], "type": "object" } }, "required": [ "template" ], "type": "object" } } }, "description": "Change a saved template", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `name_invalid` — That template name is not valid. · `description_invalid` — That template description is too long. · `settings_invalid` — Those template settings are not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource. · `template_not_found` — No such template. · `source_render_not_found` — No such render on this account." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `template_limit` — This account already holds the most templates it may. Delete one to save another." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "renders:write" ] }, { "DashboardSession": [] } ], "summary": "Change a saved template", "tags": [ "templates" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "templates_update", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "renders:write" ] } }, "/usage": { "get": { "description": "Public API calls over a window, by day and by operation, plus the video time the account spent in the same window. A key sees only its own calls; a signed-in person sees the whole account. Windows are inclusive of `from` and exclusive of `to`, default the last 30 days, and may span at most 92.", "operationId": "usage.get", "parameters": [ { "description": "The start of the window, inclusive. Defaults to 30 days ago.", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" } }, { "description": "The end of the window, exclusive. Defaults to now.", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" } }, { "description": "Which breakdowns to compute. `both` is the default.", "in": "query", "name": "groupBy", "required": false, "schema": { "default": "both", "enum": [ "day", "operation", "both" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "byDay": { "description": "UTC days, ascending. Absent days are absent, not zero.", "items": { "additionalProperties": false, "properties": { "day": { "type": "string" }, "errors": { "type": "number" }, "requests": { "type": "number" } }, "required": [ "day", "requests", "errors" ], "type": "object" }, "type": "array" }, "byOperation": { "description": "Busiest first.", "items": { "additionalProperties": false, "properties": { "errors": { "type": "number" }, "operation": { "type": "string" }, "requests": { "type": "number" } }, "required": [ "operation", "requests", "errors" ], "type": "object" }, "type": "array" }, "details": { "anyOf": [ { "additionalProperties": false, "properties": { "note": { "type": "string" } }, "required": [ "note" ], "type": "object" }, { "type": "null" } ], "description": "Present only when a field above could not be answered, saying which and why." }, "from": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "requests": { "description": "Every public call in the window, whatever it answered.", "type": "number" }, "scope": { "description": "`api_key` when a key asked — it sees only its own calls.", "enum": [ "api_key", "account" ], "type": "string" }, "secondsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video time charged in the window, from the wallet ledger — the only authority on spend. For a signed-in person this is the ACCOUNT's total. For a KEY it is the total of the work THAT KEY created: renders and marketing exports it started, joined to the ledger by the row they were charged against. Work started in the dashboard is not a key's, and one key never sees another's." }, "to": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" } }, "required": [ "from", "to", "scope", "requests", "byDay", "byOperation", "secondsCharged", "details" ], "type": "object" } } }, "description": "What this credential has been doing", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "usage:read" ] }, { "DashboardSession": [] } ], "summary": "What this credential has been doing", "tags": [ "usage" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "usage_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "usage:read" ] } }, "/voices/preview": { "post": { "description": "Synthesise a short sentence in one of the catalogue's voices and answer a short-lived link to the audio. Send your own `text` (up to 300 characters) or omit it for a stock sentence. The same sentence in the same voice is only ever synthesised once, so repeating a preview is free and instant. When somebody else is synthesising this exact preview at this moment the answer is `status: \"preview_pending\"` with no URL — ask again in a second.", "operationId": "voices.preview", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "text": { "description": "The sentence to speak. Omit for a stock one.", "maxLength": 300, "type": "string" }, "voiceId": { "description": "A voice id from catalog.voices.list.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "voiceId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cached": { "description": "True when the audio already existed and nothing was synthesised.", "type": "boolean" }, "expiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "ready", "preview_pending" ], "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A signed link to the audio. Null while the preview is still being made." } }, "required": [ "status", "url", "expiresAt", "cached" ], "type": "object" } } }, "description": "Hear a voice", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`preview_failed` — That preview could not be made. Try again shortly." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`storage_unavailable` — File storage is temporarily unavailable. · `tts_unavailable` — Voice previews are temporarily unavailable." } }, "security": [ { "ApiKey": [ "catalog:read" ] }, { "DashboardSession": [] } ], "summary": "Hear a voice", "tags": [ "voices" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "voices_preview", "x-rate-class": "expensive", "x-rate-per-minute": 20, "x-scopes": [ "catalog:read" ] } }, "/wallet": { "get": { "description": "How many seconds of finished video this account can still make, by bucket: a plan's seconds for the current billing month (which end with the period), top up seconds (which never expire), free seconds, and what is currently held by work in flight. `availableSeconds` is the one number a reservation is judged against.", "operationId": "wallet.get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "wallet": { "additionalProperties": false, "properties": { "availableSeconds": { "description": "What a new render or export may be reserved against, right now.", "type": "number" }, "freeSeconds": { "type": "number" }, "paygSeconds": { "type": "number" }, "planActive": { "type": "boolean" }, "planExpiresAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "planId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "planSeconds": { "type": "number" }, "reservedSeconds": { "type": "number" } }, "required": [ "planSeconds", "planId", "planExpiresAt", "planActive", "paygSeconds", "freeSeconds", "reservedSeconds", "availableSeconds" ], "type": "object" } }, "required": [ "wallet" ], "type": "object" } } }, "description": "The video-time balance", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "wallet:read" ] }, { "DashboardSession": [] } ], "summary": "The video-time balance", "tags": [ "wallet" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "wallet_get", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "wallet:read" ] } }, "/wallet/ledger": { "get": { "description": "Every movement of this account's seconds, newest first: grants, reservations, charges and releases, each with the row it was for. Joined to a render or an export by `refType` + `refId`; the ledger is the record of what was spent, and no other count of seconds is authoritative.", "operationId": "wallet.ledger.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "balanceAfter": { "anyOf": [ { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "The whole wallet as it stood after this row, so a statement reads down the page without re-summing." }, "bucket": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "kind": { "description": "What happened: a grant, a reservation, a charge, a release, an expiry.", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the row is about — `render`, `marketing_export` — and `refId` is that row's id." }, "seconds": { "description": "Signed: negative took time away.", "type": "number" } }, "required": [ "kind", "seconds", "bucket", "refType", "refId", "note", "balanceAfter", "createdAt", "id" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "Where the video time went", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "wallet:read" ] }, { "DashboardSession": [] } ], "summary": "Where the video time went", "tags": [ "wallet" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": null, "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "wallet_ledger_list", "x-rate-class": "read", "x-rate-per-minute": 600, "x-scopes": [ "wallet:read" ] } }, "/webhooks": { "get": { "description": "Every endpoint this account has registered, newest first, active and disabled alike. Signing secrets are never returned.", "operationId": "webhooks.list", "parameters": [ { "description": "How many to return (1–100). Defaults to 100, which is what this list answered before it was paged.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner` when you turned it off, `consecutive_failures` when we did." }, "events": { "description": "The event types this endpoint asked for. Anything not on the list is not sent.", "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "type": "array" }, "failureStreak": { "description": "Consecutive failed deliveries. Any success resets it; at 20 the endpoint is disabled automatically.", "type": "number" }, "id": { "type": "string" }, "lastDeliveryAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "Where the signed POST goes. `https` outside development; the address is re-checked before every delivery.", "type": "string" } }, "required": [ "id", "url", "events", "description", "status", "failureStreak", "disabledAt", "disabledReason", "lastDeliveryAt", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "The account's webhook endpoints", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "The account's webhook endpoints", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "webhooks_list", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] }, "post": { "description": "Register an address to be POSTed to when work finishes, so an integration can stop polling. The signing secret is in the response and nowhere else. The URL is checked at registration AND again before every delivery — https outside development, no username or password, no fragment, no non-default port in production, and every address it resolves to must be public. The connection is then pinned to the address that was checked, and a redirect is refused rather than followed. At most 10 active endpoints per account.", "operationId": "webhooks.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "description": "What this endpoint is for. Shown in the console and in the account's audit trail.", "maxLength": 200, "type": "string" }, "events": { "description": "What to send. At least one; an unknown name is refused rather than ignored, because an endpoint subscribed to a typo would silently never fire.", "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array" }, "url": { "description": "Where to POST. https, a public address, no credentials in the URL.", "maxLength": 2048, "type": "string" } }, "required": [ "url", "events" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "endpoint": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner` when you turned it off, `consecutive_failures` when we did." }, "events": { "description": "The event types this endpoint asked for. Anything not on the list is not sent.", "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "type": "array" }, "failureStreak": { "description": "Consecutive failed deliveries. Any success resets it; at 20 the endpoint is disabled automatically.", "type": "number" }, "id": { "type": "string" }, "lastDeliveryAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "Where the signed POST goes. `https` outside development; the address is re-checked before every delivery.", "type": "string" } }, "required": [ "id", "url", "events", "description", "status", "failureStreak", "disabledAt", "disabledReason", "lastDeliveryAt", "createdAt", "updatedAt" ], "type": "object" }, "secret": { "description": "THE SIGNING SECRET. This is the only time it is returned: it is stored encrypted and is never answered again. Verify every delivery with it — `Gogoscreen-Signature: t=,v1=.\" + raw body)>` — over the RAW request body, and reject a `t` more than five minutes from your clock.", "type": "string" } }, "required": [ "secret", "endpoint" ], "type": "object" } } }, "description": "Register a webhook endpoint", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `webhook_url_invalid` — That webhook URL is not one this API will post to. Use an https URL with no username, password or fragment. · `webhook_url_blocked` — That webhook URL resolves to an address this API will not post to. Point it at a public address. · `webhook_host_denied` — That webhook host is not allowed by this deployment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_endpoints` — This account already has the maximum number of active webhook endpoints. Delete one to add another." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "Register a webhook endpoint", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "webhooks_create", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] } }, "/webhooks/{id}": { "delete": { "description": "Remove an endpoint. Its pending deliveries are marked failed rather than sent: an endpoint that has been deleted must not deliver an hour later. The delivery log goes with it. Deleting an endpoint that is already gone is a 404 — unlike revoking a key, there is no credential here to be sure is dead.", "operationId": "webhooks.delete", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "deleted": { "const": true, "type": "boolean" }, "id": { "type": "string" } }, "required": [ "id", "deleted" ], "type": "object" } } }, "description": "Delete a webhook endpoint", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "webhooks_delete", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] }, "get": { "description": "One endpoint of this account, by id. An endpoint belonging to another account is a 404, never a 403.", "operationId": "webhooks.get", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "endpoint": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner` when you turned it off, `consecutive_failures` when we did." }, "events": { "description": "The event types this endpoint asked for. Anything not on the list is not sent.", "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "type": "array" }, "failureStreak": { "description": "Consecutive failed deliveries. Any success resets it; at 20 the endpoint is disabled automatically.", "type": "number" }, "id": { "type": "string" }, "lastDeliveryAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "Where the signed POST goes. `https` outside development; the address is re-checked before every delivery.", "type": "string" } }, "required": [ "id", "url", "events", "description", "status", "failureStreak", "disabledAt", "disabledReason", "lastDeliveryAt", "createdAt", "updatedAt" ], "type": "object" } }, "required": [ "endpoint" ], "type": "object" } } }, "description": "One webhook endpoint", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "One webhook endpoint", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "webhooks_get", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] }, "patch": { "description": "Change where an endpoint points, what it is sent, what it is called, or whether it is on. A new URL is fenced exactly as a new registration is. Setting `status` back to `active` clears the failure streak — leaving it at 20 would switch the endpoint off again on its next failure, whatever was fixed. The signing secret does not change and is not returned; to change it, delete the endpoint and register another.", "operationId": "webhooks.update", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ] }, "events": { "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array" }, "status": { "description": "`disabled` stops delivery and marks every pending delivery failed; `active` turns it back on and clears the streak.", "enum": [ "active", "disabled" ], "type": "string" }, "url": { "maxLength": 2048, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "endpoint": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`owner` when you turned it off, `consecutive_failures` when we did." }, "events": { "description": "The event types this endpoint asked for. Anything not on the list is not sent.", "items": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "type": "array" }, "failureStreak": { "description": "Consecutive failed deliveries. Any success resets it; at 20 the endpoint is disabled automatically.", "type": "number" }, "id": { "type": "string" }, "lastDeliveryAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "url": { "description": "Where the signed POST goes. `https` outside development; the address is re-checked before every delivery.", "type": "string" } }, "required": [ "id", "url", "events", "description", "status", "failureStreak", "disabledAt", "disabledReason", "lastDeliveryAt", "createdAt", "updatedAt" ], "type": "object" } }, "required": [ "endpoint" ], "type": "object" } } }, "description": "Change a webhook endpoint", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `webhook_url_invalid` — That webhook URL is not one this API will post to. Use an https URL with no username, password or fragment. · `webhook_url_blocked` — That webhook URL resolves to an address this API will not post to. Point it at a public address. · `webhook_host_denied` — That webhook host is not allowed by this deployment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_endpoints` — This account already has the maximum number of active webhook endpoints. Delete one to add another." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`payload_too_large` — That request body is too large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unsupported_media_type` — That content type is not supported." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "Change a webhook endpoint", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "webhooks_update", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] } }, "/webhooks/{id}/deliveries": { "get": { "description": "Every delivery attempted to this endpoint, newest first: which event, how many attempts, what the receiver answered and how long it took. There is no retry operation — delivery is at-least-once with six automatic attempts, and a seventh on demand would be a different promise from the one the signature headers make.", "operationId": "webhooks.deliveries.list", "parameters": [ { "description": "How many rows to return (1–100).", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "The `nextCursor` of the previous page. Opaque: do not build one.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "attempt": { "description": "How many times this delivery has been tried. Six at most.", "type": "number" }, "createdAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, "deliveredAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "endpointId": { "type": "string" }, "eventId": { "description": "Also sent as the `Gogoscreen-Event-Id` header. Dedupe on it: delivery is at-least-once.", "type": "string" }, "eventType": { "enum": [ "storyboard.succeeded", "storyboard.failed", "storyboard.cancelled", "render.succeeded", "render.failed", "render.cancelled", "marketing.source.succeeded", "marketing.source.failed", "marketing.source.cancelled", "marketing.generation.succeeded", "marketing.generation.failed", "marketing.generation.cancelled", "marketing.export.succeeded", "marketing.export.failed", "marketing.export.cancelled", "webhook.test" ], "type": "string" }, "id": { "type": "string" }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A status line or an error code. Never a response body beyond 256 characters." }, "nextAttemptAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "responseMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "responseStatus": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "description": "`exhausted` means all six attempts failed; `failed` means we stopped trying because the endpoint was switched off under it.", "enum": [ "pending", "succeeded", "failed", "exhausted" ], "type": "string" }, "updatedAt": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" } }, "required": [ "id", "endpointId", "eventId", "eventType", "attempt", "status", "responseStatus", "responseMs", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "One endpoint's delivery log", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `invalid_cursor` — That page cursor is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "One endpoint's delivery log", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": false, "x-kind": "read", "x-mcp-tool": "webhooks_deliveries_list", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] } }, "/webhooks/{id}/test": { "post": { "description": "Queue a `webhook.test` event to this endpoint: a real signed delivery through the same path live events use, so what it proves is what production will do. The answer is 202 and the delivery's id — the delivery itself has not happened yet. Read its outcome from the endpoint's delivery log.", "operationId": "webhooks.test", "parameters": [ { "description": "The resource `id`, from a create answer or the matching list.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "deliveryId": { "description": "Look this up in `GET /webhooks/{id}/deliveries` to see what the receiver answered.", "type": "string" }, "eventId": { "description": "Sent as `Gogoscreen-Event-Id`.", "type": "string" } }, "required": [ "deliveryId", "eventId" ], "type": "object" } } }, "description": "Send a test delivery", "headers": { "Cache-Control": { "description": "Always `private, no-store`.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "Present only when this answer was stored by an earlier call with the same Idempotency-Key. Nothing new was done.", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`unauthorized` — Authentication is required." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`not_found` — No such resource." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `webhook_endpoint_disabled` — That webhook endpoint is disabled. Re-enable it before sending to it." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`rate_limited` — Too many requests. Try again shortly." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "`internal_error` — Something went wrong. Try again." } }, "security": [ { "ApiKey": [ "webhooks:manage" ] }, { "DashboardSession": [] } ], "summary": "Send a test delivery", "tags": [ "webhooks" ], "x-actors": [ "user", "api_key" ], "x-async-kind": null, "x-audit": "webhook_management", "x-idempotent": true, "x-kind": "write", "x-mcp-tool": "webhooks_test", "x-rate-class": "write", "x-rate-per-minute": 120, "x-scopes": [ "webhooks:manage" ] } } }, "servers": [ { "url": "https://api.gogoscreen.com/api/v1" } ], "tags": [ { "description": "Who the credential belongs to, and what the account is allowed to do.", "name": "account" }, { "description": "Operations under `assistant`.", "name": "assistant" }, { "description": "The fixed lists a caller chooses from: plans, voices, render options and marketing templates.", "name": "catalog" }, { "description": "API keys — creating, listing, rotating and revoking them. Dashboard credentials only: a key may not manage keys.", "name": "keys" }, { "description": "Marketing videos generated from a scan of a website: sources, projects, revisions, generations and exports.", "name": "marketing" }, { "description": "Product walkthroughs recorded from a live website, and the seconds they spend.", "name": "renders" }, { "description": "The plan for a walkthrough, made and reviewed before any video is rendered.", "name": "storyboards" }, { "description": "Saved render settings, reusable across walkthroughs.", "name": "templates" }, { "description": "What this account has called, and how much of it.", "name": "usage" }, { "description": "Hearing a narration voice before spending seconds on one.", "name": "voices" }, { "description": "The account's seconds: the balance, and every movement of it.", "name": "wallet" }, { "description": "Where this account's job events are delivered, and what happened to each delivery.", "name": "webhooks" } ], "x-rate-classes": { "charge": { "perMinute": 20 }, "expensive": { "perMinute": 20 }, "read": { "perMinute": 600 }, "write": { "perMinute": 120 } }, "x-scopes": [ "catalog:read", "account:read", "wallet:read", "usage:read", "storyboards:read", "storyboards:write", "renders:read", "renders:write", "marketing:read", "marketing:write", "marketing:export", "webhooks:manage", "keys:manage", "assistant:use" ] }