{"openapi":"3.1.0","info":{"title":"Submagic (BYOK) API","version":"0.1.0","description":"Submagic (BYOK) lets an AI assistant read your own Submagic data through the Submagic API with a key you supply (Submagic API key (starts with sk-)). Read-only: 9 tools (list_languages, list_templates, list_hook_title_templates, list_user_media, get_project, list_presets, get_preset, list_published_projects, get_publication). The BYOK key travels with each request, is used for that one call only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-submagic.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-submagic/docs"},"termsOfService":"https://connectorbay.com/byok-submagic/terms"},"servers":[{"url":"https://byok-submagic.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-submagic/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_languages":{"post":{"operationId":"list_languages","summary":"List the languages Submagic can transcribe and caption, with their codes. Use for \"Which languages does Submagic support","description":"List the languages Submagic can transcribe and caption, with their codes. Use for \"Which languages does Submagic support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_languagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_templates":{"post":{"operationId":"list_templates","summary":"List the names of the built-in caption templates that can be used when creating projects. Use for \"What caption template","description":"List the names of the built-in caption templates that can be used when creating projects. Use for \"What caption templates does Submagic offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_hook_title_templates":{"post":{"operationId":"list_hook_title_templates","summary":"List the names of the hook-title templates available for projects. Use for \"Which hook title templates can I use in Subm","description":"List the names of the hook-title templates available for projects. Use for \"Which hook title templates can I use in Submagic\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_hook_title_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_user_media":{"post":{"operationId":"list_user_media","summary":"List files in the media library (videos, audio, images) with size, duration and upload date; cursor paging. Use for \"Wha","description":"List files in the media library (videos, audio, images) with size, duration and upload date; cursor paging. Use for \"What videos are in my Submagic media library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["VIDEO","AUDIO","IMAGE"],"type":"string"},{"type":"null"}],"default":null,"description":"Only media of this type.","title":"Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 100, default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from 'nextCursor' of the previous answer; leave empty for the first page.","title":"Cursor"}},"title":"list_user_mediaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_project":{"post":{"operationId":"get_project","summary":"Get a Submagic project: title, status (processing to completed), language, template, effects switched on, video details ","description":"Get a Submagic project: title, status (processing to completed), language, template, effects switched on, video details and download or preview URLs. The word-by-word transcript is left out. Use for \"Is Submagic project 550e8400-e29b-41d4-a716-446655440000 finished\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Project id (UUID).","maxLength":200,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_projectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_presets":{"post":{"operationId":"list_presets","summary":"List saved presets (caption, hook title and effect settings reused across projects); cursor paging. Use for \"What Submag","description":"List saved presets (caption, hook title and effect settings reused across projects); cursor paging. Use for \"What Submagic presets have I saved\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 100, default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from 'nextCursor' of the previous answer; leave empty for the first page.","title":"Cursor"}},"title":"list_presetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_preset":{"post":{"operationId":"get_preset","summary":"Get one preset: its name and which captions, hook title, zooms and B-roll settings it applies. Use for \"Show Submagic pr","description":"Get one preset: its name and which captions, hook title, zooms and B-roll settings it applies. Use for \"Show Submagic preset 550e8400-e29b-41d4-a716-446655440000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"preset_id":{"description":"Preset id (UUID).","maxLength":200,"title":"Preset Id","type":"string"}},"required":["preset_id"],"title":"get_presetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_published_projects":{"post":{"operationId":"list_published_projects","summary":"List projects published to social platforms with views, engagement and per-platform post analytics; filter by platform a","description":"List projects published to social platforms with views, engagement and per-platform post analytics; filter by platform and date, sort by views. Use for \"Which of my Submagic videos got the most views on YouTube in May 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"platform":{"anyOf":[{"enum":["youtube","tiktok","instagram","twitter","facebook","linkedin"],"type":"string"},{"type":"null"}],"default":null,"description":"Only publications on this platform.","title":"Platform"},"from_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the publish date range (ISO 8601).","title":"From Date"},"to_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the publish date range (ISO 8601).","title":"To Date"},"sort_by":{"anyOf":[{"enum":["publishedAt","views","engagement"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: publishedAt, views or engagement.","title":"Sort By"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor copied from 'nextCursor' of the previous answer; leave empty for the first page.","title":"Cursor"}},"title":"list_published_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_publication":{"post":{"operationId":"get_publication","summary":"Get one publication: status, totals and per-platform post links and analytics. Use for \"Show the analytics of Submagic p","description":"Get one publication: status, totals and per-platform post links and analytics. Use for \"Show the analytics of Submagic publication pub1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"publication_id":{"description":"Publication id (UUID).","maxLength":200,"title":"Publication Id","type":"string"}},"required":["publication_id"],"title":"get_publicationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}