{"openapi":"3.1.0","info":{"title":"Descript (BYOK) API","version":"0.1.0","description":"Descript (BYOK) lets an AI assistant read your own Descript data through the Descript API with a key you supply (Descript API token (tied to one drive)). Read-only: 8 tools (get_api_status, list_projects, get_project, search_drive, list_jobs, get_job, list_agent_models, get_published_project). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-descript.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-descript/docs"},"termsOfService":"https://connectorbay.com/byok-descript/terms"},"servers":[{"url":"https://byok-descript.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-descript/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/get_api_status":{"post":{"operationId":"get_api_status","summary":"Check that the Descript token is valid and show which drive (workspace) it is tied to and the API version. Use for \"Is m","description":"Check that the Descript token is valid and show which drive (workspace) it is tied to and the API version. Use for \"Is my Descript API token working and which drive is it for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_statusArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List Descript projects in the token's drive with name, folder path and dates, filtered by name, folder, creator or date ","description":"List Descript projects in the token's drive with name, folder path and dates, filtered by name, folder, creator or date and sorted. Use for \"Which Descript projects are in my Clients folder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name contains this text (case-insensitive).","title":"Name"},"folder_path":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects directly in this folder path, for example Clients/Acme/Videos.","title":"Folder Path"},"created_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"User UUID of the creator, or me for your own projects.","title":"Created By"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects created after this ISO 8601 time.","title":"Created After"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects updated after this ISO 8601 time.","title":"Updated After"},"sort":{"anyOf":[{"enum":["name","created_at","updated_at","last_viewed_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort field: name, created_at, updated_at or last_viewed_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort direction: asc or desc.","title":"Direction"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.next_cursor to get the next page.","title":"Cursor"}},"title":"list_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_project":{"post":{"operationId":"get_project","summary":"Get one Descript project: its media files, compositions (name, duration, media type) and existing publishes (share link,","description":"Get one Descript project: its media files, compositions (name, duration, media type) and existing publishes (share link, access level, dates). Use for \"What compositions and publishes does this Descript project have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Descript project UUID, from list_projects.","maxLength":60,"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/search_drive":{"post":{"operationId":"search_drive","summary":"Search the token's Descript drive for projects, folders, layout packs and media by name or content, with optional date a","description":"Search the token's Descript drive for projects, folders, layout packs and media by name or content, with optional date and type filters. Use for \"Find Descript projects that mention onboarding\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search term matched against names and contents.","maxLength":200,"title":"Query","type":"string"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only results updated at or after this ISO 8601 date or time.","title":"Updated After"},"updated_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only results updated at or before this ISO 8601 date or time.","title":"Updated Before"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Restrict to one result type, for example project, project_folder or layout_pack.","title":"Type"},"match":{"anyOf":[{"enum":["name","content"],"type":"string"},{"type":"null"}],"default":null,"description":"Restrict how the query matches: name or content.","title":"Match"},"sort":{"anyOf":[{"enum":["relevance","newest","oldest"],"type":"string"},{"type":"null"}],"default":"relevance","description":"Order: relevance, newest or oldest.","title":"Sort"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum results (1 to 100).","title":"Limit"}},"required":["query"],"title":"search_driveArguments","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_jobs":{"post":{"operationId":"list_jobs","summary":"List recent Descript jobs (imports, agent edits, publishes) with state and outcome, default last 7 days (max 30), option","description":"List recent Descript jobs (imports, agent edits, publishes) with state and outcome, default last 7 days (max 30), optionally for one project. Use for \"Which Descript jobs ran this week and did they succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs of this project UUID.","title":"Project Id"},"type":{"anyOf":[{"enum":["import/project_media","agent"],"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs of this type.","title":"Type"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs created after this ISO 8601 time (oldest allowed: 30 days ago).","title":"Created After"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs created before this ISO 8601 time.","title":"Created Before"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.next_cursor to get the next page.","title":"Cursor"}},"title":"list_jobsArguments","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_job":{"post":{"operationId":"get_job","summary":"Get the status of one Descript job by ID: state, progress and, when finished, success or error details and credits used.","description":"Get the status of one Descript job by ID: state, progress and, when finished, success or error details and credits used. Use for \"Is Descript job 7a1c3b9e finished\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Descript job UUID, from list_jobs.","maxLength":60,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"get_jobArguments","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_agent_models":{"post":{"operationId":"list_agent_models","summary":"List the Descript agent (Underlord) models and the aliases that point to them, with relative cost tier. Use for \"Which D","description":"List the Descript agent (Underlord) models and the aliases that point to them, with relative cost tier. Use for \"Which Descript agent models can I choose\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_agent_modelsArguments","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_published_project":{"post":{"operationId":"get_published_project","summary":"Get metadata of a published Descript project by its share slug: publish type, privacy, title, duration and publish time.","description":"Get metadata of a published Descript project by its share slug: publish type, privacy, title, duration and publish time. Use for \"What is the title and privacy of this published Descript project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"URL slug of the published project (the last part of its share link).","maxLength":120,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_published_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}}}}