{"openapi":"3.1.0","info":{"title":"Motiongist API","version":"1.0.0","description":"Generate narrated motion-design explainer videos (vertical 1080×1920) over HTTP. Videos are narrated in English (default) or French (brief.language). Same engine as the Motiongist studio. Docs: https://motiongist.com/docs/api. MCP server for AI agents: https://motiongist.com/api/mcp.","contact":{"email":"support@motiongist.com","url":"https://motiongist.com/docs/api"},"termsOfService":"https://motiongist.com/terms"},"servers":[{"url":"https://motiongist.com"}],"externalDocs":{"description":"Documentation","url":"https://motiongist.com/docs/api"},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Account & catalog"},{"name":"Generations (jobs)"},{"name":"Videos"},{"name":"Post copy, sharing & publishing"},{"name":"Projects"},{"name":"Files"},{"name":"Webhooks"},{"name":"Scripts & ideas"}],"paths":{"/api/v1":{"get":{"operationId":"index","summary":"Public API index","description":"Describes the API without a key: version, links to this documentation and the OpenAPI spec, authentication and the list of endpoints.","tags":["Account & catalog"],"parameters":[],"responses":{"200":{"description":"Public index","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"docs":{"type":"string"},"openapi":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}}},"requestId":{"type":"string"}}},"example":{"data":{"name":"Motiongist API","version":"1.0.0","docs":"https://motiongist.com/docs/api","openapi":"https://motiongist.com/openapi.json","endpoints":["…"]},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"security":[]}},"/api/v1/me":{"get":{"operationId":"me","summary":"Current workspace, plan, credits and limits","description":"Workspace linked to the key, plan, credit balance, limits (rate, parallel generations) and the key’s scopes.","tags":["Account & catalog"],"parameters":[],"responses":{"200":{"description":"My account","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"subscriptionStatus":{"type":"string"}}},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"monthlyCredits":{"type":"integer"},"softOverdraft":{"type":"integer"},"maxConcurrentJobs":{"type":"integer"}}},"credits":{"type":"object","properties":{"balance":{"type":"integer"}}},"limits":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"},"maxConcurrentJobs":{"type":"integer"},"activeJobs":{"type":"object","properties":{"running":{"type":"integer"},"queued":{"type":"integer"}}}}},"key":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"workspace":{"id":"0d1e2f3a-4b5c-4d6e-8f70-81a2b3c4d5e6","name":"Acme’s workspace","plan":"studio","subscriptionStatus":"active"},"plan":{"id":"studio","name":"Studio","monthlyCredits":30000,"softOverdraft":15000,"maxConcurrentJobs":2},"credits":{"balance":29153},"limits":{"requestsPerMinute":60,"maxConcurrentJobs":2,"activeJobs":{"running":1,"queued":0}},"key":{"id":"b1c2d3e4-…","kind":"rest","scopes":["jobs:write","jobs:read","videos:read","videos:write","assets:write","webhooks:write"]}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}}}},"/api/v1/catalog":{"get":{"operationId":"catalog","summary":"Voices, looks, lengths, languages and credit costs","description":"Everything you can put in a brief: voices (with audio samples), looks, lengths, narration languages (en, fr), audiences, credit costs and plans.","tags":["Account & catalog"],"parameters":[],"responses":{"200":{"description":"Catalog","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"voices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"gender":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}},"looks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"lengths":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"secondsMin":{"type":"integer"},"secondsMax":{"type":"integer"},"baseCredits":{"type":"integer"}}}},"languages":{"type":"array","items":{"type":"string"}},"defaultLanguage":{"type":"string"},"audiences":{"type":"array","items":{"type":"string"}},"creditCosts":{"type":"object","properties":{"base":{"type":"object","properties":{"short":{"type":"integer"},"standard":{"type":"integer"},"full":{"type":"integer"}}},"finalVoicePerChars":{"type":"integer"},"studioTier":{"type":"integer"},"customLook":{"type":"integer"},"threeD":{"type":"integer"},"revisionFactor":{"type":"number"}}}}},"requestId":{"type":"string"}}},"example":{"data":{"voices":[{"id":"George","name":"George","gender":"m","description":"Warm and steady, made for explaining","tags":["narration","calm"]}],"looks":[{"id":"clean","label":"Light, product"},{"id":"night","label":"Dark, tech"},{"id":"toon","label":"Illustrated"}],"lengths":[{"id":"short","secondsMin":45,"secondsMax":60,"baseCredits":400}],"languages":["en","fr"],"defaultLanguage":"en","audiences":["beginner","dev","ops","decision-maker"],"creditCosts":{"base":{"short":400,"standard":700,"full":1000},"finalVoicePerChars":10,"studioTier":300,"customLook":300,"threeD":100,"revisionFactor":0.5}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}}}},"/api/v1/jobs/estimate":{"post":{"operationId":"jobsEstimate","summary":"Price a brief and get a signed quote","description":"Computes the exact price in credits and the generation time, and returns a signed quote valid for 1 hour. Nothing is charged. Pass the quote to POST /jobs to lock the price.","tags":["Generations (jobs)"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Estimate a brief","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer"}}}},"quote":{"type":"string"},"quoteExpiresAt":{"type":"string"},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"balance":{"type":"integer"},"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{}},"overdraft":{"type":"boolean"},"eta":{"type":"object","properties":{"minutesMin":{"type":"integer"},"minutesMax":{"type":"integer"}}}}},"requestId":{"type":"string"}}},"example":{"data":{"total":847,"lines":[{"label":"Standard video (90–120 s)","credits":700},{"label":"Final voice (1,470 characters)","credits":147}],"quote":"eyJ3cyI6IjQ…(signed quote, pass it back unchanged)…","quoteExpiresAt":"2026-10-23T10:12:00.000Z","voiceMode":"final","isRevision":false,"balance":29153,"allowed":true,"blockers":[],"overdraft":false,"eta":{"minutesMin":4,"minutesMax":8}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brief":{"type":"object","properties":{"subject":{"type":"string","minLength":3,"maxLength":200},"input":{"default":{"kind":"idea"},"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"idea"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["kind","text"]},{"type":"object","properties":{"kind":{"type":"string","const":"document"},"text":{"type":"string","minLength":1,"maxLength":40000},"sourceName":{"type":"string","maxLength":200}},"required":["kind","text"]}]},"audience":{"default":"dev","type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"default":"standard","type":"string","enum":["short","standard","full"]},"language":{"default":"en","type":"string","enum":["fr","en"]},"voice":{"default":"George","type":"string","maxLength":40},"look":{"default":{"mode":"preset"},"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"preset"},"preset":{"type":"string","maxLength":40}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"brand"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"description":{"type":"string","minLength":3,"maxLength":500}},"required":["mode","description"]}]},"brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":24},"site":{"type":"string","maxLength":40},"colors":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"logo":{"type":"string","maxLength":200}},"required":["name","colors"]},"notes":{"default":{"mustShow":[],"avoid":[]},"type":"object","properties":{"mustShow":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"avoid":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"keyMoment":{"type":"string","maxLength":200},"free":{"type":"string","maxLength":1000}}},"mascot":{"default":false,"type":"boolean"},"tier":{"default":"standard","type":"string","enum":["standard","studio"]},"dimension":{"default":"2d","type":"string","enum":["2d","3d"]},"threeD":{"default":"none","type":"string","enum":["none","signature"]}},"required":["subject"],"description":"The full video brief"},"voiceMode":{"type":"string","enum":["draft","final"],"description":"final = licensed voice (paid plans), draft = free draft voice. Default: final on paid plans."}},"required":["brief"]},"example":{"brief":{"subject":"How a CDN works","input":{"kind":"idea"},"audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":["edge cache","latency"],"avoid":[]}}}}}}}},"/api/v1/jobs":{"post":{"operationId":"jobsCreate","summary":"Start a generation","description":"Charges the credits and queues the generation. With a quote, the price is guaranteed (and refused if the brief changed); without a quote, the server recomputes the price. 202 response: then poll GET /jobs/{id} or subscribe to webhooks.","tags":["Generations (jobs)"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"202":{"description":"Start a generation","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"integer"},"detail":{"type":"null"},"stages":{"type":"object","properties":{}},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"credits":{"type":"integer"},"queuePosition":{"type":"integer"},"cancellable":{"type":"boolean"},"error":{"type":"null"},"videoId":{"type":"null"},"attempt":{"type":"integer"},"source":{"type":"string"},"queuedAt":{"type":"string"},"startedAt":{"type":"null"},"finishedAt":{"type":"null"}}},"projectId":{"type":"string"},"queuePosition":{"type":"integer"}}},"requestId":{"type":"string"}}},"example":{"data":{"job":{"id":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","status":"queued","stage":"script","stageLabel":"Script","progress":0,"detail":null,"stages":{},"voiceMode":"final","isRevision":false,"credits":847,"queuePosition":1,"cancellable":true,"error":null,"videoId":null,"attempt":1,"source":"api","queuedAt":"2026-10-23T09:12:04.000Z","startedAt":null,"finishedAt":null},"projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","queuePosition":1},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR | QUOTE_INVALID","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"402":{"description":"INSUFFICIENT_CREDITS","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INSUFFICIENT_CREDITS","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"brief":{"description":"Video brief (one-shot: a project is created for it). Or projectId.","type":"object","properties":{"subject":{"type":"string","minLength":3,"maxLength":200},"input":{"default":{"kind":"idea"},"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"idea"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["kind","text"]},{"type":"object","properties":{"kind":{"type":"string","const":"document"},"text":{"type":"string","minLength":1,"maxLength":40000},"sourceName":{"type":"string","maxLength":200}},"required":["kind","text"]}]},"audience":{"default":"dev","type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"default":"standard","type":"string","enum":["short","standard","full"]},"language":{"default":"en","type":"string","enum":["fr","en"]},"voice":{"default":"George","type":"string","maxLength":40},"look":{"default":{"mode":"preset"},"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"preset"},"preset":{"type":"string","maxLength":40}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"brand"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"description":{"type":"string","minLength":3,"maxLength":500}},"required":["mode","description"]}]},"brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":24},"site":{"type":"string","maxLength":40},"colors":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"logo":{"type":"string","maxLength":200}},"required":["name","colors"]},"notes":{"default":{"mustShow":[],"avoid":[]},"type":"object","properties":{"mustShow":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"avoid":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"keyMoment":{"type":"string","maxLength":200},"free":{"type":"string","maxLength":1000}}},"mascot":{"default":false,"type":"boolean"},"tier":{"default":"standard","type":"string","enum":["standard","studio"]},"dimension":{"default":"2d","type":"string","enum":["2d","3d"]},"threeD":{"default":"none","type":"string","enum":["none","signature"]}},"required":["subject"]},"projectId":{"description":"Existing project to generate (alternative to brief)","type":"string","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)$"},"quote":{"description":"Signed quote returned by POST /jobs/estimate. Guarantees the price; without a quote, the server recomputes the price.","type":"string","minLength":10,"maxLength":4000},"title":{"type":"string","minLength":1,"maxLength":120},"voiceMode":{"type":"string","enum":["draft","final"],"description":"final = licensed voice (paid plans), draft = free draft voice. Default: final on paid plans."}}},"example":{"brief":{"subject":"How a CDN works","input":{"kind":"idea"},"audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":["edge cache","latency"],"avoid":[]}},"quote":"eyJ3cyI6IjQ…(signed quote, pass it back unchanged)…"}}}}},"get":{"operationId":"jobsList","summary":"List generations","description":"Generations of the workspace, newest first, with cursor pagination.","tags":["Generations (jobs)"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items (1 to 100, default 20)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned in nextCursor, for the next page","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter, one or more comma-separated values: queued, running, succeeded, failed, cancelled","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only generations created after this date (ISO 8601)","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"List generations","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"integer"},"detail":{"type":"string"},"stages":{"type":"object","properties":{}},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"credits":{"type":"integer"},"queuePosition":{"type":"integer"},"cancellable":{"type":"boolean"},"error":{"type":"null"},"videoId":{"type":"null"},"attempt":{"type":"integer"},"source":{"type":"string"},"queuedAt":{"type":"string"},"startedAt":{"type":"string"},"finishedAt":{"type":"null"}}}},"nextCursor":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"items":[{"id":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","status":"running","stage":"storyboard","stageLabel":"Storyboard","progress":46,"detail":"Scene 4/9","stages":{},"voiceMode":"final","isRevision":false,"credits":847,"queuePosition":0,"cancellable":true,"error":null,"videoId":null,"attempt":1,"source":"api","queuedAt":"2026-10-23T09:12:04.000Z","startedAt":"2026-10-23T09:12:09.000Z","finishedAt":null}],"nextCursor":"2026-10-23T09:12:04.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read"}},"/api/v1/jobs/{id}":{"get":{"operationId":"jobsGet","summary":"Get a generation","description":"Status, stage (script, voice, storyboard, review, render), progress in %, queue position, error if any, and videoId once finished. Poll every 5 to 10 seconds at most.","tags":["Generations (jobs)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Generation id","schema":{"type":"string","format":"uuid"},"example":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55"}],"responses":{"200":{"description":"Track a generation","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"integer"},"detail":{"type":"null"},"stages":{"type":"object","properties":{}},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"credits":{"type":"integer"},"queuePosition":{"type":"integer"},"cancellable":{"type":"boolean"},"error":{"type":"null"},"videoId":{"type":"string"},"attempt":{"type":"integer"},"source":{"type":"string"},"queuedAt":{"type":"string"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","status":"succeeded","stage":"done","stageLabel":"Ready","progress":100,"detail":null,"stages":{},"voiceMode":"final","isRevision":false,"credits":847,"queuePosition":0,"cancellable":false,"error":null,"videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","attempt":1,"source":"api","queuedAt":"2026-10-23T09:12:04.000Z","startedAt":"2026-10-23T09:12:09.000Z","finishedAt":"2026-10-23T09:19:41.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read"}},"/api/v1/jobs/{id}/cancel":{"post":{"operationId":"jobsCancel","summary":"Cancel a generation","description":"Cancels a generation as long as rendering has not started. Queued: cancelled immediately and credits refunded. Running: the engine is asked to stop, the refund follows.","tags":["Generations (jobs)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Generation id","schema":{"type":"string","format":"uuid"},"example":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Cancel a generation","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"integer"},"detail":{"type":"string"},"stages":{"type":"object","properties":{}},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"credits":{"type":"integer"},"queuePosition":{"type":"integer"},"cancellable":{"type":"boolean"},"error":{"type":"null"},"videoId":{"type":"null"},"attempt":{"type":"integer"},"source":{"type":"string"},"queuedAt":{"type":"string"},"startedAt":{"type":"string"},"finishedAt":{"type":"null"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","status":"cancelled","stage":"storyboard","stageLabel":"Storyboard","progress":46,"detail":"Scene 4/9","stages":{},"voiceMode":"final","isRevision":false,"credits":847,"queuePosition":0,"cancellable":false,"error":null,"videoId":null,"attempt":1,"source":"api","queuedAt":"2026-10-23T09:12:04.000Z","startedAt":"2026-10-23T09:12:09.000Z","finishedAt":null},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"NOT_CANCELLABLE","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_CANCELLABLE","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write"}},"/api/v1/videos":{"get":{"operationId":"videosList","summary":"List videos","description":"Finished videos of the workspace, newest first. Use GET /videos/{id} to get the download links.","tags":["Videos"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items (1 to 100, default 20)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned in nextCursor, for the next page","schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"description":"Only the versions of this project","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List videos","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"jobId":{"type":"string"},"title":{"type":"string"},"durationS":{"type":"number"},"width":{"type":"integer"},"height":{"type":"integer"},"draftVoice":{"type":"boolean"},"watermarked":{"type":"boolean"},"createdAt":{"type":"string"}}}},"nextCursor":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"items":[{"id":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","jobId":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","title":"How a CDN works","durationS":104.2,"width":1080,"height":1920,"draftVoice":false,"watermarked":false,"createdAt":"2026-10-23T09:19:41.000Z"}],"nextCursor":"2026-10-23T09:12:04.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"}},"/api/v1/videos/{id}":{"get":{"operationId":"videosGet","summary":"Get a video with signed file URLs","description":"Metadata and signed links valid for 15 minutes: MP4 (1080×1920, Range requests supported), SRT captions, contact sheet, poster, storyboard. Fetch the video again for fresh links.","tags":["Videos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Get a video","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"jobId":{"type":"string"},"title":{"type":"string"},"durationS":{"type":"number"},"width":{"type":"integer"},"height":{"type":"integer"},"voice":{"type":"string"},"voiceProvider":{"type":"string"},"draftVoice":{"type":"boolean"},"watermarked":{"type":"boolean"},"look":{"type":"string"},"scenes":{"type":"integer"},"qaScore":{"type":"number"},"createdAt":{"type":"string"},"aiGenerated":{"type":"boolean"},"files":{"type":"object","properties":{"mp4":{"type":"object","properties":{"url":{"type":"string"},"download":{"type":"string"}}},"srt":{"type":"object","properties":{"url":{"type":"string"},"download":{"type":"string"}}},"contact":{"type":"object","properties":{"url":{"type":"string"},"download":{"type":"string"}}},"poster":{"type":"object","properties":{"url":{"type":"string"},"download":{"type":"string"}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","jobId":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","title":"How a CDN works","durationS":104.2,"width":1080,"height":1920,"voice":"George","voiceProvider":"elevenlabs","draftVoice":false,"watermarked":false,"look":"night","scenes":11,"qaScore":0.93,"createdAt":"2026-10-23T09:19:41.000Z","aiGenerated":true,"files":{"mp4":{"url":"https://motiongist.com/api/files/videos/…/video.mp4?e=1761211161&s=…","download":"https://motiongist.com/api/files/videos/…/video.mp4?e=1761211161&s=…&d=how-a-cdn-works.mp4"},"srt":{"url":"https://motiongist.com/api/files/videos/…/captions.srt?e=1761211161&s=…","download":"https://motiongist.com/api/files/videos/…/captions.srt?e=1761211161&s=…&d=how-a-cdn-works-captions.srt"},"contact":{"url":"https://motiongist.com/api/files/videos/…/contact.jpg?e=1761211161&s=…","download":"https://motiongist.com/api/files/videos/…/contact.jpg?e=1761211161&s=…&d=…"},"poster":{"url":"https://motiongist.com/api/files/videos/…/poster.jpg?e=1761211161&s=…","download":"https://motiongist.com/api/files/videos/…/poster.jpg?e=1761211161&s=…&d=…"}}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"},"delete":{"operationId":"videosDelete","summary":"Delete a video","description":"Deletes the video (files are permanently erased after 30 days). Emits the video.deleted event.","tags":["Videos"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Delete a video","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","deleted":true},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write"}},"/api/v1/videos/{id}/post-copy":{"get":{"operationId":"postCopyGet","summary":"Post copy of a video per platform","description":"Title, description and hashtags for YouTube, TikTok, Instagram and LinkedIn, in the video language and within each platform limit (limits are returned). Generated on the first call, then stored. caption is the text actually posted (description + hashtags).","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Get the post copy","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"language":{"type":"string"},"generatedAt":{"type":"string"},"platforms":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"caption":{"type":"string"},"limits":{"type":"object","properties":{"title":{"type":"integer"},"caption":{"type":"integer"},"hashtags":{"type":"integer"}}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"language":"en","generatedAt":"2026-10-23T09:20:00.000Z","platforms":{"youtube":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"],"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","limits":{"title":100,"caption":5000,"hashtags":15}}}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"},"post":{"operationId":"postCopyRegenerate","summary":"Rewrite the post copy","description":"Rewrites the copy (all platforms or some), optionally in another language. Free, limited to 60 AI calls per hour per workspace.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Rewrite the post copy","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"language":{"type":"string"},"generatedAt":{"type":"string"},"platforms":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"caption":{"type":"string"},"limits":{"type":"object","properties":{"title":{"type":"integer"},"caption":{"type":"integer"},"hashtags":{"type":"integer"}}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"language":"en","generatedAt":"2026-10-23T09:20:00.000Z","platforms":{"youtube":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"],"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","limits":{"title":100,"caption":5000,"hashtags":15}}}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"description":"Write it in this language (default: the current one, else the video language)","type":"string","enum":["en","fr"]},"platforms":{"description":"Only these platforms (the others are kept)","type":"array","items":{"type":"string","enum":["youtube","tiktok","instagram","linkedin"]}}}},"example":{"language":"en","platforms":["tiktok"]}}}}},"patch":{"operationId":"postCopyUpdate","summary":"Save edited post copy","description":"Replaces the given platforms. Text over a platform limit is refused (VALIDATION_ERROR), never cut. Hashtags are given without #.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Edit the post copy","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"language":{"type":"string"},"generatedAt":{"type":"string"},"platforms":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"caption":{"type":"string"},"limits":{"type":"object","properties":{"title":{"type":"integer"},"caption":{"type":"integer"},"hashtags":{"type":"integer"}}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"language":"en","generatedAt":"2026-10-23T09:20:00.000Z","platforms":{"youtube":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"],"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","limits":{"title":100,"caption":5000,"hashtags":15}}}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["en","fr"]},"platforms":{"type":"object","properties":{"youtube":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":6000},"hashtags":{"maxItems":60,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title","description","hashtags"]},"tiktok":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":6000},"hashtags":{"maxItems":60,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title","description","hashtags"]},"instagram":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":6000},"hashtags":{"maxItems":60,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title","description","hashtags"]},"linkedin":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":6000},"hashtags":{"maxItems":60,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title","description","hashtags"]}}}},"required":["platforms"]},"example":{"platforms":{"tiktok":{"title":"How a CDN works","description":"Your files, next to your visitors.","hashtags":["webdev","cdn"]}}}}}}}},"/api/v1/videos/{id}/share":{"get":{"operationId":"shareGet","summary":"Share page settings of a video","description":"Public share page of the video: link (unlisted, noindex), embed code, button, download, branding and view count. enabled=false means no public link.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Get the share page","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"token":{"type":"string"},"url":{"type":"string"},"embedUrl":{"type":"string"},"embedCode":{"type":"string"},"cta":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}},"allowDownload":{"type":"boolean"},"showBranding":{"type":"boolean"},"brandingForced":{"type":"boolean"},"views":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"enabled":true,"token":"Xq3vR8kP2mWz7tLa","url":"https://motiongist.com/v/Xq3vR8kP2mWz7tLa","embedUrl":"https://motiongist.com/embed/Xq3vR8kP2mWz7tLa","embedCode":"<iframe src=\"https://motiongist.com/embed/Xq3vR8kP2mWz7tLa\" …></iframe>","cta":{"label":"Book a demo","url":"https://example.com/demo"},"allowDownload":false,"showBranding":true,"brandingForced":false,"views":128,"createdAt":"2026-10-23T09:25:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"},"patch":{"operationId":"shareUpdate","summary":"Turn the share page on/off and set it up","description":"enabled=true creates the link (kept across updates); enabled=false revokes it for good (turning it back on creates a new link). cta adds a button (http/https URL). The free plan always shows the \"Made with Motiongist\" badge.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string","format":"uuid"},"example":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f"}],"responses":{"200":{"description":"Update the share page","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"enabled":{"type":"boolean"},"token":{"type":"string"},"url":{"type":"string"},"embedUrl":{"type":"string"},"embedCode":{"type":"string"},"cta":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}},"allowDownload":{"type":"boolean"},"showBranding":{"type":"boolean"},"brandingForced":{"type":"boolean"},"views":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"enabled":true,"token":"Xq3vR8kP2mWz7tLa","url":"https://motiongist.com/v/Xq3vR8kP2mWz7tLa","embedUrl":"https://motiongist.com/embed/Xq3vR8kP2mWz7tLa","embedCode":"<iframe src=\"https://motiongist.com/embed/Xq3vR8kP2mWz7tLa\" …></iframe>","cta":{"label":"Book a demo","url":"https://example.com/demo"},"allowDownload":false,"showBranding":true,"brandingForced":false,"views":128,"createdAt":"2026-10-23T09:25:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"cta":{"anyOf":[{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":40},"url":{"type":"string","maxLength":500}},"required":["label","url"]},{"type":"null"}]},"allowDownload":{"type":"boolean"},"showBranding":{"type":"boolean"}},"required":["enabled"]},"example":{"enabled":true,"cta":{"label":"Book a demo","url":"https://example.com/demo"},"allowDownload":false}}}}}},"/api/v1/social-accounts":{"get":{"operationId":"socialAccountsList","summary":"Connected social accounts","description":"YouTube, TikTok, Instagram and LinkedIn accounts connected by the workspace members in the web app (/app/publishing; connecting needs a browser). platforms tells which platforms this server can publish to.","tags":["Post copy, sharing & publishing"],"parameters":[],"responses":{"200":{"description":"List connected accounts","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"null"},"status":{"type":"string"},"simulated":{"type":"boolean"},"connectedAt":{"type":"string"},"updatedAt":{"type":"string"}}}},"platforms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"available":{"type":"boolean"},"mode":{"type":"string"}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"items":[{"id":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","provider":"youtube","name":"Motiongist Demo","avatarUrl":null,"status":"active","simulated":false,"connectedAt":"2026-10-20T14:02:00.000Z","updatedAt":"2026-10-20T14:02:00.000Z"}],"platforms":[{"id":"youtube","available":true,"mode":"live"}]},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"}},"/api/v1/posts":{"get":{"operationId":"postsList","summary":"Publishing queue and history","description":"Posts of the workspace, filtered by scheduled date (from, to), status or video.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"from","in":"query","required":false,"description":"Scheduled at or after (ISO 8601 with offset)","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Scheduled at or before","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"scheduled, publishing, published, failed or cancelled","schema":{"type":"string"}},{"name":"videoId","in":"query","required":false,"description":"Only the posts of this video","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"Number of items (1 to 500, default 100)","schema":{"type":"integer"}}],"responses":{"200":{"description":"List posts","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"type":"string"},"videoTitle":{"type":"string"},"projectId":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string"},"publishedAt":{"type":"null"},"copy":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}},"caption":{"type":"string"},"options":{"type":"object","properties":{}},"externalId":{"type":"null"},"externalUrl":{"type":"null"},"error":{"type":"null"},"attempts":{"type":"integer"},"createdAt":{"type":"string"}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"items":[{"id":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f","videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","videoTitle":"How a CDN works","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","accountName":"Motiongist Demo","provider":"youtube","status":"scheduled","scheduledAt":"2026-10-30T16:30:00.000Z","publishedAt":null,"copy":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"]},"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","options":{},"externalId":null,"externalUrl":null,"error":null,"attempts":0,"createdAt":"2026-10-23T09:30:00.000Z"}]},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"},"post":{"operationId":"postsCreate","summary":"Publish a video now or schedule it (free)","description":"Queues a video for a connected account, now (scheduledAt omitted) or at scheduledAt (up to 1 year ahead). Uses the video post copy for the platform unless copy is given. Costs no credits. The worker publishes within seconds of the date, retries temporary errors (after 1 min, 5 min, 30 min) and emits post.published or post.failed.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"201":{"description":"Publish or schedule","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"type":"string"},"videoTitle":{"type":"string"},"projectId":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string"},"publishedAt":{"type":"null"},"copy":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}},"caption":{"type":"string"},"options":{"type":"object","properties":{}},"externalId":{"type":"null"},"externalUrl":{"type":"null"},"error":{"type":"null"},"attempts":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f","videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","videoTitle":"How a CDN works","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","accountName":"Motiongist Demo","provider":"youtube","status":"scheduled","scheduledAt":"2026-10-30T16:30:00.000Z","publishedAt":null,"copy":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"]},"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","options":{},"externalId":null,"externalUrl":null,"error":null,"attempts":0,"createdAt":"2026-10-23T09:30:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"type":"string","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)$"},"accountId":{"type":"string","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)$"},"scheduledAt":{"anyOf":[{"type":"string","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":"null"}]},"copy":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"description":{"type":"string","maxLength":6000},"hashtags":{"maxItems":60,"type":"array","items":{"type":"string","maxLength":100}}},"required":["title","description","hashtags"]},"options":{"type":"object","properties":{"privacy":{"type":"string","enum":["public","unlisted","private"]},"simulate":{"type":"string","enum":["transient","permanent","auth"]}},"additionalProperties":false}},"required":["videoId","accountId"]},"example":{"videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","scheduledAt":"2026-10-30T17:30:00+01:00"}}}}}},"/api/v1/posts/{id}":{"get":{"operationId":"postsGet","summary":"Get a post","description":"Status of a post; externalUrl once published, error when it failed.","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string","format":"uuid"},"example":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f"}],"responses":{"200":{"description":"Get a post","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"type":"string"},"videoTitle":{"type":"string"},"projectId":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string"},"publishedAt":{"type":"string"},"copy":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}},"caption":{"type":"string"},"options":{"type":"object","properties":{}},"externalId":{"type":"string"},"externalUrl":{"type":"string"},"error":{"type":"null"},"attempts":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f","videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","videoTitle":"How a CDN works","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","accountName":"Motiongist Demo","provider":"youtube","status":"published","scheduledAt":"2026-10-30T16:30:00.000Z","publishedAt":"2026-10-30T16:30:08.000Z","copy":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"]},"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","options":{},"externalId":"dQw4w9WgXcQ","externalUrl":"https://www.youtube.com/shorts/dQw4w9WgXcQ","error":null,"attempts":0,"createdAt":"2026-10-23T09:30:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:read"},"patch":{"operationId":"postsUpdate","summary":"Reschedule a post","description":"Moves a scheduled post, or re-queues a failed or cancelled one (attempts reset).","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string","format":"uuid"},"example":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f"}],"responses":{"200":{"description":"Reschedule a post","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"type":"string"},"videoTitle":{"type":"string"},"projectId":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string"},"publishedAt":{"type":"null"},"copy":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}},"caption":{"type":"string"},"options":{"type":"object","properties":{}},"externalId":{"type":"null"},"externalUrl":{"type":"null"},"error":{"type":"null"},"attempts":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f","videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","videoTitle":"How a CDN works","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","accountName":"Motiongist Demo","provider":"youtube","status":"scheduled","scheduledAt":"2026-10-30T16:30:00.000Z","publishedAt":null,"copy":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"]},"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","options":{},"externalId":null,"externalUrl":null,"error":null,"attempts":0,"createdAt":"2026-10-23T09:30:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledAt":{"anyOf":[{"type":"string","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":"null"}],"description":"New time (ISO 8601 with offset); null = now"}},"required":["scheduledAt"]},"example":{"scheduledAt":"2026-10-31T09:00:00+01:00"}}}}},"delete":{"operationId":"postsCancel","summary":"Cancel a scheduled post","description":"Cancels a post that has not started publishing (CONFLICT otherwise).","tags":["Post copy, sharing & publishing"],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string","format":"uuid"},"example":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f"}],"responses":{"200":{"description":"Cancel a post","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"videoId":{"type":"string"},"videoTitle":{"type":"string"},"projectId":{"type":"string"},"accountId":{"type":"string"},"accountName":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"scheduledAt":{"type":"string"},"publishedAt":{"type":"null"},"copy":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}}}},"caption":{"type":"string"},"options":{"type":"object","properties":{}},"externalId":{"type":"null"},"externalUrl":{"type":"null"},"error":{"type":"null"},"attempts":{"type":"integer"},"createdAt":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"01970d2c-77cc-7e3a-8f1b-5a6b7c8d9e0f","videoId":"c4d5e6f7-1a2b-4c3d-8e9f-0a1b2c3d4e5f","videoTitle":"How a CDN works","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","accountId":"01970d2c-55aa-7c1e-9d0b-3e4f5a6b7c8d","accountName":"Motiongist Demo","provider":"youtube","status":"cancelled","scheduledAt":"2026-10-30T16:30:00.000Z","publishedAt":null,"copy":{"title":"How a CDN works in 60 seconds #shorts","description":"Your files, next to your visitors.\n\nFollow for more explainers.","hashtags":["cdn","webdev","shorts"]},"caption":"Your files, next to your visitors.\n\nFollow for more explainers.\n\n#cdn #webdev #shorts","options":{},"externalId":null,"externalUrl":null,"error":null,"attempts":0,"createdAt":"2026-10-23T09:30:00.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"videos:write"}},"/api/v1/projects":{"get":{"operationId":"projectsList","summary":"List projects","description":"Projects (studio drafts) of the workspace, most recently updated first.","tags":["Projects"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Number of items (1 to 100, default 20)","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned in nextCursor, for the next page","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"draft, queued, generating, ready or failed","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search in the title","schema":{"type":"string"}}],"responses":{"200":{"description":"List projects","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"draft":{"type":"object","properties":{"subject":{"type":"string"},"inputKind":{"type":"string"},"audience":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"voice":{"type":"string"},"look":{"type":"object","properties":{"mode":{"type":"string"},"preset":{"type":"string"}}},"notes":{"type":"object","properties":{"mustShow":{"type":"array","items":{}},"avoid":{"type":"array","items":{}}}},"mascot":{"type":"boolean"},"tier":{"type":"string"},"format":{"type":"string"},"captions":{"type":"boolean"},"music":{"type":"boolean"}}},"script":{"type":"string"},"narration":{"type":"null"},"latestJobId":{"type":"null"},"latestVideoId":{"type":"null"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"}}}},"nextCursor":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"items":[{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","title":"How a CDN works","status":"draft","draft":{"subject":"How a CDN works","inputKind":"script","audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":[],"avoid":[]},"mascot":false,"tier":"standard","format":"9:16","captions":true,"music":true},"script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","narration":null,"latestJobId":null,"latestVideoId":null,"source":"api","createdAt":"2026-10-23T09:02:11.000Z","updatedAt":"2026-10-23T09:04:37.000Z","url":"https://motiongist.com/app/projects/2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"nextCursor":"2026-10-23T09:12:04.000Z"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read"},"post":{"operationId":"projectsCreate","summary":"Create a project (draft)","description":"Creates a draft, like in the studio: settings, script, voice preview, then estimate and generate. Handy for an agent that iterates with the user before paying. The project also shows up in the web studio.","tags":["Projects"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"201":{"description":"Create a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"draft":{"type":"object","properties":{"subject":{"type":"string"},"inputKind":{"type":"string"},"audience":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"voice":{"type":"string"},"look":{"type":"object","properties":{"mode":{"type":"string"},"preset":{"type":"string"}}},"notes":{"type":"object","properties":{"mustShow":{"type":"array","items":{}},"avoid":{"type":"array","items":{}}}},"mascot":{"type":"boolean"},"tier":{"type":"string"},"format":{"type":"string"},"captions":{"type":"boolean"},"music":{"type":"boolean"}}},"script":{"type":"string"},"narration":{"type":"null"},"latestJobId":{"type":"null"},"latestVideoId":{"type":"null"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","title":"How a CDN works","status":"draft","draft":{"subject":"How a CDN works","inputKind":"script","audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":[],"avoid":[]},"mascot":false,"tier":"standard","format":"9:16","captions":true,"music":true},"script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","narration":null,"latestJobId":null,"latestVideoId":null,"source":"api","createdAt":"2026-10-23T09:02:11.000Z","updatedAt":"2026-10-23T09:04:37.000Z","url":"https://motiongist.com/app/projects/2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"script":{"description":"Exact text to narrate. Without a script, POST /projects/{id}/script writes one.","type":"string","maxLength":4000},"draft":{"description":"Project settings: subject, audience, length, language (en or fr), voice, look, brand, notes…","type":"object","properties":{"subject":{"type":"string","maxLength":200},"inputKind":{"type":"string","enum":["idea","script","url","document"]},"sourceText":{"type":"string","maxLength":40000},"sourceName":{"type":"string","maxLength":200},"sourceUrl":{"type":"string","maxLength":2000},"audience":{"type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"type":"string","enum":["short","standard","full"]},"language":{"type":"string","enum":["fr","en"]},"voice":{"type":"string","maxLength":40},"look":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"preset"},"preset":{"type":"string","maxLength":40}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"brand"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"description":{"type":"string","minLength":3,"maxLength":500}},"required":["mode","description"]}]},"brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":24},"site":{"type":"string","maxLength":40},"colors":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"logo":{"type":"string","maxLength":200}},"required":["name","colors"]},"notes":{"type":"object","properties":{"mustShow":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"avoid":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"keyMoment":{"type":"string","maxLength":200},"free":{"type":"string","maxLength":1000}}},"mascot":{"type":"boolean"},"tier":{"type":"string","enum":["standard","studio"]},"dimension":{"type":"string","enum":["2d","3d"]},"format":{"type":"string","enum":["9:16","16:9"]},"captions":{"type":"boolean"},"music":{"type":"boolean"}}}}},"example":{"draft":{"subject":"How a CDN works","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"}}}}}}}},"/api/v1/projects/{id}":{"get":{"operationId":"projectsGet","summary":"Get a project","description":"Settings, script, narration preview, latest generation and latest video of the project.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Get a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"draft":{"type":"object","properties":{"subject":{"type":"string"},"inputKind":{"type":"string"},"audience":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"voice":{"type":"string"},"look":{"type":"object","properties":{"mode":{"type":"string"},"preset":{"type":"string"}}},"notes":{"type":"object","properties":{"mustShow":{"type":"array","items":{}},"avoid":{"type":"array","items":{}}}},"mascot":{"type":"boolean"},"tier":{"type":"string"},"format":{"type":"string"},"captions":{"type":"boolean"},"music":{"type":"boolean"}}},"script":{"type":"string"},"narration":{"type":"null"},"latestJobId":{"type":"null"},"latestVideoId":{"type":"null"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","title":"How a CDN works","status":"draft","draft":{"subject":"How a CDN works","inputKind":"script","audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":[],"avoid":[]},"mascot":false,"tier":"standard","format":"9:16","captions":true,"music":true},"script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","narration":null,"latestJobId":null,"latestVideoId":null,"source":"api","createdAt":"2026-10-23T09:02:11.000Z","updatedAt":"2026-10-23T09:04:37.000Z","url":"https://motiongist.com/app/projects/2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read"},"patch":{"operationId":"projectsUpdate","summary":"Update a project","description":"Updates the title, the script (null to clear it) or part of the settings (merged with the existing ones). Any change invalidates the previous quote.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Update a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"draft":{"type":"object","properties":{"subject":{"type":"string"},"inputKind":{"type":"string"},"audience":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"voice":{"type":"string"},"look":{"type":"object","properties":{"mode":{"type":"string"},"preset":{"type":"string"}}},"notes":{"type":"object","properties":{"mustShow":{"type":"array","items":{}},"avoid":{"type":"array","items":{}}}},"mascot":{"type":"boolean"},"tier":{"type":"string"},"format":{"type":"string"},"captions":{"type":"boolean"},"music":{"type":"boolean"}}},"script":{"type":"string"},"narration":{"type":"null"},"latestJobId":{"type":"null"},"latestVideoId":{"type":"null"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","title":"How a CDN works","status":"draft","draft":{"subject":"How a CDN works","inputKind":"script","audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":[],"avoid":[]},"mascot":false,"tier":"standard","format":"9:16","captions":true,"music":true},"script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","narration":null,"latestJobId":null,"latestVideoId":null,"source":"api","createdAt":"2026-10-23T09:02:11.000Z","updatedAt":"2026-10-23T09:04:37.000Z","url":"https://motiongist.com/app/projects/2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"script":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"draft":{"type":"object","properties":{"subject":{"type":"string","maxLength":200},"inputKind":{"type":"string","enum":["idea","script","url","document"]},"sourceText":{"type":"string","maxLength":40000},"sourceName":{"type":"string","maxLength":200},"sourceUrl":{"type":"string","maxLength":2000},"audience":{"type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"type":"string","enum":["short","standard","full"]},"language":{"type":"string","enum":["fr","en"]},"voice":{"type":"string","maxLength":40},"look":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"preset"},"preset":{"type":"string","maxLength":40}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"brand"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"description":{"type":"string","minLength":3,"maxLength":500}},"required":["mode","description"]}]},"brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":24},"site":{"type":"string","maxLength":40},"colors":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"logo":{"type":"string","maxLength":200}},"required":["name","colors"]},"notes":{"type":"object","properties":{"mustShow":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"avoid":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"keyMoment":{"type":"string","maxLength":200},"free":{"type":"string","maxLength":1000}}},"mascot":{"type":"boolean"},"tier":{"type":"string","enum":["standard","studio"]},"dimension":{"type":"string","enum":["2d","3d"]},"format":{"type":"string","enum":["9:16","16:9"]},"captions":{"type":"boolean"},"music":{"type":"boolean"}}}}},"example":{"draft":{"voice":"Sarah","length":"short"}}}}}},"delete":{"operationId":"projectsDelete","summary":"Delete a project","description":"Deletes the project and its videos. Refused (409) while a generation is running.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Delete a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","deleted":true},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write"}},"/api/v1/projects/{id}/script":{"post":{"operationId":"projectsScript","summary":"Write the project script with AI","description":"Writes a narrated script (hook, one idea per sentence, recap) from the project subject or source document, in the project language, and saves it to the project. Free, limited to 60 AI calls per hour per workspace.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Write the script","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"title":{"type":"string"},"script":{"type":"string"},"words":{"type":"integer"},"seconds":{"type":"integer"},"source":{"type":"string"},"project":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"draft":{"type":"object","properties":{"subject":{"type":"string"},"inputKind":{"type":"string"},"audience":{"type":"string"},"length":{"type":"string"},"language":{"type":"string"},"voice":{"type":"string"},"look":{"type":"object","properties":{"mode":{"type":"string"},"preset":{"type":"string"}}},"notes":{"type":"object","properties":{"mustShow":{"type":"array","items":{}},"avoid":{"type":"array","items":{}}}},"mascot":{"type":"boolean"},"tier":{"type":"string"},"format":{"type":"string"},"captions":{"type":"boolean"},"music":{"type":"boolean"}}},"script":{"type":"string"},"narration":{"type":"null"},"latestJobId":{"type":"null"},"latestVideoId":{"type":"null"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"}}}}},"requestId":{"type":"string"}}},"example":{"data":{"title":"How a CDN works","script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","words":246,"seconds":100,"source":"llm","project":{"id":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","title":"How a CDN works","status":"draft","draft":{"subject":"How a CDN works","inputKind":"script","audience":"dev","length":"standard","language":"en","voice":"George","look":{"mode":"preset","preset":"night"},"notes":{"mustShow":[],"avoid":[]},"mascot":false,"tier":"standard","format":"9:16","captions":true,"music":true},"script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","narration":null,"latestJobId":null,"latestVideoId":null,"source":"api","createdAt":"2026-10-23T09:02:11.000Z","updatedAt":"2026-10-23T09:04:37.000Z","url":"https://motiongist.com/app/projects/2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"description":"Topic to cover (default: the project subject)","type":"string","minLength":3,"maxLength":500},"tone":{"description":"Desired tone, e.g. \"funny and direct\"","type":"string","maxLength":120}}},"example":{"tone":"direct, with a touch of humor"}}}}}},"/api/v1/projects/{id}/narration":{"post":{"operationId":"projectsNarration","summary":"Synthesize a narration preview","description":"Synthesizes the script with the chosen voice so you can listen before generating. Free, cached as long as the text and the voice do not change. Returns an audio URL valid for 15 minutes.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Preview the narration","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"narration":{"type":"object","properties":{"assetId":{"type":"string"},"voice":{"type":"string"},"provider":{"type":"string"},"seconds":{"type":"number"},"words":{"type":"integer"}}},"audioUrl":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"narration":{"assetId":"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9","voice":"George","provider":"edge","seconds":98.4,"words":246},"audioUrl":"https://motiongist.com/api/files/narrations/…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write"}},"/api/v1/projects/{id}/storyboard":{"get":{"operationId":"projectsStoryboardGet","summary":"Get the project storyboard","description":"The scene plan of the project: status (none, planning, ready, failed) and scenes (id, stage, narration, intent). After a render it is the storyboard of the latest video; dirty lists the scenes the next render rebuilds.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Read the storyboard","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"supported":{"type":"boolean"},"status":{"type":"string"},"source":{"type":"string"},"basedOnVideoId":{"type":"null"},"dirty":{"type":"array","items":{}},"planJob":{"type":"null"},"error":{"type":"null"},"updatedAt":{"type":"string"},"plan":{"type":"object","properties":{"title":{"type":"string"},"look":{"type":"string"},"presenter":{"type":"boolean"},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stage":{"type":"string"},"narration":{"type":"string"},"intent":{"type":"string"}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"supported":true,"status":"ready","source":"engine","basedOnVideoId":null,"dirty":[],"planJob":null,"error":null,"updatedAt":"2026-10-23T09:14:00.000Z","plan":{"title":"How a CDN works","look":"night","presenter":false,"scenes":[{"id":"s1","stage":"hero","narration":"Your site lives on one server. Your visitors live everywhere.","intent":"A single server in Virginia, dots of visitors light up around the globe."},{"id":"s2","stage":"graph","narration":"A CDN keeps copies of it close to every visitor.","intent":"Edge servers pop up on each continent on “copies”, lines shorten on “close”."},{"id":"s3","stage":"split","narration":"Pages load faster, and your server breathes.","intent":"Left: stopwatch 800 → 40 ms. Right: CPU gauge drops."}]}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read"},"post":{"operationId":"projectsStoryboardWrite","summary":"Have the engine write the storyboard (free)","description":"Optional and free: the engine plans the video scene by scene in about a minute, so the user can review it before paying for a render. Poll GET until status is ready. The render then follows the storyboard exactly.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"202":{"description":"Write the storyboard","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"jobId":{"type":"string"},"reused":{"type":"boolean"},"storyboard":{"type":"object","properties":{"supported":{"type":"boolean"},"status":{"type":"string"},"source":{"type":"string"},"basedOnVideoId":{"type":"null"},"dirty":{"type":"array","items":{}},"planJob":{"type":"null"},"error":{"type":"null"},"updatedAt":{"type":"string"},"plan":{"type":"null"}}}}},"requestId":{"type":"string"}}},"example":{"data":{"jobId":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","reused":false,"storyboard":{"supported":true,"status":"planning","source":"engine","basedOnVideoId":null,"dirty":[],"planJob":null,"error":null,"updatedAt":"2026-10-23T09:14:00.000Z","plan":null}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write"},"patch":{"operationId":"projectsStoryboardUpdate","summary":"Edit the storyboard scenes","description":"Replaces the ordered scene list (3 to 24 scenes). Keep the id of existing scenes, omit it for new ones. Edited scenes are rebuilt on the next render; untouched scenes of a rendered video keep their visuals. Estimate again afterwards.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Edit the storyboard","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"supported":{"type":"boolean"},"status":{"type":"string"},"source":{"type":"string"},"basedOnVideoId":{"type":"null"},"dirty":{"type":"array","items":{}},"planJob":{"type":"null"},"error":{"type":"null"},"updatedAt":{"type":"string"},"plan":{"type":"object","properties":{"title":{"type":"string"},"look":{"type":"string"},"presenter":{"type":"boolean"},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stage":{"type":"string"},"narration":{"type":"string"},"intent":{"type":"string"}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"supported":true,"status":"ready","source":"engine","basedOnVideoId":null,"dirty":[],"planJob":null,"error":null,"updatedAt":"2026-10-23T09:14:00.000Z","plan":{"title":"How a CDN works","look":"night","presenter":false,"scenes":[{"id":"s1","stage":"hero","narration":"Your site lives on one server. Your visitors live everywhere.","intent":"A single server in Virginia, dots of visitors light up around the globe."},{"id":"s2","stage":"graph","narration":"A CDN keeps copies of it close to every visitor.","intent":"Edge servers pop up on each continent on “copies”, lines shorten on “close”."},{"id":"s3","stage":"split","narration":"Pages load faster, and your server breathes.","intent":"Left: stopwatch 800 → 40 ms. Right: CPU gauge drops."}]}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":60},"scenes":{"minItems":3,"maxItems":24,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_-]{0,30}$"},"stage":{"type":"string","minLength":2,"maxLength":24},"narration":{"type":"string","minLength":8,"maxLength":360},"intent":{"type":"string","minLength":10,"maxLength":700}},"required":["narration","intent"]}}},"required":["scenes"]},"example":{"scenes":[{"id":"s1","narration":"A CDN keeps copies of your site close to every visitor.","intent":"World map, servers light up on “close”."},{"narration":"New scene without id.","intent":"Stopwatch drops from 800 to 40 ms."},{"id":"s3","narration":"Faster pages, lighter servers.","intent":"Two gauges move in opposite directions."}]}}}}},"delete":{"operationId":"projectsStoryboardDelete","summary":"Drop the storyboard","description":"Removes the storyboard: the engine plans the scenes itself during the next render.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"}],"responses":{"200":{"description":"Remove the storyboard","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"supported":{"type":"boolean"},"status":{"type":"string"},"source":{"type":"string"},"basedOnVideoId":{"type":"null"},"dirty":{"type":"array","items":{}},"planJob":{"type":"null"},"error":{"type":"null"},"updatedAt":{"type":"string"},"plan":{"type":"null"}}},"requestId":{"type":"string"}}},"example":{"data":{"supported":true,"status":"none","source":"engine","basedOnVideoId":null,"dirty":[],"planJob":null,"error":null,"updatedAt":"2026-10-23T09:14:00.000Z","plan":null},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write"}},"/api/v1/projects/{id}/storyboard/regenerate":{"post":{"operationId":"projectsStoryboardRegenerate","summary":"Flag scenes to rebuild on the next render","description":"Marks scenes to be rebuilt on the next render even though their text did not change (new take on the visuals). The other scenes are reused as they are.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Rebuild scenes","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"supported":{"type":"boolean"},"status":{"type":"string"},"source":{"type":"string"},"basedOnVideoId":{"type":"null"},"dirty":{"type":"array","items":{"type":"string"}},"planJob":{"type":"null"},"error":{"type":"null"},"updatedAt":{"type":"string"},"plan":{"type":"object","properties":{"title":{"type":"string"},"look":{"type":"string"},"presenter":{"type":"boolean"},"scenes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stage":{"type":"string"},"narration":{"type":"string"},"intent":{"type":"string"}}}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"supported":true,"status":"ready","source":"engine","basedOnVideoId":null,"dirty":["s2"],"planJob":null,"error":null,"updatedAt":"2026-10-23T09:14:00.000Z","plan":{"title":"How a CDN works","look":"night","presenter":false,"scenes":[{"id":"s1","stage":"hero","narration":"Your site lives on one server. Your visitors live everywhere.","intent":"A single server in Virginia, dots of visitors light up around the globe."},{"id":"s2","stage":"graph","narration":"A CDN keeps copies of it close to every visitor.","intent":"Edge servers pop up on each continent on “copies”, lines shorten on “close”."},{"id":"s3","stage":"split","narration":"Pages load faster, and your server breathes.","intent":"Left: stopwatch 800 → 40 ms. Right: CPU gauge drops."}]}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"409":{"description":"CONFLICT","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sceneIds":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_-]{0,30}$"}}},"required":["sceneIds"]},"example":{"sceneIds":["s2"]}}}}}},"/api/v1/projects/{id}/estimate":{"post":{"operationId":"projectsEstimate","summary":"Price a project and get a signed quote","description":"Exact price in credits for the current state of the project, and a signed quote valid for 1 hour. A new version of an already generated project is billed as a revision (50% of the base price).","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Estimate a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"credits":{"type":"integer"}}}},"quote":{"type":"string"},"quoteExpiresAt":{"type":"string"},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"balance":{"type":"integer"},"allowed":{"type":"boolean"},"blockers":{"type":"array","items":{}},"overdraft":{"type":"boolean"},"eta":{"type":"object","properties":{"minutesMin":{"type":"integer"},"minutesMax":{"type":"integer"}}}}},"requestId":{"type":"string"}}},"example":{"data":{"total":847,"lines":[{"label":"Standard video (90–120 s)","credits":700},{"label":"Final voice (1,470 characters)","credits":147}],"quote":"eyJ3cyI6IjQ…(signed quote, pass it back unchanged)…","quoteExpiresAt":"2026-10-23T10:12:00.000Z","voiceMode":"final","isRevision":false,"balance":29153,"allowed":true,"blockers":[],"overdraft":false,"eta":{"minutesMin":4,"minutesMax":8}},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:read","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"voiceMode":{"type":"string","enum":["draft","final"],"description":"final = licensed voice (paid plans), draft = free draft voice. Default: final on paid plans."}}},"example":{"voiceMode":"final"}}}}}},"/api/v1/projects/{id}/generate":{"post":{"operationId":"projectsGenerate","summary":"Generate the project with a signed quote","description":"Starts the generation at the quoted price. The quote is required: if it expired or the project changed since the estimate, the response is QUOTE_INVALID and you need to estimate again.","tags":["Projects"],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id","schema":{"type":"string","format":"uuid"},"example":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"202":{"description":"Generate a project","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string"},"stage":{"type":"string"},"stageLabel":{"type":"string"},"progress":{"type":"integer"},"detail":{"type":"string"},"stages":{"type":"object","properties":{}},"voiceMode":{"type":"string"},"isRevision":{"type":"boolean"},"credits":{"type":"integer"},"queuePosition":{"type":"integer"},"cancellable":{"type":"boolean"},"error":{"type":"null"},"videoId":{"type":"null"},"attempt":{"type":"integer"},"source":{"type":"string"},"queuedAt":{"type":"string"},"startedAt":{"type":"string"},"finishedAt":{"type":"null"}}},"projectId":{"type":"string"},"queuePosition":{"type":"integer"}}},"requestId":{"type":"string"}}},"example":{"data":{"job":{"id":"7f3c2a10-5b1e-4c8a-9d2f-0e6b4a1c9d55","projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","status":"queued","stage":"storyboard","stageLabel":"Storyboard","progress":0,"detail":"Scene 4/9","stages":{},"voiceMode":"final","isRevision":false,"credits":847,"queuePosition":0,"cancellable":true,"error":null,"videoId":null,"attempt":1,"source":"api","queuedAt":"2026-10-23T09:12:04.000Z","startedAt":"2026-10-23T09:12:09.000Z","finishedAt":null},"projectId":"2b9e4d71-8c0a-4f3e-a6b5-1d2c3e4f5a6b","queuePosition":1},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"QUOTE_INVALID","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"QUOTE_INVALID","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"402":{"description":"INSUFFICIENT_CREDITS","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INSUFFICIENT_CREDITS","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"type":"string","minLength":10,"maxLength":4000,"description":"Signed quote returned by POST /projects/{id}/estimate (valid 1 h)"}},"required":["quote"]},"example":{"quote":"eyJ3cyI6IjQ…(signed quote, pass it back unchanged)…"}}}}}},"/api/v1/assets":{"post":{"operationId":"assetsUpload","summary":"Upload a logo or a source document","description":"multipart/form-data upload (file field). Logo as PNG, SVG, JPEG or WebP up to 2 MB: use ref (\"asset:<id>\") in brand.logo. Document as PDF, DOCX, TXT or MD up to 20 MB: the extracted text (40,000 characters max) is returned, to pass in brief.input (kind document) or draft.sourceText. The type is detected from the content, not the extension.","tags":["Files"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"201":{"description":"Upload a file","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"ref":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"mime":{"type":"string"},"bytes":{"type":"integer"},"sha256":{"type":"string"},"createdAt":{"type":"string"},"url":{"type":"string"},"text":{"type":"string"},"textLength":{"type":"integer"},"truncated":{"type":"boolean"},"title":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9","ref":"asset:5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9","kind":"document","name":"whitepaper.pdf","mime":"application/pdf","bytes":482113,"sha256":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","createdAt":"2026-10-23T09:00:00.000Z","url":"https://motiongist.com/api/files/assets/…","text":"Whitepaper — CDNs in 2026…","textLength":18342,"truncated":false,"title":"whitepaper"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"413":{"description":"PAYLOAD_TOO_LARGE","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYLOAD_TOO_LARGE","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"assets:write","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"kind":{"type":"string","enum":["logo","document"]}}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"webhooksList","summary":"List webhooks","description":"Webhooks of the workspace with the status of the last delivery. The secret is only shown at creation.","tags":["Webhooks"],"parameters":[],"responses":{"200":{"description":"List webhooks","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"lastStatus":{"type":"null"},"lastDeliveredAt":{"type":"null"},"createdAt":{"type":"string"},"secretPreview":{"type":"string"}}}},"requestId":{"type":"string"}}},"example":{"data":[{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","url":"https://example.com/hooks/motiongist","events":["job.succeeded","job.failed"],"active":true,"lastStatus":null,"lastDeliveredAt":null,"createdAt":"2026-10-23T08:55:00.000Z","secretPreview":"whsec_k3Jd…"}],"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"webhooks:write"},"post":{"operationId":"webhooksCreate","summary":"Create a webhook","description":"Registers a URL that receives the chosen events. The response contains the signing secret (whsec_…), shown only once.","tags":["Webhooks"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"201":{"description":"Create a webhook","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"lastStatus":{"type":"null"},"lastDeliveredAt":{"type":"null"},"createdAt":{"type":"string"},"secret":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","url":"https://example.com/hooks/motiongist","events":["job.succeeded","job.failed"],"active":true,"lastStatus":null,"lastDeliveredAt":null,"createdAt":"2026-10-23T08:55:00.000Z","secret":"whsec_k3JdQ9…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"webhooks:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"Public HTTPS URL that receives the events (signed JSON POST)"},"events":{"description":"Subscribed events (all by default)","maxItems":8,"type":"array","items":{"type":"string","enum":["job.started","job.progress","job.succeeded","job.failed","job.cancelled","video.deleted","post.published","post.failed"]}}},"required":["url"]},"example":{"url":"https://example.com/hooks/motiongist","events":["job.succeeded","job.failed"]}}}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"webhooksDelete","summary":"Delete a webhook","description":"Deletes the webhook; pending deliveries are dropped.","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"string","format":"uuid"},"example":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}],"responses":{"200":{"description":"Delete a webhook","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"requestId":{"type":"string"}}},"example":{"data":{"id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","deleted":true},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"404":{"description":"NOT_FOUND","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"webhooks:write"}},"/api/v1/scripts/generate":{"post":{"operationId":"scriptsGenerate","summary":"Write a narrated script from a topic","description":"Writes a narrated script for a vertical video, in English (default) or French (language), without creating a project. Then pass it in brief.input ({kind: \"script\", text}). Free, limited to 60 AI calls per hour per workspace.","tags":["Scripts & ideas"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Write a script","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"title":{"type":"string"},"script":{"type":"string"},"words":{"type":"integer"},"seconds":{"type":"integer"},"source":{"type":"string"}}},"requestId":{"type":"string"}}},"example":{"data":{"title":"How a CDN works","script":"Your site takes 3 seconds to load in Tokyo? The problem isn’t your server. It’s the distance…","words":246,"seconds":100,"source":"llm"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"string","minLength":3,"maxLength":500},"audience":{"type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"type":"string","enum":["short","standard","full"]},"language":{"type":"string","enum":["fr","en"]},"tone":{"type":"string","maxLength":120},"source":{"description":"Source text whose facts must be respected","type":"string","maxLength":40000}},"required":["topic"]},"example":{"topic":"How a CDN works","audience":"dev","length":"standard","language":"en"}}}}}},"/api/v1/scripts/ideas":{"post":{"operationId":"scriptsIdeas","summary":"Video ideas for a niche","description":"Suggests video ideas (catchy title and visual angle) for a niche. Free, limited to 60 AI calls per hour per workspace.","tags":["Scripts & ideas"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replaying the same request within 24 h returns the first response (X-Idempotent-Replay: true).","schema":{"type":"string"}}],"responses":{"200":{"description":"Video ideas","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"}},"content":{"application/json":{"schema":{"type":"object","required":["data","requestId"],"properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"angle":{"type":"string"}}}}}},"requestId":{"type":"string"}}},"example":{"data":{"ideas":[{"title":"Your password lasts 3 seconds","angle":"A stopwatch cracking longer and longer passwords"}]},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"400":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"401":{"description":"MISSING_API_KEY","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"MISSING_API_KEY","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"403":{"description":"PLAN_REQUIRED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PLAN_REQUIRED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"X-API-Tier":{"$ref":"#/components/headers/X-API-Tier"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"…"},"requestId":"req_3f9a1c2e7b8d4a60"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"niche":{"type":"string","minLength":2,"maxLength":200},"language":{"type":"string","enum":["fr","en"]},"count":{"type":"integer","minimum":1,"maximum":12}},"required":["niche"]},"example":{"niche":"cybersecurity for small businesses","language":"en","count":3}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"REST API key (mg_live_…), created in https://motiongist.com/app/developers. Studio, Team plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Same API key as a bearer token, or an OAuth access token (cat_…)."}},"schemas":{"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","UNAUTHENTICATED","FORBIDDEN","PLAN_REQUIRED","INSUFFICIENT_CREDITS","VALIDATION_ERROR","QUOTE_INVALID","NOT_FOUND","CONFLICT","NOT_CANCELLABLE","CONCURRENCY_LIMIT","RATE_LIMITED","IDEMPOTENCY_CONFLICT","IDEMPOTENCY_IN_PROGRESS","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{}}},"requestId":{"type":"string"}}},"Brief":{"type":"object","properties":{"subject":{"type":"string","minLength":3,"maxLength":200},"input":{"default":{"kind":"idea"},"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"idea"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","const":"script"},"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["kind","text"]},{"type":"object","properties":{"kind":{"type":"string","const":"document"},"text":{"type":"string","minLength":1,"maxLength":40000},"sourceName":{"type":"string","maxLength":200}},"required":["kind","text"]}]},"audience":{"default":"dev","type":"string","enum":["beginner","dev","ops","decision-maker"]},"length":{"default":"standard","type":"string","enum":["short","standard","full"]},"language":{"default":"en","type":"string","enum":["fr","en"]},"voice":{"default":"George","type":"string","maxLength":40},"look":{"default":{"mode":"preset"},"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"preset"},"preset":{"type":"string","maxLength":40}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"brand"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"custom"},"description":{"type":"string","minLength":3,"maxLength":500}},"required":["mode","description"]}]},"brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":24},"site":{"type":"string","maxLength":40},"colors":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"logo":{"type":"string","maxLength":200}},"required":["name","colors"]},"notes":{"default":{"mustShow":[],"avoid":[]},"type":"object","properties":{"mustShow":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"avoid":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"keyMoment":{"type":"string","maxLength":200},"free":{"type":"string","maxLength":1000}}},"mascot":{"default":false,"type":"boolean"},"tier":{"default":"standard","type":"string","enum":["standard","studio"]},"dimension":{"default":"2d","type":"string","enum":["2d","3d"]},"threeD":{"default":"none","type":"string","enum":["none","signature"]}},"required":["subject"]},"WebhookEvent":{"type":"object","description":"Body POSTed to your webhook URL. Header X-Motiongist-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["job.started","job.progress","job.succeeded","job.failed","job.cancelled","video.deleted","post.published","post.failed"]},"created":{"type":"string","format":"date-time"},"data":{"type":"object"}}}},"headers":{"X-Request-Id":{"description":"Unique request id (also in the body). Quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window (60 per 60 s, per key).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO-8601 time when the window resets.","schema":{"type":"string","format":"date-time"}},"X-API-Tier":{"description":"Plan resolved for the key (Studio, Team).","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying (429).","schema":{"type":"integer"}}}},"x-scopes":["jobs:write","jobs:read","videos:read","videos:write","assets:write","webhooks:write"]}