{ "openapi": "3.1.0", "info": { "title": "Vidocu API", "version": "1.14.0", "description": "Turn videos into subtitles, voiceover, help articles and exports.\n\nAuthenticate with an API key (`Authorization: Bearer vdo_live_...`) or an OAuth 2.0 access token. Long-running operations return `202` with a `jobId` you poll via `GET /v1/jobs/{id}`, or you can subscribe to webhooks.\n\nThis spec is generated from the server's own validation schemas.", "contact": { "name": "Vidocu Support", "url": "https://vidocu.ai" }, "license": { "name": "Proprietary", "url": "https://vidocu.ai/terms" } }, "servers": [ { "url": "https://api.vidocu.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "tags": [ { "name": "Videos", "description": "Create, list, update and delete videos" }, { "name": "Operations", "description": "Analyze, export, translate, narrate, document" }, { "name": "Projects", "description": "Project folders" }, { "name": "Tools", "description": "Standalone processing tools" }, { "name": "Governance", "description": "Locks, approvals and review comments" }, { "name": "Courses", "description": "Documents and videos turned into module-based courses" }, { "name": "Brand Kit", "description": "Defaults that keep generated output on-brand" }, { "name": "Webhooks", "description": "Event subscriptions" }, { "name": "Jobs", "description": "Async job status" }, { "name": "Usage", "description": "Balance and limits" }, { "name": "Reference", "description": "Static reference data" } ], "paths": { "/v1/videos/upload": { "post": { "tags": [ "Videos" ], "summary": "Upload a video", "description": "Accepts a direct file (multipart), a `videoUrl` to fetch, or `filename` + `contentType` to get a presigned upload URL.\n\n**Scope:** `videos:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosUpload", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "pattern": "^video\\/" }, "videoUrl": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "videoContext": { "type": "string" }, "projectId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Video created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos": { "get": { "tags": [ "Videos" ], "summary": "List videos", "description": "**Scope:** `videos:read`", "operationId": "getV1Videos", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "in_progress", "completed" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "uncategorized", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "backup", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "none", "taken" ] } }, { "name": "approval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] } }, { "name": "kb", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "published", "not_published", "none" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}": { "get": { "tags": [ "Videos" ], "summary": "Get a video", "description": "**Scope:** `videos:read`", "operationId": "getV1VideosId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Videos" ], "summary": "Update a video", "description": "Rename, refile, or adjust generation context. A locked video can still be moved between projects; any other change is refused.\n\n**Scope:** `videos:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1VideosId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "projectId": { "type": [ "string", "null" ], "minLength": 1 }, "videoContext": { "type": "string", "maxLength": 5000 }, "companyContext": { "type": "string", "maxLength": 5000 }, "subtitleLanguage": { "type": "string", "minLength": 2, "maxLength": 10 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Videos" ], "summary": "Delete a video", "description": "Removes the video and its stored files. Locked videos are refused.\n\n**Scope:** `videos:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1VideosId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "id", "deleted" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/analyze": { "post": { "tags": [ "Operations" ], "summary": "Analyze a video", "description": "**Scope:** `analyze:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdAnalyze", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoContext": { "type": "string", "maxLength": 5000 }, "companyContext": { "type": "string", "maxLength": 5000 }, "language": { "type": "string" }, "tone": { "type": "string" }, "contentStyle": { "type": "string", "enum": [ "how-to", "sop", "promotional", "training", "announcement" ] }, "productName": { "type": "string", "maxLength": 200 }, "scriptSource": { "type": "string", "enum": [ "video", "transcript", "original", "custom" ] }, "customScript": { "type": "string", "maxLength": 100000 }, "scriptSkillId": { "type": "string" }, "forceRefresh": { "type": "boolean" }, "keyEvents": { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "timestamp": { "type": "number", "minimum": 0 } }, "required": [ "text" ], "additionalProperties": false } ] }, "maxItems": 500 }, "analysisModel": { "type": "string", "enum": [ "gemini" ] }, "subtitleModel": { "type": "string", "enum": [ "openai", "gemini" ] }, "autoZoom": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "jobId", "status" ], "additionalProperties": false, "description": "Async operation accepted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/export": { "post": { "tags": [ "Operations" ], "summary": "Export a video", "description": "Per-request overrides layer on top of the video's settings and the Brand Kit (request > video > Brand Kit) and apply to this render only.\n\n**Scope:** `export:write`\n\n**Role permission:** `canExport` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdExport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string" }, "ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:5", "4:3" ] }, "watermark": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" }, "position": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] }, "opacity": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } ] }, "captions": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "properties": { "mode": { "type": "string" }, "position": { "type": "string" }, "positionPercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } ] }, "music": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "volume": { "type": "number", "minimum": 0, "maximum": 1 }, "duckVolume": { "type": "number", "minimum": 0, "maximum": 1 }, "fadeDuration": { "type": "number", "minimum": 0 }, "playInScenes": { "type": "boolean" } }, "additionalProperties": false } ] }, "openingSceneUrl": { "type": [ "string", "null" ], "format": "uri" }, "closingSceneUrl": { "type": [ "string", "null" ], "format": "uri" }, "zooms": { "type": "boolean" }, "elements": { "type": "boolean" }, "reframe": { "type": "boolean" }, "slides": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "maxItems": 200 }, "avatarSettings": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "object", "properties": { "avatarId": { "type": "string" }, "voiceId": { "type": "string" }, "layout": { "type": "string" }, "sizePercent": { "type": "number", "minimum": 1, "maximum": 100 }, "shape": { "type": "string", "enum": [ "circle", "rounded", "square" ] }, "backgroundColor": { "type": "string" }, "zoom": { "type": "number", "minimum": 1 }, "offsetY": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } ] } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "jobId", "status" ], "additionalProperties": false, "description": "Async operation accepted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/translate": { "post": { "tags": [ "Operations" ], "summary": "Translate a video", "description": "**Scope:** `translate:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdTranslate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string", "minLength": 2 } }, "required": [ "language" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "jobId", "status" ], "additionalProperties": false, "description": "Async operation accepted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/subtitles": { "get": { "tags": [ "Operations" ], "summary": "Get subtitles", "description": "**Scope:** `subtitles:read`", "operationId": "getV1VideosIdSubtitles", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "srt" ], "default": "json" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/voiceover": { "post": { "tags": [ "Operations" ], "summary": "Generate a voiceover", "description": "**Scope:** `voiceover:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdVoiceover", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "voiceId": { "type": "string", "minLength": 1 }, "language": { "type": "string" }, "sentencePauseSeconds": { "type": "number", "minimum": 0, "maximum": 3 }, "applyPronunciations": { "type": "boolean", "default": true }, "model": { "type": "string", "enum": [ "auto", "eleven_multilingual_v2", "eleven_v3" ] }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.3 }, "stability": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "voiceId" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "jobId", "status" ], "additionalProperties": false, "description": "Async operation accepted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/article": { "post": { "tags": [ "Operations" ], "summary": "Generate a help article", "description": "Synchronous — returns the article inline.\n\n**Scope:** `article:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "regenerate": { "type": "boolean", "default": false }, "language": { "type": "string" }, "instructions": { "type": "string", "maxLength": 2000 }, "format": { "type": "string", "enum": [ "markdown", "html" ], "default": "markdown" }, "style": { "type": "string", "maxLength": 40 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Operations" ], "summary": "Get the help article", "description": "The stored article. Returns 404 if none has been generated yet.\n\n**Scope:** `article:read`", "operationId": "getV1VideosIdArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "markdown", "html" ], "default": "markdown" } }, { "name": "style", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/process": { "post": { "tags": [ "Operations" ], "summary": "One-shot process", "description": "Upload, analyze, and optionally voiceover / export / article / translate.\n\n**Scope:** `process:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosProcess", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "context": { "type": "string" }, "companyContext": { "type": "string" }, "language": { "type": "string" }, "tone": { "type": "string" }, "voiceId": { "type": "string" }, "projectId": { "type": "string", "minLength": 1 }, "generate": { "type": "object", "properties": { "analysis": { "type": "boolean", "default": true }, "voiceover": { "type": "boolean", "default": false }, "export": { "type": "boolean", "default": false }, "helpArticle": { "type": "boolean", "default": false }, "translation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "languages": { "type": "array", "items": { "type": "string", "minLength": 2 }, "default": [] } }, "required": [ "enabled" ], "additionalProperties": false, "default": { "enabled": false, "languages": [] } } }, "additionalProperties": false, "default": { "analysis": true } }, "exportSettings": { "type": "object", "additionalProperties": {} } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "videoId": { "type": "string" }, "projectId": { "type": "string" }, "status": { "type": "string", "enum": [ "processing" ] } }, "required": [ "jobId", "videoId", "projectId", "status" ], "additionalProperties": false, "description": "Upload accepted and processing started." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/script": { "get": { "tags": [ "Operations" ], "summary": "Get the script", "description": "The timed lines that are burned in as subtitles and spoken as narration.\n\n**Scope:** `subtitles:read`", "operationId": "getV1VideosIdScript", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Operations" ], "summary": "Replace the script", "description": "Full replacement, not a patch. Editing a line's text invalidates narration already generated for it; the response reports how many lines were affected.\n\n**Scope:** `subtitles:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "putV1VideosIdScript", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "text": { "type": "string" } }, "required": [ "start", "end", "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5000 } }, "required": [ "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/download": { "get": { "tags": [ "Videos" ], "summary": "Get a file URL", "description": "URL of a stored artifact — exported video, source, voiceover audio, SRT or thumbnail.\n\n**Scope:** `videos:read`", "operationId": "getV1VideosIdDownload", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "video", "source", "audio", "srt", "vtt", "thumbnail" ], "default": "video" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Secrets are not returned — they are shown once, at creation.\n\n**Scope:** `webhooks:read`", "operationId": "getV1Webhooks", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "The signing secret is returned ONCE in this response. HTTPS is required.\n\n**Scope:** `webhooks:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Webhooks", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "video.analyzed", "video.translated", "subtitles.generated", "voiceover.generated", "article.generated", "export.completed", "export.failed", "tool.completed", "tool.failed", "process.completed", "process.failed" ] }, "minItems": 1 } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Webhook created; includes the secret" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Re-enabling also resets the consecutive-failure count.\n\n**Scope:** `webhooks:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1WebhooksId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "video.analyzed", "video.translated", "subtitles.generated", "voiceover.generated", "article.generated", "export.completed", "export.failed", "tool.completed", "tool.failed", "process.completed", "process.failed" ] }, "minItems": 1 }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "**Scope:** `webhooks:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1WebhooksId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "id", "deleted" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects": { "post": { "tags": [ "Projects" ], "summary": "Create a project folder", "description": "**Scope:** `projects:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Projects", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "thumbnailUrl": { "type": "string", "format": "uri" }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "workspace", "restricted", "readonly" ] }, "memberIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "default": [] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Project created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Projects" ], "summary": "List project folders", "description": "**Scope:** `projects:read`", "operationId": "getV1Projects", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "updatedAt", "createdAt", "name" ], "default": "updatedAt" } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get a project folder", "description": "**Scope:** `projects:read`", "operationId": "getV1ProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Projects" ], "summary": "Update a project folder", "description": "**Scope:** `projects:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1ProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "workspace", "restricted", "readonly" ] }, "memberIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "default": [] } }, "required": [ "mode" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete a project folder", "description": "`cascade=true` also deletes the videos and their files. Refused if the project holds any locked video.\n\n**Scope:** `projects:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1ProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cascade", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "cascade": { "type": "boolean", "description": "True when the project's videos were deleted too." }, "deletedVideos": { "type": "integer" }, "uncategorizedVideos": { "type": "integer", "description": "Videos moved out of the project instead of deleted." } }, "required": [ "success", "cascade", "deletedVideos", "uncategorizedVideos" ], "additionalProperties": false, "description": "Project deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The video's content is locked and can't be changed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tools": { "get": { "tags": [ "Tools" ], "summary": "List tools", "description": "Generated from the live registry. Check `apiSupported` before executing.\n\n**Scope:** `tools:read`", "operationId": "getV1Tools", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tools/{type}": { "get": { "tags": [ "Tools" ], "summary": "Get a tool", "description": "**Scope:** `tools:read`", "operationId": "getV1ToolsType", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tools/{type}/execute": { "post": { "tags": [ "Tools" ], "summary": "Execute a tool", "description": "Input is validated against the tool's own parameter schema from GET /v1/tools/:type. Charged on success at the tool's own rate.\n\n**Scope:** `tools:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ToolsTypeExecute", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Poll this via GET /v1/jobs/{id}." }, "status": { "type": "string", "enum": [ "pending" ] }, "tool": { "type": "string", "description": "The tool type that was dispatched." } }, "required": [ "jobId", "status", "tool" ], "additionalProperties": false, "description": "Tool execution accepted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/lock": { "post": { "tags": [ "Governance" ], "summary": "Lock a video", "description": "Freezes the package, cascading to its training module and KB articles. Already-locked is a no-op, not an error.\n\n**Scope:** `locks:write`\n\n**Role permission:** `canLock` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdLock", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Governance" ], "summary": "Unlock a video", "description": "Refused while an approval round is open — withdraw it first.\n\n**Scope:** `locks:write`\n\n**Role permission:** `canLock` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1VideosIdLock", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locked": { "type": "boolean", "enum": [ false ] }, "unlocked": { "type": "boolean", "enum": [ true ] } }, "required": [ "locked", "unlocked" ], "additionalProperties": false, "description": "Lock released." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "An approval round is open, or it isn't locked" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/approvals": { "post": { "tags": [ "Governance" ], "summary": "Request approval", "description": "Approvers are workspace member user ids. Every one must approve; one rejection fails the round.\n\n**Scope:** `approvals:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdApprovals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 20 }, "message": { "type": "string", "maxLength": 2000 } }, "required": [ "approvers" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Approval requested" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Governance" ], "summary": "List a video's approval rounds", "description": "**Scope:** `approvals:read`", "operationId": "getV1VideosIdApprovals", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/approvals": { "get": { "tags": [ "Governance" ], "summary": "List approval requests", "description": "**Scope:** `approvals:read`", "operationId": "getV1Approvals", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] } }, { "name": "videoId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/approvals/{id}/decide": { "post": { "tags": [ "Governance" ], "summary": "Approve or reject", "description": "Only a named approver can decide, and only once.\n\n**Scope:** `approvals:write`", "operationId": "postV1ApprovalsIdDecide", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "comment": { "type": "string", "maxLength": 2000 } }, "required": [ "decision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not an approver, or already decided" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/approvals/{id}/withdraw": { "post": { "tags": [ "Governance" ], "summary": "Withdraw an approval round", "description": "Clears the video's approval state. Required before unlocking.\n\n**Scope:** `approvals:write`", "operationId": "postV1ApprovalsIdWithdraw", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/comments": { "get": { "tags": [ "Governance" ], "summary": "List comments", "description": "**Scope:** `comments:read`", "operationId": "getV1VideosIdComments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Governance" ], "summary": "Add a comment", "description": "Optionally pinned to a timestamp in the video.\n\n**Scope:** `comments:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1VideosIdComments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "timestamp": { "type": "number", "minimum": 0 } }, "required": [ "text" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Comment added" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/comments/{commentId}": { "delete": { "tags": [ "Governance" ], "summary": "Delete a comment", "description": "**Scope:** `comments:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1VideosIdCommentsCommentId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "id", "deleted" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/assets": { "get": { "tags": [ "Brand Kit" ], "summary": "List brand assets", "description": "Opening and closing scenes, watermarks, music, backgrounds.\n\n**Scope:** `brand_kit:read`", "operationId": "getV1Brand-kitAssets", "parameters": [ { "name": "assetType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "opening_scene", "closing_scene", "watermark", "background_music", "background", "avatar_training" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Brand Kit" ], "summary": "Register a brand asset", "description": "Records an already-uploaded file. Get a URL from POST /v1/upload-url first.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Brand-kitAssets", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assetType": { "type": "string", "enum": [ "opening_scene", "closing_scene", "watermark", "background_music", "background", "avatar_training" ] }, "fileType": { "type": "string", "enum": [ "video", "image", "audio" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" }, "duration": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "fileSize": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "assetType", "fileType", "name", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Registered" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/assets/{id}": { "delete": { "tags": [ "Brand Kit" ], "summary": "Remove a brand asset", "description": "Removes the record; the stored file is left alone since other videos may use it.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Brand-kitAssetsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/templates": { "get": { "tags": [ "Studio" ], "summary": "List templates", "description": "The workspace's own templates plus the global gallery.\n\n**Scope:** `studio:read`", "operationId": "getV1StudioTemplates", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/templates/{id}/use": { "post": { "tags": [ "Studio" ], "summary": "Start a project from a template", "description": "**Scope:** `studio:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1StudioTemplatesIdUse", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Project created from the template" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects": { "get": { "tags": [ "Studio" ], "summary": "List Studio projects", "description": "Timeline counts only — fetch one project for its tracks and clips.\n\n**Scope:** `studio:read`", "operationId": "getV1StudioProjects", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Studio" ], "summary": "Create an empty Studio project", "description": "**Scope:** `studio:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1StudioProjects", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "projectId": { "type": "string", "description": "Project folder to file it under" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects/{id}": { "get": { "tags": [ "Studio" ], "summary": "Get a Studio project", "description": "Includes the full timeline: tracks, clips and media.\n\n**Scope:** `studio:read`", "operationId": "getV1StudioProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Studio" ], "summary": "Update a project's metadata", "description": "Name, folder and canvas settings. The timeline has its own endpoint.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1StudioProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "projectId": { "type": [ "string", "null" ] }, "canvasWidth": { "type": "integer", "minimum": 16, "maximum": 7680 }, "canvasHeight": { "type": "integer", "minimum": 16, "maximum": 7680 }, "canvasRatio": { "type": "string", "maxLength": 12 }, "fps": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Studio" ], "summary": "Delete a Studio project", "description": "A video already exported from it is a separate object and is kept.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1StudioProjectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects/{id}/timeline": { "put": { "tags": [ "Studio" ], "summary": "Replace a project's timeline", "description": "Whole-document replacement of tracks, clips and media. Validated against the editor's types and checked for referential integrity — every clip must sit on a track that exists, and media clips must point at media that exists. totalDuration is derived, not taken from the request.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "putV1StudioProjectsIdTimeline", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "main", "overlay", "audio" ] }, "name": { "type": "string", "maxLength": 120 }, "order": { "type": "integer", "minimum": 0, "maximum": 100 }, "locked": { "type": "boolean" }, "visible": { "type": "boolean" }, "volume": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "id", "type", "name", "order", "locked", "visible", "volume" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "video", "image", "audio", "text", "shape", "emoji", "slide" ] }, "mediaId": { "type": "string" }, "trackId": { "type": "string", "minLength": 1 }, "startOnTimeline": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "sourceStartTime": { "type": "number", "minimum": 0 }, "sourceEndTime": { "type": "number", "minimum": 0 }, "speed": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 10 }, "volume": { "type": "number", "minimum": 0, "maximum": 100 }, "opacity": { "type": "number", "minimum": 0, "maximum": 100 }, "fitMode": { "type": "string", "enum": [ "fill", "fit" ] }, "fillZoom": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "fillOffsetX": { "type": "number", "minimum": -50, "maximum": 50 }, "fillOffsetY": { "type": "number", "minimum": -50, "maximum": 50 }, "crop": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "rotation": { "type": "number" }, "flipH": { "type": "boolean" }, "flipV": { "type": "boolean" }, "brightness": { "type": "number", "minimum": -100, "maximum": 100 }, "contrast": { "type": "number", "minimum": -100, "maximum": 100 }, "saturation": { "type": "number", "minimum": -100, "maximum": 100 }, "hueRotate": { "type": "number", "minimum": 0, "maximum": 360 }, "sepia": { "type": "number", "minimum": 0, "maximum": 100 }, "grayscale": { "type": "number", "minimum": 0, "maximum": 100 }, "blur": { "type": "number", "minimum": 0, "maximum": 20 }, "filterPreset": { "type": "string", "maxLength": 80 }, "fadeIn": { "type": "number", "minimum": 0 }, "fadeOut": { "type": "number", "minimum": 0 }, "duckUnderVoiceover": { "type": "boolean" }, "duckVolume": { "type": "number", "minimum": 0, "maximum": 100 }, "duckFade": { "type": "number", "minimum": 0 }, "position": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false }, "size": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "width", "height" ], "additionalProperties": false }, "caption": { "type": "boolean" }, "textStyle": { "type": "object", "additionalProperties": {} }, "shapeStyle": { "type": "object", "additionalProperties": {} }, "slide": { "type": "object", "additionalProperties": {} }, "transition": { "type": "object", "additionalProperties": {} }, "voiceover": { "type": "object", "additionalProperties": {} }, "zoom": { "type": "object", "additionalProperties": {} }, "zooms": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "id", "type", "trackId", "startOnTimeline", "duration", "sourceStartTime", "sourceEndTime", "speed", "volume", "opacity" ], "additionalProperties": false }, "maxItems": 2000 }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "maxLength": 300 }, "type": { "type": "string", "enum": [ "video", "image", "audio" ] }, "url": { "type": "string", "format": "uri" }, "thumbnailUrl": { "type": "string", "format": "uri" }, "duration": { "type": "number", "minimum": 0 }, "width": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "height": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "fileSize": { "type": "integer", "minimum": 0 }, "uploadedAt": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "imported": { "type": "boolean" } }, "required": [ "id", "name", "type", "url" ], "additionalProperties": false }, "maxItems": 1000 } }, "required": [ "tracks", "clips", "media" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects/{id}/duplicate": { "post": { "tags": [ "Studio" ], "summary": "Duplicate a project", "description": "The copy never inherits the original's share link or export state.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1StudioProjectsIdDuplicate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Duplicated" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects/{id}/export": { "post": { "tags": [ "Studio" ], "summary": "Render a Studio project", "description": "Renders the timeline to a video on Remotion Lambda. Takes minutes — poll the returned jobId. Counts as one export against the plan; free plans get the Vidocu watermark.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1StudioProjectsIdExport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Render started" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Export limit reached for this plan" }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nothing on the timeline to export" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/studio/projects/{id}/share": { "post": { "tags": [ "Studio" ], "summary": "Get or create a share link", "description": "Minting is idempotent — one token per project, forever. Visibility is a separate switch.\n\n**Scope:** `studio:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1StudioProjectsIdShare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "type": "boolean", "description": "Defaults to true" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules": { "get": { "tags": [ "Training Modules" ], "summary": "List training modules", "description": "Answer keys are never included in the list — fetch a single module for those.\n\n**Scope:** `modules:read`", "operationId": "getV1Modules", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/generate": { "post": { "tags": [ "Training Modules" ], "summary": "Generate a module", "description": "From a video or a knowledge-base article. Regenerating replaces the source's existing module rather than adding a second one.\n\n**Scope:** `modules:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ModulesGenerate", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string" }, "articleId": { "type": "string" }, "questionCount": { "type": "integer", "minimum": 1, "maximum": 50 }, "instructions": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Module generated" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}": { "get": { "tags": [ "Training Modules" ], "summary": "Get a module", "description": "Includes answer keys unless forLearner=true.\n\n**Scope:** `modules:read`", "operationId": "getV1ModulesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "forLearner", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Training Modules" ], "summary": "Update a module", "description": "**Scope:** `modules:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1ModulesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "state": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "settings": { "type": "object", "properties": { "recordAttempts": { "type": "boolean" }, "participantIdentity": { "type": "string", "enum": [ "anonymous", "name", "email_name", "auth" ] }, "availableFrom": { "type": [ "string", "null" ], "format": "date-time" }, "availableUntil": { "type": [ "string", "null" ], "format": "date-time" }, "requiresTrainerApproval": { "type": "boolean" }, "mandatory": { "type": "boolean" }, "qualificationValidDays": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": false }, "quiz": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "multiple_choice", "true_false" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "type": "string", "maxLength": 2000 }, "options": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "minItems": 2, "maxItems": 10 }, "correctIndex": { "type": "integer", "minimum": 0 }, "explanation": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "type", "prompt", "options", "correctIndex" ], "additionalProperties": false }, "minItems": 1, "maxItems": 200 }, "passingScore": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "questions", "passingScore" ], "additionalProperties": false }, "keywords": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 20 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "The module is locked" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Training Modules" ], "summary": "Delete a module", "description": "**Scope:** `modules:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1ModulesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Locked modules are permanent records" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/lock": { "post": { "tags": [ "Training Modules" ], "summary": "Lock a module", "description": "Freezes it permanently. Already-locked is a no-op.\n\n**Scope:** `modules:write`\n\n**Role permission:** `canLock` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ModulesIdLock", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/translate": { "post": { "tags": [ "Training Modules" ], "summary": "Translate a module", "description": "**Scope:** `modules:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ModulesIdTranslate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetLocales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" }, "minItems": 1, "maxItems": 20 } }, "required": [ "targetLocales" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/translations": { "get": { "tags": [ "Training Modules" ], "summary": "List a module's translations", "description": "Each carries `stale`, set when the source changed after translation.\n\n**Scope:** `modules:read`", "operationId": "getV1ModulesIdTranslations", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/submit": { "post": { "tags": [ "Training Modules" ], "summary": "Record an attempt", "description": "Graded server-side against the answer keys. For LMS and intranet integrations.\n\n**Scope:** `modules:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ModulesIdSubmit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1 }, "selectedIndex": { "type": "integer", "minimum": 0, "maximum": 50 } }, "required": [ "questionId", "selectedIndex" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 200 }, "locale": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" } }, "required": [ "answers" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Graded and recorded" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/results": { "get": { "tags": [ "Training Modules" ], "summary": "Attempts and pass rate", "description": "**Scope:** `modules:read`", "operationId": "getV1ModulesIdResults", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/passers": { "get": { "tags": [ "Training Modules" ], "summary": "Who has passed", "description": "Distinct people by email; anonymous attempts are excluded.\n\n**Scope:** `modules:read`", "operationId": "getV1ModulesIdPassers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/{id}/qualifications": { "get": { "tags": [ "Training Modules" ], "summary": "Who is signed off", "description": "**Scope:** `modules:read`", "operationId": "getV1ModulesIdQualifications", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Training Modules" ], "summary": "Sign someone off", "description": "A trainer's assertion, recorded against the acting user. Calling twice returns the existing record.\n\n**Scope:** `modules:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1ModulesIdQualifications", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Recorded" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/analytics": { "get": { "tags": [ "Training Modules" ], "summary": "Per-module rollup", "description": "**Scope:** `modules:read`", "operationId": "getV1ModulesAnalytics", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/analytics/by-person": { "get": { "tags": [ "Training Modules" ], "summary": "Per-person rollup", "description": "**Scope:** `modules:read`", "operationId": "getV1ModulesAnalyticsBy-person", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/analytics/signoffs": { "get": { "tags": [ "Training Modules" ], "summary": "Recent trainer sign-offs", "description": "**Scope:** `modules:read`", "operationId": "getV1ModulesAnalyticsSignoffs", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/planner": { "get": { "tags": [ "Training Modules" ], "summary": "Training planner grid", "description": "Every training against every person on the roster, most urgent first. Unlike the analytics endpoints, this includes people who have never attempted a training — which is the only way to see who still has not done one.\n\n**Scope:** `modules:read`", "operationId": "getV1ModulesPlanner", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "moduleId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "passed", "renewed", "expired", "awaiting_signoff", "in_progress", "not_started" ] } }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "mandatory", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "readiness", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "approved", "published" ] } }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "applicability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "undecided", "applicable", "not_applicable" ] } }, { "name": "includeNa", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "urgency", "training", "person", "status", "expires", "deadline" ] } }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/planner/deadline": { "put": { "tags": [ "Training Modules" ], "summary": "Set or clear a due date", "description": "A deadline is an expectation rather than a record, so it can be set on somebody who has never attempted the training. Pass dueAt: null to clear it.\n\n**Scope:** `modules:write`", "operationId": "putV1ModulesPlannerDeadline", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "moduleId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "dueAt": { "type": [ "string", "null" ] }, "applicability": { "type": "string", "enum": [ "undecided", "applicable", "not_applicable" ] }, "notApplicable": { "type": "boolean" } }, "required": [ "moduleId", "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/modules/people": { "get": { "tags": [ "Training Modules" ], "summary": "Training roster", "description": "The people this workspace trains, plus anyone who has training records but is not on the roster yet.\n\n**Scope:** `modules:read`", "operationId": "getV1ModulesPeople", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Training Modules" ], "summary": "Add a person to the roster", "description": "Adds somebody before they have trained at all, which is what makes 'has never done it' visible for a new employee. Idempotent on email.\n\n**Scope:** `modules:write`", "operationId": "postV1ModulesPeople", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 200 } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes": { "get": { "tags": [ "Remix" ], "summary": "List remixes", "description": "**Scope:** `remixes:read`", "operationId": "getV1Remixes", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "queued", "analyzing", "ready", "failed" ] } }, { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Remix" ], "summary": "Create a remix", "description": "From a workspace video (videoId) or an external URL (videoUrl + durationSec). Creating doesn't analyze — call analyze next.\n\n**Scope:** `remixes:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Remixes", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "videoId": { "type": "string", "minLength": 1 }, "videoUrl": { "type": "string", "format": "uri" }, "durationSec": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 43200 }, "projectId": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough balance for a video this long" }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes/{id}": { "get": { "tags": [ "Remix" ], "summary": "Get a remix", "description": "Includes the full analysis once it's ready.\n\n**Scope:** `remixes:read`", "operationId": "getV1RemixesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Remix" ], "summary": "Update a remix", "description": "Title and project folder. Status, analysis and exports belong to the pipeline.\n\n**Scope:** `remixes:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1RemixesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "projectId": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Remix" ], "summary": "Delete a remix", "description": "**Scope:** `remixes:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1RemixesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Analysis is running" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes/{id}/analyze": { "post": { "tags": [ "Remix" ], "summary": "Analyze a remix", "description": "Finds the shorts and drafts the copy. One analysis runs per workspace at a time; a second returns status \"queued\" and starts on its own.\n\n**Scope:** `remixes:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1RemixesIdAnalyze", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Analyzing, or queued behind another" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes/{id}/export": { "post": { "tags": [ "Remix" ], "summary": "Export a remix output", "description": "Text outputs (blog, linkedin, x) return their content immediately; video outputs (short, yt-trim) return a job to poll. Each export counts as one against the plan.\n\n**Scope:** `remixes:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1RemixesIdExport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "outputType": { "type": "string", "enum": [ "yt-trim", "short", "blog", "linkedin", "x" ] }, "shortId": { "type": "string" }, "variantIndex": { "type": "integer", "minimum": 0, "maximum": 20 } }, "required": [ "outputType" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Video export started" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Export limit reached for this plan" }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The remix isn't analyzed yet" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes/{id}/regenerate": { "post": { "tags": [ "Remix" ], "summary": "Regenerate a text output", "description": "Rewrites the blog post, LinkedIn posts or X thread from the analyzed transcript. Free — no credit charge and it doesn't count as an export.\n\n**Scope:** `remixes:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1RemixesIdRegenerate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "outputType": { "type": "string", "enum": [ "blog", "linkedin", "x" ] } }, "required": [ "outputType" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remixes/{id}/exports": { "get": { "tags": [ "Remix" ], "summary": "List a remix's exports", "description": "**Scope:** `remixes:read`", "operationId": "getV1RemixesIdExports", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recordings": { "get": { "tags": [ "AI Recorder" ], "summary": "List recordings", "description": "**Scope:** `recordings:read`", "operationId": "getV1Recordings", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "AI Recorder" ], "summary": "Start a recording", "description": "Describe a flow and the agent records it. Long-running — poll the job. Billed per minute of finished video; failed and aborted jobs are free.\n\n**Scope:** `recordings:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Recordings", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "What the recording should show" }, "url": { "type": "string", "format": "uri" }, "device": { "type": "string", "enum": [ "desktop", "mobile" ] }, "pacing": { "type": "string", "enum": [ "relaxed", "standard", "brisk" ] }, "mode": { "type": "string", "enum": [ "regular", "follow", "steps" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 2000 }, "url": { "type": "string", "format": "uri" } }, "required": [ "instruction" ], "additionalProperties": false }, "maxItems": 50 } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Recording started" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The recorder judged the prompt not actionable" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recordings/{jobId}": { "get": { "tags": [ "AI Recorder" ], "summary": "Get a recording", "description": "Includes the aborted and partial flags.\n\n**Scope:** `recordings:read`", "operationId": "getV1RecordingsJobId", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "AI Recorder" ], "summary": "Delete a recording", "description": "**Scope:** `recordings:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1RecordingsJobId", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "jobId": { "type": "string" } }, "required": [ "deleted", "jobId" ], "additionalProperties": false, "description": "Recording deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recordings/{jobId}/download": { "get": { "tags": [ "AI Recorder" ], "summary": "Get a download URL", "description": "Time-limited URL for the finished file.\n\n**Scope:** `recordings:read`", "operationId": "getV1RecordingsJobIdDownload", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The recording hasn't completed" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recordings/{jobId}/input": { "post": { "tags": [ "AI Recorder" ], "summary": "Answer a blocked recording", "description": "Supply a value the agent paused for, such as a one-time code.\n\n**Scope:** `recordings:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1RecordingsJobIdInput", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recorder-sessions": { "get": { "tags": [ "AI Recorder" ], "summary": "List saved logins", "description": "By domain. Each item carries its setupPrompt (off-camera setup run before every recording and screenshot on that site, or null). Stored cookies are never returned.\n\n**Scope:** `recordings:read`", "operationId": "getV1Recorder-sessions", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recorder-sessions/{domain}": { "patch": { "tags": [ "AI Recorder" ], "summary": "Set a saved login's setup instructions", "description": "Steps the recorder replays on this site before every recording and screenshot, off camera. Send null to clear. 404 when there is no saved login for the domain.\n\n**Scope:** `recordings:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Recorder-sessionsDomain", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "setupPrompt": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Steps the recorder performs on this site before every recording and screenshot, off camera (e.g. \"Switch to the Acme workspace and close the welcome banner\"). null clears it. A recording request's own setupPrompt takes precedence." } }, "required": [ "setupPrompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "AI Recorder" ], "summary": "Forget a saved login", "description": "**Scope:** `recordings:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Recorder-sessionsDomain", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "domain": { "type": "string" } }, "required": [ "deleted", "domain" ], "additionalProperties": false, "description": "Saved recorder session deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base": { "get": { "tags": [ "Knowledge Center" ], "summary": "Get the knowledge base", "description": "One per workspace. 404 until one is created.\n\n**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-base", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Knowledge Center" ], "summary": "Create the knowledge base", "description": "The slug becomes the public address, {slug}.vidocu.help.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-base", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "defaultLocale": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" } }, "required": [ "name", "slug" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The workspace already has one, or the slug is taken" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Knowledge Center" ], "summary": "Update the knowledge base", "description": "Changing the slug changes the public URL — add a redirect for existing links.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Knowledge-base", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "defaultLocale": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" }, "enabledLocales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" }, "maxItems": 60 }, "visibility": { "type": "string", "enum": [ "public", "staff", "customers" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Knowledge Center" ], "summary": "Take the knowledge base offline", "description": "Soft delete: the site stops resolving, articles are retained.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Knowledge-base", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/sections": { "get": { "tags": [ "Knowledge Center" ], "summary": "List sections", "description": "**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-baseSections", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Knowledge Center" ], "summary": "Create a section", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseSections", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 500 }, "visibility": { "type": "string", "enum": [ "public", "staff", "customers" ] }, "parentId": { "type": [ "string", "null" ], "minLength": 1, "description": "Id of a top-level section to nest under. null (or omitted) makes this a top-level section. One level deep only." } }, "required": [ "name", "slug" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/sections/{id}": { "patch": { "tags": [ "Knowledge Center" ], "summary": "Update a section", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Knowledge-baseSectionsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "visibility": { "type": "string", "enum": [ "public", "staff", "customers" ] }, "position": { "type": "integer", "minimum": 0 }, "parentId": { "type": [ "string", "null" ], "minLength": 1, "description": "Id of a top-level section to nest under. null (or omitted) makes this a top-level section. One level deep only." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Knowledge Center" ], "summary": "Delete a section", "description": "Refused while it still holds articles.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Knowledge-baseSectionsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The section still has articles" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/sections/reorder": { "post": { "tags": [ "Knowledge Center" ], "summary": "Reorder sections", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseSectionsReorder", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 200 } }, "required": [ "sectionIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/articles": { "get": { "tags": [ "Knowledge Center" ], "summary": "List articles", "description": "Metadata only — fetch one article for its content.\n\n**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-baseArticles", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, { "name": "sectionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "staff", "customers" ] } }, { "name": "linkedVideoId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Knowledge Center" ], "summary": "Create an article", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseArticles", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "content": { "type": "string", "minLength": 1, "maxLength": 500000 }, "excerpt": { "type": "string", "maxLength": 1000 }, "state": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "visibility": { "type": "string", "enum": [ "public", "staff", "customers" ] }, "linkedVideoId": { "type": "string" } }, "required": [ "sectionId", "title", "slug", "content" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug taken, or the linked video is awaiting approval" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/articles/{id}": { "get": { "tags": [ "Knowledge Center" ], "summary": "Get an article", "description": "Includes the Markdown content.\n\n**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-baseArticlesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Knowledge Center" ], "summary": "Update an article", "description": "Locked articles accept only sectionId, state and seo.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Knowledge-baseArticlesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "slug": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "content": { "type": "string", "minLength": 1, "maxLength": 500000 }, "excerpt": { "type": [ "string", "null" ], "maxLength": 1000 }, "state": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "visibility": { "type": "string", "enum": [ "public", "staff", "customers" ] }, "seo": { "type": "object", "properties": { "metaTitle": { "type": "string", "maxLength": 200 }, "metaDescription": { "type": "string", "maxLength": 400 }, "ogImageUrl": { "type": "string", "format": "uri" }, "canonicalUrl": { "type": "string", "format": "uri" }, "noindex": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug taken, or the linked video is awaiting approval" }, "423": { "description": "The article is locked" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Knowledge Center" ], "summary": "Delete an article", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Knowledge-baseArticlesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Locked articles are permanent records" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/articles/from-video": { "post": { "tags": [ "Knowledge Center" ], "summary": "Import an article from a video", "description": "The video must already have a help article. A locked video produces a locked article.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseArticlesFrom-video", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string", "minLength": 1 }, "sectionId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, "required": [ "videoId", "sectionId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Imported" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The video has no help article yet" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/articles/{id}/translate": { "post": { "tags": [ "Knowledge Center" ], "summary": "Translate an article", "description": "Targets must be enabled locales. Draws on the add-on's AI credit pool.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseArticlesIdTranslate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetLocales": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" }, "minItems": 1, "maxItems": 20 } }, "required": [ "targetLocales" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/ask": { "post": { "tags": [ "Knowledge Center" ], "summary": "Ask the knowledge base", "description": "Retrieval-grounded answer with citations, for support-bot integrations.\n\n**Scope:** `knowledge_base:read`", "operationId": "postV1Knowledge-baseAsk", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "locale": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$" } }, "required": [ "question" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/reindex": { "post": { "tags": [ "Knowledge Center" ], "summary": "Rebuild search embeddings", "description": "Only needed after a bulk import — publishing indexes automatically.\n\n**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseReindex", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/redirects": { "get": { "tags": [ "Knowledge Center" ], "summary": "List redirects", "description": "**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-baseRedirects", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Knowledge Center" ], "summary": "Create a redirect", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Knowledge-baseRedirects", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromPath": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/" }, "toPath": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/" } }, "required": [ "fromPath", "toPath" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/redirects/{id}": { "delete": { "tags": [ "Knowledge Center" ], "summary": "Delete a redirect", "description": "**Scope:** `knowledge_base:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Knowledge-baseRedirectsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" } }, "required": [ "deleted", "id" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/knowledge-base/analytics": { "get": { "tags": [ "Knowledge Center" ], "summary": "Knowledge base analytics", "description": "Article counts, most-viewed articles, top searches and zero-result searches.\n\n**Scope:** `knowledge_base:read`", "operationId": "getV1Knowledge-baseAnalytics", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/courses": { "get": { "tags": [ "Courses" ], "summary": "List courses", "description": "**Scope:** `courses:read`", "operationId": "getV1Courses", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "uploading", "extracting", "planning", "plan_ready", "failed" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Courses" ], "summary": "Create a course", "description": "From a document URL or an existing video. Planning starts immediately; poll the returned jobId.\n\n**Scope:** `courses:write`\n\n**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Courses", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileUrl": { "type": "string", "format": "uri" }, "filename": { "type": "string", "minLength": 1, "maxLength": 300 }, "sourceVideoId": { "type": "string", "minLength": 1 }, "instructions": { "type": "string", "maxLength": 5000 } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Course created; planning started" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/courses/{id}": { "get": { "tags": [ "Courses" ], "summary": "Get a course", "description": "Includes its modules.\n\n**Scope:** `courses:read`", "operationId": "getV1CoursesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Courses" ], "summary": "Update a course", "description": "Title, planner instructions, project folder. Modules and status are owned by the pipeline.\n\n**Scope:** `courses:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1CoursesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "userInstructions": { "type": "string", "maxLength": 5000 }, "projectId": { "type": [ "string", "null" ], "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Courses" ], "summary": "Delete a course", "description": "Videos already generated from its modules are kept.\n\n**Scope:** `courses:write`\n\n**Role permission:** `canDelete` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1CoursesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] }, "generatedVideosKept": { "type": "integer", "description": "Videos generated by the course that outlive it." } }, "required": [ "success", "id", "deleted", "generatedVideosKept" ], "additionalProperties": false, "description": "Course deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/courses/{id}/storyboard": { "get": { "tags": [ "Courses" ], "summary": "Get the storyboard", "description": "Every module's scenes, omissions and warnings.\n\n**Scope:** `courses:read`", "operationId": "getV1CoursesIdStoryboard", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Courses" ], "summary": "Build a module's storyboard", "description": "**Scope:** `courses:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1CoursesIdStoryboard", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "moduleId": { "type": "string", "minLength": 1 } }, "required": [ "moduleId" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That module is already being worked on" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/courses/{id}/generate": { "post": { "tags": [ "Courses" ], "summary": "Generate a module's video", "description": "Needs a storyboard first.\n\n**Scope:** `courses:write`\n\n**Role permission:** `canEdit` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1CoursesIdGenerate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "moduleId": { "type": "string", "minLength": 1 } }, "required": [ "moduleId" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Job accepted; poll GET /v1/jobs/:id" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "That module is already generating" }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit": { "get": { "tags": [ "Brand Kit" ], "summary": "Get the Brand Kit", "description": "Defaults applied to generated videos and articles, plus counts for skills, glossary and pronunciations.\n\n**Scope:** `brand_kit:read`", "operationId": "getV1Brand-kit", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Brand Kit" ], "summary": "Update the Brand Kit", "description": "Only the fields you pass change; null clears one. Applies to every future export and article.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Brand-kit", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyContext": { "type": [ "string", "null" ], "maxLength": 5000 }, "defaultLanguage": { "type": "string", "minLength": 2, "maxLength": 10 }, "defaultVoiceId": { "type": [ "string", "null" ] }, "openingSceneUrl": { "type": [ "string", "null" ], "format": "uri" }, "closingSceneUrl": { "type": [ "string", "null" ], "format": "uri" }, "backgroundMusicUrl": { "type": [ "string", "null" ], "format": "uri" }, "backgroundMusicVolume": { "type": "number", "minimum": 0, "maximum": 100 }, "backgroundMusicDuckVolume": { "type": "number", "minimum": 0, "maximum": 100 }, "backgroundMusicFadeDuration": { "type": "number", "minimum": 0, "maximum": 30 }, "backgroundMusicPlayInScenes": { "type": "boolean" }, "defaultVideoBackground": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "gradientId": { "type": "string", "maxLength": 80 }, "gradientColors": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 8 }, "gradientAngle": { "type": "number", "minimum": 0, "maximum": 360 }, "customImageUrl": { "type": "string", "format": "uri" }, "padding": { "type": "number", "minimum": 0, "maximum": 500 }, "borderRadius": { "type": "number", "minimum": 0, "maximum": 500 } }, "required": [ "enabled", "padding", "borderRadius" ], "additionalProperties": false }, "defaultSlideStyle": { "type": [ "object", "null" ], "additionalProperties": {} }, "defaultArticleStyle": { "type": [ "object", "null" ], "additionalProperties": {} }, "defaultAvatarSettings": { "type": [ "object", "null" ], "additionalProperties": {} }, "watermark": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "imageUrl": { "type": "string", "format": "uri" }, "position": { "type": "string", "enum": [ "top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] }, "opacity": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "enabled", "imageUrl", "position", "size", "opacity" ], "additionalProperties": false }, "logoUrl": { "type": [ "string", "null" ], "format": "uri" }, "heygenAvatarId": { "type": [ "string", "null" ] }, "heygenVoiceId": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/pronunciations": { "get": { "tags": [ "Brand Kit" ], "summary": "Get pronunciations", "description": "**Scope:** `brand_kit:read`", "operationId": "getV1Brand-kitPronunciations", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Brand Kit" ], "summary": "Replace pronunciations", "description": "Full replacement — they apply as an ordered list of whole-word rewrites, so entries interact.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "putV1Brand-kitPronunciations", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pronunciations": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string", "minLength": 1, "maxLength": 120 }, "pronunciation": { "type": "string", "minLength": 1, "maxLength": 200 }, "caseSensitive": { "type": "boolean" } }, "required": [ "word", "pronunciation" ], "additionalProperties": false }, "maxItems": 500 } }, "required": [ "pronunciations" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/skills": { "get": { "tags": [ "Brand Kit" ], "summary": "List brand skills", "description": "**Scope:** `brand_kit:read`", "operationId": "getV1Brand-kitSkills", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Brand Kit" ], "summary": "Create a brand skill", "description": "Markdown instructions folded into generation as a style guide. Max 20,000 characters.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Brand-kitSkills", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "type": "string", "enum": [ "videoScript", "article" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "name", "domain", "content" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Skill created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/skills/{id}": { "patch": { "tags": [ "Brand Kit" ], "summary": "Update a brand skill", "description": "**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "patchV1Brand-kitSkillsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "type": "string", "enum": [ "videoScript", "article" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Brand Kit" ], "summary": "Delete a brand skill", "description": "**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1Brand-kitSkillsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "id", "deleted" ], "additionalProperties": false, "description": "Resource deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/glossary": { "get": { "tags": [ "Brand Kit" ], "summary": "Get the glossary", "description": "Brand terms and how they should be translated. Feeds the translation pipeline.\n\n**Scope:** `brand_kit:read`", "operationId": "getV1Brand-kitGlossary", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Brand Kit" ], "summary": "Replace the glossary", "description": "Full replacement, max 200 entries.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "putV1Brand-kitGlossary", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 120 }, "doNotTranslate": { "type": "boolean" }, "caseSensitive": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 300 }, "translations": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } } }, "required": [ "term" ], "additionalProperties": false }, "maxItems": 200 } }, "required": [ "entries" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/brand-kit/glossary/import": { "post": { "tags": [ "Brand Kit" ], "summary": "Import glossary CSV", "description": "Merge (default) or replace. Reports added/updated/cleared/dropped plus row-level issues.\n\n**Scope:** `brand_kit:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Brand-kitGlossaryImport", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 1000000 }, "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" } }, "required": [ "csv" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List jobs", "description": "**Scope:** `jobs:read`", "operationId": "getV1Jobs", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "export", "analysis", "translation", "tool", "process" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get job status", "description": "**Scope:** `jobs:read`", "operationId": "getV1JobsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get usage and limits", "description": "`balance` is unit-tagged — most workspaces are billed in credits, not minutes.\n\n**Scope:** `usage:read`", "operationId": "getV1Usage", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage/credits": { "get": { "tags": [ "Usage" ], "summary": "Get credit costs", "description": "What each operation costs, alongside the balance. Tools are priced individually — see GET /v1/tools.\n\n**Scope:** `usage:read`", "operationId": "getV1UsageCredits", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voices": { "get": { "tags": [ "Reference" ], "summary": "List voices", "description": "Voices accepted as `voiceId`. The workspace's own clones come first, marked `custom: true`.\n\n**Scope:** `voices:read`", "operationId": "getV1Voices", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/avatars": { "get": { "tags": [ "Reference" ], "summary": "List AI avatars", "description": "Avatars usable with the AI avatar generator. Search with `q` — the stock library is large.\n\n**Scope:** `avatars:read`", "operationId": "getV1Avatars", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Reference" ], "summary": "Create a photo avatar", "description": "Builds a photo avatar from a public image URL and adds it to the workspace. Enterprise plan required.\n\n**Scope:** `avatars:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "postV1Avatars", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "imageUrl": { "type": "string", "format": "uri" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "imageUrl", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Avatar created" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/avatars/{id}": { "get": { "tags": [ "Reference" ], "summary": "Get an AI avatar", "description": "Checks the workspace's own avatars first, then the stock library.\n\n**Scope:** `avatars:read`", "operationId": "getV1AvatarsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`) or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voices/{id}": { "delete": { "tags": [ "Reference" ], "summary": "Delete a cloned voice", "description": "Removes one of the workspace's cloned voices, at the provider as well. Stock voices can't be deleted; cloning is app-only (it needs recorded consent).\n\n**Scope:** `voices:write`\n\n**Role permission:** `canEditSettings` (OAuth only — API keys carry full workspace permissions)", "operationId": "deleteV1VoicesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "voiceId": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "voiceId", "deleted" ], "additionalProperties": false, "description": "Voice deleted." } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/languages": { "get": { "tags": [ "Reference" ], "summary": "List supported languages", "description": "The codes every `language` parameter accepts.", "operationId": "getV1Languages", "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 req/min)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`vdo_live_...`) or an OAuth 2.0 access token (`vdo_oat_...`)." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://vidocu.ai/oauth/authorize", "tokenUrl": "https://api.vidocu.ai/oauth/token", "scopes": { "videos:read": "View videos in the workspace", "videos:write": "Upload and modify videos", "projects:read": "View project folders", "projects:write": "Create, update, and delete project folders", "subtitles:read": "View subtitles", "subtitles:write": "Generate and edit subtitles", "export:write": "Export videos", "translate:write": "Translate videos", "voiceover:write": "Generate voiceovers", "article:read": "View help articles", "article:write": "Generate help articles", "analyze:write": "Analyze videos", "tools:read": "List and view tools", "tools:write": "Execute tools", "jobs:read": "View job status", "courses:read": "View courses and their storyboards", "courses:write": "Create courses and run planning, storyboarding and generation", "studio:read": "View Studio projects and templates", "studio:write": "Create, edit and share Studio projects", "modules:read": "View training modules, results and qualifications", "modules:write": "Create, edit and translate training modules; record attempts and sign-offs", "remixes:read": "View remixes and their analysis", "remixes:write": "Create remixes and run analysis", "recordings:read": "View AI Recorder jobs and saved logins", "recordings:write": "Start recordings and manage saved logins", "knowledge_base:read": "View the knowledge base, its articles and analytics", "knowledge_base:write": "Create and edit knowledge base content", "brand_kit:read": "View Brand Kit settings, skills and glossary", "brand_kit:write": "Change Brand Kit settings, skills and glossary", "usage:read": "View usage statistics", "voices:read": "List available voices", "voices:write": "Delete cloned voices", "avatars:read": "List available AI avatars", "avatars:write": "Create custom AI avatars", "webhooks:read": "View webhook subscriptions", "webhooks:write": "Create, update, and delete webhooks", "process:write": "Use one-shot process endpoint" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable code, e.g. `validation_error`, `insufficient_role`, `locked`" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }