{ "openapi": "3.0.0", "info": { "description": "Descript API documentation.", "version": "1.2", "title": "Descript API", "x-logo": { "url": "assets/descript-logo.svg", "altText": "Descript" }, "license": { "name": "Proprietary", "url": "https://www.descript.com/terms" } }, "servers": [ { "url": "https://descriptapi.com/v1" } ], "tags": [ { "name": "Getting started", "description": "The Descript API lets you programmatically create projects, import media, and edit your projects — all without opening the app.\n\nTo learn more, visit [descript.com/api](https://descript.com/api).\n\n## Create an API token\n\n1. In Descript, open **Settings** and select **API tokens** from the sidebar. Then click **Create token**.\n\n![Navigate to Settings > API tokens and click Create token](assets/token1.png)\n\n2. Give your token a name and select the Drive it should be associated with. Click **Create token**.\n\n\"Name\n\n3. Copy your token and store it in a safe place. You won't be able to view it again. If you lose it, you'll need to generate a new one.\n\n\"Copy\n\n> **Warning:** Treat your API token like a password. Anyone with your token can make API requests on your behalf using your account permissions. Never share your token publicly or commit it to source control.\n\nInclude the token as a Bearer token in the `Authorization` header of your API requests.\n\n## Import media into a new project\n\nYou can create a new project, import media, and place the media into a composition all in one API request using the [import endpoint](#operation/importProjectMedia). This step also transcribes and processes the media so that it's ready for you or the agent to edit.\n\nTo import files, pass in public or pre-signed URIs. Currently, the API does not support uploading a file directly. To test the API with an example file, use the demo video included in the sample request below.\n\nImporting and processing is an asynchronous job, so the response payload will contain a `job_id` for you to [query the status of the job](#operation/getJob) and information about the newly created project. Note that `project_id` and `project_url` are returned immediately alongside `job_id`, but opening the project in Descript will not always show the API's processing state in real time. To prevent unintended changes, we recommend that you do not make any changes to the project until the job has stopped.\n\n\n\n**Request**\n\n```bash\ncurl -X POST https://descriptapi.com/v1/jobs/import/project_media \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"project_name\": \"My First Video\",\n \"add_media\": {\n \"demo.mp4\": {\n \"url\": \"https://test-files.descriptapi.com/demo-video.mp4\"\n }\n },\n \"add_compositions\": [\n {\n \"name\": \"Demo Video\",\n \"clips\": [\n { \"media\": \"demo.mp4\" }\n ]\n }\n ]\n }'\n```\n\n**Response**\n\n```json\n{\n \"job_id\": \"project-media-import-9d635d5b\",\n \"drive_id\": \"c9c5c47e\",\n \"project_id\": \"e2f89ce6\",\n \"project_url\": \"https://web.descript.com/e2f89ce6\"\n}\n```\n\n## Check for import completion\n\nPoll the [job status endpoint](#operation/getJob) using the `job_id` from the last step to check whether the import job is finished processing. When it is, you'll see `job_state: \"stopped\"`. You can then check the `results` object to see its full results.\n\nYou can also pass in a `callback_url` as a part of the first import request, and we'll ping you when the job has stopped with the same response payload.\n\n**Request**\n\n```bash\ncurl https://descriptapi.com/v1/jobs/project-media-import-9d635d5b \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n**Response**\n\n```json\n{\n \"job_id\": \"project-media-import-9d635d5b\",\n \"job_type\": \"import/project_media\",\n \"job_state\": \"stopped\",\n \"project_id\": \"e2f89ce6\",\n \"project_url\": \"https://web.descript.com/e2f89ce6\",\n \"result\": {\n \"status\": \"success\",\n \"media_status\": {\n \"main.mp4\": {\n \"status\": \"success\",\n \"duration_seconds\": 69.477006\n }\n },\n \"created_compositions\": [\n { \"id\": \"f8e5088a-4d53-4aab-9d4f-c6624b7d7622\", \"name\": \"Demo Video\" }\n ]\n }\n}\n```\n\n## Prompt for edits with Agent Underlord\n\nOnce your media is imported, you can use the [agent edit endpoint](#operation/agentEditJob) to prompt Underlord for edits, just as you would in the app. Because it's an API, conversation and follow up questions aren't practical. So we recommend framing your edits as a one-shot prompt with all the information the agent needs.\n\nEditing can take some time, so the response also returns a `job_id` that you can use to [check the status of the job](#operation/getJob). You can also pass in a `callback_url` as a part of an agent request, and we'll ping you when the job has stopped.\n\n**Request**\n\n```bash\ncurl -X POST https://descriptapi.com/v1/jobs/agent \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"project_id\": \"e2f89ce6\",\n \"prompt\": \"Add studio sound and captions\"\n }'\n```\n\n**Response**\n\n```json\n{\n \"job_id\": \"project-agent-edit-e2f89ce6\",\n \"drive_id\": \"c9c5c47e\",\n \"project_id\": \"e2f89ce6\",\n \"project_url\": \"https://web.descript.com/e2f89ce6\"\n}\n```\n\n## Wait for the agent to complete its job\n\nPoll the [job status endpoint](#operation/getJob) using the `job_id`. When the agent job completes successfully, the response includes a summary of what it accomplished (see the `result.agent_response` field). Use the project URL to open the project in Descript and review Underlord's changes.\n\n**Request**\n\n```bash\ncurl https://descriptapi.com/v1/jobs/project-agent-edit-e2f89ce6 \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\nOnce the agent job is successfully complete, you’ll see a response from the agent with a brief summary of what it accomplished. You can then use the project url to review its changes directly in Descript.\n\n**Response**\n\n```json\n{\n\t\"job_id\":\"project-agent-edit-e2f89ce6\",\n\t\"job_type\":\"agent\",\n \"project_id\":\"YOUR_PROJECT_ID\",\n\t\"project_url\":\"https://web.descript.com/e2f89ce6\",\n\t\"job_state\":\"stopped\",\n\t\"created_at\":\"2026-02-09T05:42:27.554Z\",\n\t\"stopped_at\":\"2026-02-09T05:43:15.296Z\",\n\t\"drive_id\":\"1df135a5-dc4a-4dc3-8f7d-681cfbe961e4\",\n\t\"result\":{\n\t\t\"status\":\"success\",\n \"agent_response\":\"Done! I've applied Studio Sound to enhance your audio quality and added classic karaoke-style captions to your video.\",\n\t\t\"project_changed\":true,\n\t\t\"media_seconds_used\":0,\n\t\t\"ai_credits_used\":32\n }\n}\n```\n" }, { "name": "Using the CLI", "description": "The CLI wraps the API into a simple to use command line tool with interactive flows for setting up authentication, importing, and prompting the agent. It also has built-in polling for job completion.\n\n## Requirements\n\nBefore installing the CLI, you'll need **Node.js 24 or higher**. Visit [nodejs.org](https://nodejs.org/) to download and install the latest LTS version for your operating system.\n\n## Install and set up\n\nFirst, install the latest version of the CLI using npm.\n\n```bash\nnpm install -g @descript/platform-cli@latest\n```\n\nNext, configure the CLI with your API key.\n\n```bash\ndescript-api config set api-key\n```\n\n![Setting up the CLI](assets/cli-set-up.gif)\n\n\n## Import media\n\nUse the `import` command to create a project by passing a project name and the link to any media you want to upload, or run `descript-api import` for interactive mode. The CLI shows live progress and outputs the project ID when done.\n\n```bash\ndescript-api import \\\n --name \"My First Project\" \\\n --media \"https://test-files.descriptapi.com/demo-video.mp4\"\n```\n\n![Interactive CLI import](assets/cli-import.gif)\n\n## Use the agent\n\nUse the `agent` command to edit a project by passing in the project id and an Underlord prompt.\n\n```bash\ndescript-api agent \\\n --project-id YOUR_PROJECT_ID \\\n --prompt \"Remove filler words and add Studio Sound to all clips\"\n```\n\nYou can also ask Underlord create a new project from a prompt alone by writing the script for you!\n\n```bash\ndescript-api edit --new \\\n --prompt \"Write a script about how to make great coffee\"\n```\n\n## All commands\n\nRun `descript-api help` to see the full list of available commands and options.\n" }, { "name": "API Endpoints", "description": "Import media, edit projects with AI, and query jobs and projects." }, { "name": "Direct file upload", "description": "Instead of providing a public URL, you can upload files directly from your local machine using the [import endpoint](#operation/importProjectMedia). The flow has three steps: request signed upload URLs, PUT your file bytes, then poll for completion.\n\n## Step 1 — Request upload URLs\n\nCall the import endpoint with `content_type` and `file_size` instead of `url` for each media item you want to upload directly.\n\n**Request**\n\n```bash\ncurl -X POST https://descriptapi.com/v1/jobs/import/project_media \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"project_name\": \"My Upload Project\",\n \"add_media\": {\n \"recording.mp4\": {\n \"content_type\": \"video/mp4\",\n \"file_size\": 52428800\n }\n },\n \"add_compositions\": [\n {\n \"name\": \"Main\",\n \"clips\": [\n { \"media\": \"recording.mp4\" }\n ]\n }\n ]\n }'\n```\n\nThe response includes an `upload_urls` object keyed by media reference ID. Each entry contains a signed `upload_url` (valid for 3 hours), plus `asset_id` and `artifact_id` for the created asset.\n\n**Response**\n\n```json\n{\n \"job_id\": \"project-media-import-a1b2c3d4\",\n \"drive_id\": \"c9c5c47e\",\n \"project_id\": \"e2f89ce6\",\n \"project_url\": \"https://web.descript.com/e2f89ce6\",\n \"upload_urls\": {\n \"recording.mp4\": {\n \"upload_url\": \"https://storage.googleapis.com/bucket/...\",\n \"asset_id\": \"d4e5f6a7-1234-5678-9abc-def012345678\",\n \"artifact_id\": \"a1b2c3d4-5678-9abc-def0-123456789abc\"\n }\n }\n}\n```\n\n## Step 2 — Upload the file\n\nPUT the raw file bytes to the signed URL. Use `Content-Type: application/octet-stream`.\n\n```bash\ncurl -X PUT \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary @recording.mp4 \\\n \"https://storage.googleapis.com/bucket/...\"\n```\n\nThe import job detects the upload automatically and begins processing.\n\n## Step 3 — Poll for completion\n\nCheck the job status the same way as a URL-based import — poll the [job status endpoint](#operation/getJob) with the `job_id`, or provide a `callback_url` in the original request.\n\n```bash\ncurl https://descriptapi.com/v1/jobs/project-media-import-a1b2c3d4 \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\nWhen the job reaches `job_state: \"stopped\"`, check `result.status` for success or failure.\n\n## Mixing URL imports and direct uploads\n\nYou can combine URL-based and direct upload media items in a single request. Items with `url` are fetched server-side; items with `content_type` and `file_size` return signed upload URLs.\n\n```bash\ncurl -X POST https://descriptapi.com/v1/jobs/import/project_media \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"project_name\": \"Mixed Import\",\n \"add_media\": {\n \"intro.mp4\": {\n \"url\": \"https://example.com/intro.mp4\"\n },\n \"recording.mp4\": {\n \"content_type\": \"video/mp4\",\n \"file_size\": 52428800\n }\n }\n }'\n```\n\nThe response will include `upload_urls` only for the direct upload items.\n\n## Required fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `content_type` | string | MIME type of the file (e.g., `video/mp4`, `audio/wav`) |\n| `file_size` | integer | File size in bytes |\n| `language` | string | *(optional)* ISO 639-1 language code for transcription. Auto-detected if omitted. |\n" }, { "name": "Authentication", "description": "The Descript API uses personal API tokens to authenticate requests. Tokens are scoped to a specific Drive and inherit your permissions on that Drive.\n\nTo create a token, see the [Getting Started](#section/Getting-started/Create-an-API-token) guide.\n\n> **Warning:** Treat your API token like a password. Anyone with your token can make API requests on your behalf using your account permissions. Never share your token publicly or commit it to source control.\n\n## Using your token\n\nInclude the token as a Bearer token in the `Authorization` header of your API requests.\n\n**Example**\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_API_TOKEN\" https://descriptapi.com/v1/status\n```\n" }, { "name": "Rate Limiting", "description": "The Descript API implements rate limiting to ensure fair usage and protect service availability.\nWhen you exceed the rate limit, the API returns a `429 Too Many Requests` response.\n\n## Rate Limit Headers\n\nWhen a rate limit is exceeded, the response includes the following headers:\n\n| Header | Description |\n|--------|-------------|\n| `Retry-After` | Number of seconds to wait before retrying the request |\n| `X-RateLimit-Remaining` | Number of requests remaining in the current window |\n| `X-RateLimit-Consumed` | Number of requests consumed in the current window |\n\n## Handling Rate Limits\n\nWhen you receive a `429` response, use the `Retry-After` header to determine how long to wait before retrying.\nThis approach is more efficient than using fixed delays or exponential backoff alone.\n" }, { "name": "Edit in Descript", "description": "> **Note:** The Edit in Descript integration requires contacting Descript for access. [Reach out to us](https://descript.com/api) to get started.\n\nEdit in Descript API enables partners to give their users the ability to transfer audio or video content to Descript for editing.\n\nEdit in Descript buttons work by generating one-time use, public Import URLs to the Descript import UI that users\ncan be automatically sent to. On that page, they can make a few simple selections before kicking off a Partner cloud\nstorage to Descript cloud storage transfer. This will redirect them to a Descript Project ready for editing.\n\nPartners can initiate the request by securely sending an information schema backend-to-backend to the Descript API\nusing a token, in exchange for the Import URL to redirect the user. Partners do not need to store this schema, as\nDescript will do so and use it to start fetching the files when the user confirms the action\n\n1. When a user clicks `Edit in Descript`, partner's backend service makes POST request to:\n `https://descriptapi.com/v1/edit_in_descript/schema` with an authorization bearer token header and JSON schema body\n2. Descript responds with either an Import URL or an error\n3. Partner redirects the user's browser to the URL returned in step 2 or display an error message and link to help documentation\n\n### Partner User Experience\nSome guidelines for partners as you consider this integration:\n* We recommend placing the `Edit in Descript` option next to your download options\n * If you offer multiple download options, such as combined vs. split audio/video files, we recommend placing\nthis integration clearly in context with each option, or only the supported option, to help users understand\nwhat will be exported.\n * Each time you request an import link, a new one is generated. Import links expire after 3 hours. After using an\nimport link, the only way to find an imported Project again is in Descript.\n * If an import link has expired or the contents of the schema has changed, please request a new import link with\nthe updated schema. This will create a new Descript Project when used.\n* We will provide Descript-branded assets to fit your proposed placement of the `Edit in Descript` CTA and ask\nthat you don't edit the assets beyond what we provide. We are happy to work with you on getting you the right\nassets for your placement.\n* Partners should provide error-handling for the POST request, at minimum displaying a generic error message and\nlinking to a help article (we can provide a link for this if you prefer).\n* Progress will be conveyed to the user in the Descript side of the user experience.\n\n### Descript User Experience\nWhen users are directed to a Descript Import URL, they'll be asked to either create an account or login in order\nto proceed.\n\nNext, they will be presented with a few options about how they'd like to import the data, such as where the new\nDescript Project should be created.\n\nThey'll then be redirected to the Project, where they can monitor the progress of the import and start editing.\n" }, { "name": "Export from Descript", "description": "Users of Descript currently have three options to export their edited content. They can export files in various\nformats, share a Descript link, or use our [one-click cloud export](https://help.descript.com/connect-with-us/hosting-partners)\nto publish directly to a partner.\n\n### Roundtrip Metadata\nIf Project data previously came from a partner via an Edit in Descript schema then any Descript Export pages\nwill include `` tags which contains the `partner_drive_id` and `source_id` provided when originally\nimporting into Descript. This allows partners to deduplicate data returning back to partner systems after\nediting in Descript. Both partner and source properties are included on all public Descript Export pages.\n\n```\n\n\n```\n" } ], "paths": { "/jobs/import/project_media": { "post": { "tags": [ "API Endpoints" ], "summary": "Import media and sequences", "security": [ { "bearerAuth": [] } ], "description": "Import media files into a new or existing project and create compositions.\n\nThis endpoint can:\n- Create a new project if `project_id` is not provided\n- Import media files from URLs\n- Create multitrack sequences\n- Create compositions (timelines) from existing or new media in the project\n- Trigger transcription and other background processing tasks\n\n### Media URL requirements\n- URLs must be accessible by Descript servers\n- URLs must support HTTP Range requests\n- Recommended to sign URLs for 12-48 hours to reduce chance of failure\n- [Supported file types](https://help.descript.com/add-and-manage-media/supported-file-types)\n\n### Direct file upload\n\nInstead of providing a URL, you can upload files directly by specifying `content_type` and `file_size` for a media item. The response will include a signed `upload_url` for each direct upload item. PUT the file bytes to that URL, and the import job will process it automatically. See the [Direct file upload](#tag/Direct-file-upload) guide for a full walkthrough.\n\n### Async Operations\n\nImports run in the background and return a `job_id`. Monitor progress via the [GET /jobs/{job_id}](#operation/getJob) endpoint.\n\n### Dynamic webhook\n\nIf `callback_url` is provided, Descript will POST the job status to that URL when the job finishes (successfully or not).\n\nThe payload will match the format returned by [GET /jobs/{job_id}](#operation/getJob).\n", "operationId": "importProjectMedia", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Request to import media into a project and optionally create compositions.\nThis operation will:\n- Create a new project if project_id is not provided (using the drive associated with the personal token)\n- Import media files from URLs or create multitrack sequences\n- Optionally create one or more compositions\n- Trigger transcription and other background processing\n", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "Existing project ID to import media into. If not provided, a new project will be created.\nWhen importing into an existing project, media filenames must not conflict with existing files.\n", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_name": { "type": "string", "description": "Name for the new project. Only used when project_id is not provided.", "example": "Marketing Video" }, "team_access": { "type": "string", "description": "Access level for drive members. Only applicable when creating a new project\n(when project_id is not provided). Defaults to `none` if not specified.\n- edit: Users can edit the project\n- comment: Users can view and comment but not edit\n- view: Users can view but not comment or edit\n- none: No shared access (private to owner)\n", "enum": [ "edit", "comment", "view", "none" ], "default": "none", "example": "edit" }, "folder_name": { "type": "string", "description": "Folder path to place the new project in (e.g. \"Clients/Acme/Videos\").\nSupports nested paths using \"/\" as separator. Only applicable when creating a new project\n(when project_id is not provided). Existing folders along the path are reused; missing\nsegments are created automatically.\n", "example": "Clients/Acme" }, "workspace_name": { "type": "string", "description": "Existing workspace to create the new project in, matched by name (case-insensitive).\nOnly applicable when creating a new project (when project_id is not provided).\n\nReserved names: `Personal` (your private space) and `General` (the shared drive workspace).\nAny other value is looked up as a custom workspace name; unknown names return 404.\n\nWhen omitted, `team_access` is passed through unchanged.\nWhen set to `Personal`, `team_access` must be `none` or omitted.\nWhen set to `General` or a custom workspace name, `team_access` must be\n`edit`, `comment`, or `view`; omitting it defaults to `view`, and `none` is rejected.\n\nFor custom workspaces, the caller must be a member of that workspace.\n", "example": "Marketing" }, "add_media": { "type": "object", "description": "Map of media reference IDs (display names with optional folder paths) to media import items.\nKeys are the display names that will appear in the project (e.g., \"Misc/intro.mp4\" or \"demo.mp4\").\nValues define how to import each media item (URL import or multitrack sequence).\n", "additionalProperties": { "type": "object", "description": "Defines how to import a single media item. Can be either a URL import or a multitrack sequence.\n", "oneOf": [ { "type": "object", "title": "URL Import", "description": "Import media from a URL", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL to import media from. Must be accessible by Descript servers and support Range requests.\nRecommended to sign URLs for 12-48 hours to reduce chance of failure.\n", "example": "https://example.com/intro.mp4" }, "language": { "type": "string", "description": "ISO 639-1 language code for transcription (e.g., \"en\", \"es\", \"fr\").\nIf not specified, language is auto-detected from the audio.\n", "example": "en" } }, "additionalProperties": false }, { "type": "object", "title": "Direct Upload", "description": "Upload a file directly to Descript. The API returns a signed upload URL\nin the response. PUT your file to that URL, then the import job will\nprocess it automatically.\n", "required": [ "content_type", "file_size" ], "properties": { "content_type": { "type": "string", "description": "MIME type of the file (e.g., \"video/mp4\", \"audio/wav\")", "example": "video/mp4" }, "file_size": { "type": "integer", "description": "File size in bytes", "example": 52428800 }, "language": { "type": "string", "description": "ISO 639-1 language code for transcription (e.g., \"en\", \"es\", \"fr\").\nIf not specified, language is auto-detected from the audio.\n", "example": "en" } }, "additionalProperties": false }, { "type": "object", "title": "Multitrack Sequence", "description": "Create a multitrack sequence from multiple media files", "required": [ "tracks" ], "properties": { "tracks": { "type": "array", "description": "Array of tracks to combine into a multitrack sequence", "minItems": 1, "items": { "type": "object", "required": [ "media" ], "properties": { "media": { "type": "string", "description": "Media reference ID (display name) of the media to include in this track", "example": "Recordings/camera1.mp4" }, "offset": { "type": "number", "format": "float", "description": "Optional time offset in seconds for syncing this track", "example": 50, "default": 0 } }, "additionalProperties": false } } }, "additionalProperties": false } ] }, "example": { "Misc/intro.mp4": { "url": "https://example.com/intro.mp4" }, "demo.mp4": { "url": "https://example.com/demo.mp4" }, "Multicam_Track": { "tracks": [ { "media": "Recordings/camera1.mp4", "offset": 0 }, { "media": "Recordings/camera2.mp4", "offset": 50 } ] } } }, "add_compositions": { "type": "array", "description": "Optional list of compositions to create in the project", "items": { "type": "object", "description": "Defines a composition to create in the project", "properties": { "name": { "type": "string", "description": "Name of the composition. If not provided, uses default naming.", "example": "Rough Cut" }, "width": { "type": "integer", "description": "Width of the composition in pixels", "example": 1920, "default": 1920 }, "height": { "type": "integer", "description": "Height of the composition in pixels", "example": 1080, "default": 1080 }, "fps": { "type": "number", "description": "**[Work in progress]** This property is not yet supported and will be ignored if provided.\n\nFrame rate for the composition in frames per second.\nCommon values: 24, 25, 29.97, 30, 60.\n", "default": 30, "example": 30 }, "clips": { "type": "array", "description": "Ordered list of clips to include in the composition", "items": { "type": "object", "required": [ "media" ], "properties": { "media": { "type": "string", "description": "Media reference ID (display name) of the media to add as a clip", "example": "Misc/intro.mp4" }, "mute": { "type": "boolean", "description": "Mute the track this clip plays on. For a sequence clip, mutes the sequence's own tracks.\nFor any other clip, mutes the composition's script layer, which silences every\nclip on it — including clips already in the composition. Defaults to false.\n", "default": false, "example": true } }, "additionalProperties": false } } }, "required": [ "clips" ], "additionalProperties": false } }, "callback_url": { "type": "string", "format": "uri", "description": "Optional webhook URL to call when the job completes or fails.\nDescript will POST the job status (same format as [GET /jobs/{job_id}](#operation/getJob)) to this URL.\n", "example": "https://example.com/webhooks/descript/job_callback" } }, "additionalProperties": false }, "examples": { "create_with_composition": { "summary": "Create project with initial composition", "description": "Most common use case for seeding a project with a simple composition", "value": { "project_name": "Marketing Video", "add_media": { "Misc/intro.mp4": { "url": "https://example.com/intro.mp4" }, "demo.mp4": { "url": "https://example.com/demo.mp4" }, "Misc/outro.mp4": { "url": "https://example.com/outro.mp4" } }, "add_compositions": [ { "name": "Rough Cut", "clips": [ { "media": "Misc/intro.mp4" }, { "media": "demo.mp4" }, { "media": "Misc/outro.mp4" } ] } ] } }, "import_only": { "summary": "Import media without composition", "description": "Import files for later composition creation", "value": { "project_name": "Video Project", "add_media": { "Assets/intro.mp4": { "url": "https://example.com/intro.mp4" }, "Assets/logo.png": { "url": "https://example.com/logo.png" } } } }, "direct_upload": { "summary": "Direct file upload", "description": "Upload a local file directly instead of providing a URL", "value": { "project_name": "Upload Project", "add_media": { "recording.mp4": { "content_type": "video/mp4", "file_size": 52428800 } }, "add_compositions": [ { "name": "Main", "clips": [ { "media": "recording.mp4" } ] } ] } }, "multitrack_sequence": { "summary": "Create multitrack sequence", "description": "Combine multiple tracks with time offsets", "value": { "project_name": "Interview Edit", "add_media": { "Misc/intro.mp4": { "url": "https://example.com/intro.mp4" }, "Recordings/camera1.mp4": { "url": "https://example.com/camera1.mp4" }, "Recordings/camera2.mp4": { "url": "https://example.com/camera2.mp4" }, "Multicam_Track": { "tracks": [ { "media": "Recordings/camera1.mp4", "offset": 0 }, { "media": "Recordings/camera2.mp4", "offset": 50 } ] } }, "add_compositions": [ { "name": "Rough Cut", "width": 1920, "height": 1080, "clips": [ { "media": "Misc/intro.mp4" }, { "media": "Multicam_Track" } ] } ] } } } } }, "description": "Media import and project creation request", "required": true }, "responses": { "201": { "description": "Import job created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Response returned when creating an import job", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "drive_id": { "type": "string", "format": "uuid", "description": "Drive ID where the project is located", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "drive_name": { "type": "string", "nullable": true, "description": "Human-readable name of the connected drive (workspace)", "example": "My Team Workspace" }, "project_id": { "type": "string", "format": "uuid", "description": "Project ID (newly created or existing)", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "upload_urls": { "type": "object", "description": "Signed upload URLs for each direct upload media item. Only present when the request\nincludes direct upload references. PUT the file contents to the `upload_url` with\n`Content-Type: application/octet-stream`. The import job will automatically detect\nthe upload and process the file.\n", "additionalProperties": { "type": "object", "properties": { "upload_url": { "type": "string", "format": "uri", "description": "Signed URL to PUT the file to. Expires after 3 hours." }, "asset_id": { "type": "string", "format": "uuid", "description": "GAT asset ID for the uploaded file" }, "artifact_id": { "type": "string", "format": "uuid", "description": "GAT artifact ID for the uploaded file" } }, "required": [ "upload_url", "asset_id", "artifact_id" ] } } }, "required": [ "job_id", "drive_id", "project_id", "project_url" ] } } } }, "400": { "description": "Invalid input:\n- Malformed request body\n- Invalid media URLs\n- URLs not accessible or don't support Range requests\n- Media filename conflicts with existing files (when importing to existing project)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "invalid_url": { "summary": "Invalid media URL", "value": { "error": "invalid_input", "message": "Invalid media URL format" } }, "url_not_accessible": { "summary": "URL not accessible", "value": { "error": "invalid_input", "message": "Media URL is not accessible or does not support Range requests" } }, "filename_conflict": { "summary": "Filename conflict", "value": { "error": "invalid_input", "message": "Media filename conflicts with existing files in the project" } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "402": { "description": "Payment Required - insufficient media minutes to start the job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" }, "examples": { "insufficient_minutes": { "summary": "Insufficient media minutes", "value": { "error": "payment_required", "message": "Insufficient media minutes to start the job (300 minutes required, 50 available)" } } } } } }, "403": { "description": "Forbidden - user does not have access to this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "forbidden": { "summary": "No access to drive or project", "value": { "error": "forbidden", "message": "User does not have access to this drive or project" } } } } } }, "404": { "description": "Not found:\n- Drive doesn't exist\n- Project doesn't exist (when project_id is provided)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "project_not_found": { "summary": "Project not found", "value": { "error": "not_found", "message": "Project not found" } }, "drive_not_found": { "summary": "Drive not found", "value": { "error": "not_found", "message": "Drive not found" } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/jobs/agent": { "post": { "tags": [ "API Endpoints" ], "summary": "Agent edit", "security": [ { "bearerAuth": [] } ], "description": "Use a background agent to create and edit projects using a natural language prompt.\n\n- **Edit existing project**: Provide a `project_id` to edit an existing project\n- **Target a specific composition**: Provide both `project_id` and `composition_id` to direct the agent to a specific composition within the project\n- **Create new project**: Provide a `project_name` instead of `project_id` to create a new project\n\n### Common use cases\n- Create new content: \"create a 30-second video about cooking tips\"\n- Apply audio effects: \"add studio sound to every clip\"\n- Remove filler words: \"remove all filler words from the transcript\"\n- Create highlights: \"create a 30-second highlight reel\"\n- Content editing: \"remove the section from 1:30 to 2:15\"\n\n### Async Operations\n\nAgent edits run in the background and return a `job_id`. Monitor progress via the [GET /jobs/{job_id}](#operation/getJob) endpoint.\n\n### Dynamic webhook\n\nIf `callback_url` is provided, Descript will POST the job status to that URL when the job completes or fails.\nThe payload will match the format returned by [GET /jobs/{job_id}](#operation/getJob).\n", "operationId": "agentEditJob", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Request to run Agent edit.\nThe agent will interpret the prompt and either edit an existing project or create a new one.\nYou must provide exactly one of `project_id` or `project_name`.\n", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The ID of an existing project to edit. Mutually exclusive with `project_name`.\n", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_name": { "type": "string", "description": "Name for creating a new project. Mutually exclusive with `project_id`.\n", "example": "My New Project" }, "composition_id": { "type": "string", "description": "Composition to target within the project. When provided,\nthe agent will focus its edits on this specific composition rather\nthan choosing one automatically. Only valid when `project_id` is also\nprovided. Requires `project_id`.\n\nAccepts any of the following formats:\n- A full composition UUID (e.g. `39677a40-1c43-4c36-8449-46cfbc4de2b5`)\n- A 5-character short ID from a Descript URL (e.g. `39677`)\n- A full Descript project URL (e.g. `https://web.descript.com/{project_id}/39677`)\n", "example": "39677a40-1c43-4c36-8449-46cfbc4de2b5" }, "model": { "type": "string", "description": "AI model to use for editing. Accepts a canonical model id\n(e.g. `claude-opus-4.8`) or a friendly alias that tracks the\nstable version of a family (e.g. `claude-opus`). Call\n[GET /agent/models](#operation/listAgentModels) for the current\nset of supported models and aliases.\n\nDefaults to `auto` when omitted, which selects a recommended\nmodel for your account.\n" }, "prompt": { "type": "string", "description": "Natural language instruction for the agent to execute.\nExamples: \"add studio sound to every clip\", \"remove all filler words\", \"create a 30-second highlight reel\"\n", "example": "add studio sound to every clip" }, "team_access": { "type": "string", "enum": [ "edit", "comment", "view", "none" ], "description": "Access level for team members when creating a new project.\nOnly applicable when `project_name` is provided (not when using `project_id`).\nDefaults to `none` if not specified.\n" }, "callback_url": { "type": "string", "format": "uri", "description": "Optional webhook URL to call when the job completes or fails.\nDescript will POST the job status (same format as [GET /jobs/{job_id}](#operation/getJob)) to this URL.\n", "example": "https://example.com/webhooks/descript/job_callback" } }, "required": [ "prompt" ], "additionalProperties": false }, "examples": { "create_new_project": { "summary": "Create a new project", "value": { "project_name": "Cooking Tips Video", "prompt": "create a 30-second video about cooking tips with background music" } }, "add_studio_sound": { "summary": "Add Studio Sound effect", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "model": "claude-haiku-4.5", "prompt": "add studio sound to every clip" } }, "remove_filler_words": { "summary": "Remove filler words", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "prompt": "remove all filler words" } }, "create_highlight": { "summary": "Create highlight reel", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "prompt": "create a 30-second highlight reel with the best moments" } }, "with_callback": { "summary": "Agent job with webhook callback", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "prompt": "add studio sound to every clip", "callback_url": "https://example.com/webhooks/descript/job_callback" } } } } }, "description": "AI agent request", "required": true }, "responses": { "201": { "description": "Agent edit job created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the Agent edit job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "drive_id": { "type": "string", "format": "uuid", "description": "Drive ID where the project is located", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "drive_name": { "type": "string", "nullable": true, "description": "Human-readable name of the connected drive (workspace)", "example": "My Team Workspace" }, "project_id": { "type": "string", "format": "uuid", "description": "The project ID (existing or newly created)", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID for this agent run. Always returned on POST — no need\nto wait for the job to complete to learn the id. Pass it back as\n`conversation_id` on a subsequent call to continue this conversation.\n", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "resolved_model": { "type": "string", "description": "Model reported for this request: the canonical id for an explicit\nmodel or alias (e.g. `claude-opus-4.8` for `claude-opus`), or\n`auto` for an `auto` request. Lets you confirm the selection\nimmediately, without waiting for the job result. Matches\n`result.resolved_model` on [GET /jobs/{job_id}](#operation/getJob).\n", "example": "claude-opus-4.8" } }, "required": [ "job_id", "drive_id", "project_id", "project_url", "resolved_model", "conversation_id" ] } } } }, "400": { "description": "Invalid input:\n- Malformed request body\n- Invalid project_id or composition_id format\n- Empty or invalid prompt\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "empty_prompt": { "summary": "Empty prompt", "value": { "error": "invalid_input", "message": "Prompt cannot be empty" } }, "invalid_project": { "summary": "Invalid project ID", "value": { "error": "invalid_input", "message": "Invalid project_id format" } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "402": { "description": "Payment Required - insufficient AI credits to start the job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error402" }, "examples": { "insufficient_credits": { "summary": "Insufficient AI credits", "value": { "error": "payment_required", "message": "Insufficient AI credits to start the job (100 credits required, 25 available)" } } } } } }, "403": { "description": "Forbidden - the drive admin has disabled agent usage for this drive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "agent_disabled": { "summary": "Agent usage disabled by admin", "value": { "error": "forbidden", "message": "Agent usage has been disabled by your admin" } } } } } }, "404": { "description": "Not found:\n- Project doesn't exist\n- Composition doesn't exist in the specified project (when composition_id is provided)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "project_not_found": { "summary": "Project not found", "value": { "error": "not_found", "message": "Project not found" } }, "composition_not_found": { "summary": "Composition not found in project", "value": { "error": "not_found", "message": "No composition matching '5b507b2b-e3ef-4146-a0d0-6741df516973' found in project 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/agent/models": { "get": { "tags": [ "API Endpoints" ], "summary": "List agent models", "security": [ { "bearerAuth": [] } ], "description": "List the currently available agent models and the aliases that resolve to them.\n\nThe `model` parameter on [POST /jobs/agent](#operation/agentEditJob) accepts any\nvalue listed under `availableModels[].id` or `aliases[].id`. Aliases let you target\nthe latest\nrecommended model for a given tier without chasing version bumps — for example,\npassing `claude-opus` always routes to whichever Claude Opus version Descript\ncurrently recommends.\n\nThe catalog changes as models launch and retire, so this endpoint's live response\nis the source of truth — the example below is an abridged illustration, not the\nfull list.\n\nCost tiers are coarse buckets — `low`, `medium`, `high` — useful for showing\nusers a relative price/performance signal. Exact pricing is reported per job via\nthe `ai_credits_used` field on [GET /jobs/{job_id}](#operation/getJob).\n\nWhen `model` is omitted on `POST /jobs/agent`, the request defaults to `auto`, which\nselects a recommended model for your account. `auto` is a `medium`-cost option. For an\n`auto` request, `result.resolved_model` on [GET /jobs/{job_id}](#operation/getJob) reports\n`auto`; for an explicit model or alias it reports the canonical id that ran.\n", "operationId": "listAgentModels", "responses": { "200": { "description": "Available agent models and aliases", "content": { "application/json": { "schema": { "type": "object", "required": [ "availableModels", "aliases" ], "properties": { "availableModels": { "type": "array", "description": "Canonical model ids currently advertised by the public agent API,\neach tagged with a coarse cost tier.\n", "items": { "type": "object", "required": [ "id", "cost" ], "properties": { "id": { "type": "string", "description": "Canonical model id to pass as `model` on `POST /jobs/agent`.", "example": "claude-opus-4.8" }, "cost": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Relative cost tier for this model.", "example": "high" } } } }, "aliases": { "type": "array", "description": "Friendly aliases that resolve to one of the `availableModels` at\nrequest time. Pass any alias `id` as `model` and the agent job\nresult's `result.resolved_model` (on\n[GET /jobs/{job_id}](#operation/getJob)) will report the canonical\nid that actually ran.\n", "items": { "type": "object", "required": [ "id", "resolvesTo", "description", "cost" ], "properties": { "id": { "type": "string", "description": "Alias id callers can pass as `model`.", "example": "claude-opus" }, "resolvesTo": { "type": "string", "description": "Canonical model id this alias currently resolves to.", "example": "claude-opus-4.8" }, "description": { "type": "string", "description": "Human-readable description of the alias's intent.", "example": "Tracks stable Anthropic Claude Opus" }, "cost": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Relative cost tier of the model this alias resolves to.", "example": "high" } } } } } }, "examples": { "default_models": { "summary": "Abridged example — call the endpoint for the current list", "value": { "availableModels": [ { "id": "auto", "cost": "medium" }, { "id": "claude-opus-4.8", "cost": "high" }, { "id": "claude-haiku-4.5", "cost": "low" } ], "aliases": [ { "id": "claude-opus", "resolvesTo": "claude-opus-4.8", "description": "Tracks stable Anthropic Claude Opus", "cost": "high" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/jobs/publish": { "post": { "tags": [ "API Endpoints" ], "summary": "Publish project media", "security": [ { "bearerAuth": [] } ], "description": "Publish a project composition to create a shareable link and download the exported file.\n\nPublishes a specific composition from a project, rendering the output as video or audio\nat the specified resolution. When the job completes successfully the result contains both:\n\n- `share_url`: a public URL that can be used to view the published content on Descript's share site.\n- `download_url`: a time-limited signed URL to download the exported media file directly,\n along with `download_url_expires_at` indicating when the link expires.\n\n### Republishing\n\nPublishing the same composition a second time automatically reuses the previous share URL,\noverwriting its content — so bookmarks and links handed out for the first publish keep working.\nRepublish matching is keyed on `(project_id, composition_id, media_type)`, so a Video publish\nand an Audio publish of the same composition produce two separate share URLs.\n\n### Async Operations\n\nPublish jobs run in the background and return a `job_id`. Monitor progress via the [GET /jobs/{job_id}](#operation/getJob) endpoint,\nwhich returns the `share_url`, `download_url`, and `download_url_expires_at` fields once the job finishes.\n\n### Dynamic webhook\n\nIf `callback_url` is provided, Descript will POST the job status to that URL when the job completes or fails.\nThe payload will match the format returned by [GET /jobs/{job_id}](#operation/getJob).\n", "operationId": "publishJob", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Request to publish a project composition.\n", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The ID of the project to publish.", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "composition_id": { "type": "string", "description": "Composition to publish. If omitted, the first composition that has content is\nused, skipping the empty placeholder that leads projects created by an agent or\nimport job.\n\nAccepts any of the following formats:\n- A full composition UUID (e.g. `39677a40-1c43-4c36-8449-46cfbc4de2b5`)\n- A 5-character short ID from a Descript URL (e.g. `39677`)\n- A full Descript project URL (e.g. `https://web.descript.com/{project_id}/39677`)\n", "example": "39677a40-1c43-4c36-8449-46cfbc4de2b5" }, "media_type": { "type": "string", "enum": [ "Video", "Audio" ], "default": "Video", "description": "Media type of the published output. Defaults to `Video` when omitted.\n\nIf the target composition has no video content:\n- omitting `media_type` publishes it as `Audio`\n (the completed job result reports `media_type: Audio`),\n- explicitly requesting `Video` is rejected with a 422.\n" }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p", "1440p", "4K" ], "description": "Resolution for the published output. Only applicable when media_type is Video." }, "callback_url": { "type": "string", "format": "uri", "description": "Optional webhook URL to call when the job completes or fails.\nDescript will POST the job status (same format as [GET /jobs/{job_id}](#operation/getJob)) to this URL.\n", "example": "https://example.com/webhooks/descript/job_callback" }, "access_level": { "type": "string", "enum": [ "public", "unlisted", "drive", "private" ], "description": "Desired access level for the published share page.\nIf omitted, the drive's configured default is used.\nReturns 403 if the requested level is not permitted by the drive's publish settings\n(e.g. requesting `public` when search engine indexing is disabled).\n" } }, "required": [ "project_id" ], "additionalProperties": false }, "examples": { "publish_video": { "summary": "Publish as 1080p video", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "media_type": "Video", "resolution": "1080p" } }, "publish_audio": { "summary": "Publish as audio only", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "media_type": "Audio" } }, "with_callback": { "summary": "Publish with webhook callback", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "media_type": "Video", "resolution": "720p", "callback_url": "https://example.com/webhooks/descript/job_callback" } } } } }, "description": "Publish request", "required": true }, "responses": { "201": { "description": "Publish job created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the publish job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "drive_id": { "type": "string", "format": "uuid", "description": "Drive ID where the project is located", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "drive_name": { "type": "string", "nullable": true, "description": "Human-readable name of the connected drive (workspace)", "example": "My Team Workspace" }, "project_id": { "type": "string", "format": "uuid", "description": "The project ID being published", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" } }, "required": [ "job_id", "drive_id", "project_id", "project_url" ] } } } }, "400": { "description": "Invalid input:\n- Malformed request body\n- Invalid project_id or composition_id format\n- Invalid media_type or resolution value\n- The target composition is empty: either the requested `composition_id` names an\n empty composition, or `composition_id` was omitted and every composition in the\n project is empty. The message names any compositions that do have content, so\n you can retry with one of those.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "invalid_project": { "summary": "Invalid project ID", "value": { "error": "invalid_input", "message": "Invalid project_id format" } }, "invalid_resolution": { "summary": "Invalid resolution", "value": { "error": "invalid_input", "message": "\"resolution\" must be one of [480p, 720p, 1080p, 1440p, 4K]" } }, "empty_composition": { "summary": "Target composition has no content", "value": { "error": "invalid_input", "message": "Composition 39677a40-1c43-4c36-8449-46cfbc4de2b5 (\"Untitled\") is empty and cannot be published. Retry with composition_id set to a composition that has content: 5b507b2b-e3ef-4146-a0d0-6741df516973." } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "403": { "description": "Forbidden:\n- User doesn't have write access to the project\n- Project doesn't belong to the token's drive\n- Requested `access_level` is not permitted by the drive's publish settings\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "forbidden": { "summary": "No access to project", "value": { "error": "forbidden", "message": "Forbidden" } } } } } }, "404": { "description": "Not found:\n- Composition doesn't exist in the specified project (when `composition_id` is provided)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "composition_not_found": { "summary": "Composition not found in project", "value": { "error": "not_found", "message": "No composition matching '5b507b2b-e3ef-4146-a0d0-6741df516973' found in project 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" } } } } } }, "422": { "description": "Unprocessable Entity:\n- `media_type` was explicitly set to `Video` but the target composition has no\n video content. Retry with `media_type` set to `Audio` (or omit it to publish\n as audio).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" }, "examples": { "audio_only_video_request": { "summary": "Audio-only composition requested as video", "value": { "error": "unprocessable_entity", "message": "Composition has no video content and cannot be published as video. Retry with media_type \"Audio\"." } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/export/transcript": { "post": { "tags": [ "API Endpoints" ], "summary": "Export project transcript", "security": [ { "bearerAuth": [] } ], "description": "Export the transcript from a project composition.\n\nSupports plain text, Markdown, HTML, RTF, DOCX, and SRT (SubRip subtitle) formats.\nOptions include speaker labels, timecodes, and markers.\n\nThe response body is the raw transcript file (binary for `docx`,\ntext otherwise) with a `Content-Disposition: attachment` header and\nan `X-Composition-Id` header identifying the exported composition.\n", "operationId": "exportTranscript", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Request to export the transcript from a project composition.", "properties": { "project_id": { "type": "string", "format": "uuid", "description": "The ID of the project to export from.", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "composition_id": { "type": "string", "description": "Composition to export. If omitted, the first composition in the project is used.\n\nAccepts any of the following formats:\n- A full composition UUID (e.g. `39677a40-1c43-4c36-8449-46cfbc4de2b5`)\n- A 5-character short ID from a Descript URL (e.g. `39677`)\n- A full Descript project URL (e.g. `https://web.descript.com/{project_id}/39677`)\n", "example": "39677a40-1c43-4c36-8449-46cfbc4de2b5" }, "format": { "type": "string", "enum": [ "txt", "markdown", "html", "rtf", "docx", "srt" ], "description": "Transcript file format. The response body is the raw transcript file\nin the requested format (binary for `docx`, plain text otherwise).\nThe `srt` format exports a SubRip subtitle file with timed captions.\n" }, "include_speaker_labels": { "type": "string", "enum": [ "off", "changes", "every_paragraph" ], "default": "changes", "description": "Speaker label mode.\n- `off`: No speaker labels\n- `changes`: Show speaker label when the speaker changes\n- `every_paragraph`: Show speaker label on every paragraph\n" }, "include_markers": { "type": "boolean", "default": false, "description": "Include markers in the transcript." }, "timecodes": { "type": "object", "description": "Timecode options. When provided, timecodes are included in\nthe output.\n", "properties": { "frequency_seconds": { "type": "number", "description": "Interval in seconds for timecode insertion." }, "on_paragraphs": { "type": "boolean", "default": false, "description": "Show timecodes at paragraph breaks." }, "on_speakers": { "type": "boolean", "default": false, "description": "Show timecodes at speaker changes." }, "on_markers": { "type": "boolean", "default": false, "description": "Show timecodes at markers." }, "offset_seconds": { "type": "number", "description": "Offset in seconds applied to all timecodes." } }, "additionalProperties": false } }, "required": [ "project_id", "format" ], "additionalProperties": false }, "examples": { "plain_text_with_speakers": { "summary": "Export as plain text with speaker labels", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "format": "txt", "include_speaker_labels": "changes" } }, "markdown_with_timecodes": { "summary": "Export as Markdown with timecodes", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "format": "markdown", "include_speaker_labels": "every_paragraph", "timecodes": { "on_paragraphs": true } } }, "srt_subtitles": { "summary": "Export as SRT subtitles", "value": { "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "format": "srt", "include_speaker_labels": "off" } } } } }, "description": "Transcript export request", "required": true }, "responses": { "200": { "description": "Transcript exported successfully. The response body is the raw\ntranscript file with the appropriate Content-Type for the\nrequested format.\n\nThe `X-Composition-Id` response header contains the composition\nUUID that was exported.\n", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment filename, e.g. `attachment; filename=\"transcript.md\"`" }, "X-Composition-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "The composition ID that was exported" } }, "content": { "text/plain": { "schema": { "type": "string" }, "example": "Speaker 1: Hello, welcome to the show.\n\nSpeaker 2: Thanks for having me." }, "text/markdown": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } }, "application/rtf": { "schema": { "type": "string" } }, "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "format": "binary" } }, "application/x-subrip": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/jobs": { "get": { "tags": [ "API Endpoints" ], "summary": "List jobs", "description": "List recent jobs with optional filtering by project or job type.\n\nBy default, jobs created within the last 7 days are returned. Use `created_after` and\n`created_before` to customize the time range. The maximum lookback is 30 days.\n\nResults are paginated. Use the `cursor` from the response `pagination.next_cursor` to\nfetch subsequent pages.\n\nQuery parameters allow you to filter the results:\n* Filter by `project_id` to see all jobs for a project\n* Filter by `type` to see specific job types (import/project_media, agent)\n", "operationId": "listJobs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "project_id", "description": "Filter by project ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "type", "description": "Filter by job type", "required": false, "schema": { "type": "string", "enum": [ "import/project_media", "agent" ] } }, { "in": "query", "name": "cursor", "description": "Cursor for the next page of results, obtained from `pagination.next_cursor` in a previous response", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "description": "Number of items per page (1-100). Defaults to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "in": "query", "name": "created_after", "description": "Filter jobs created after this timestamp (ISO 8601). Default: 7 days ago. Oldest allowed: 30 days ago.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "created_before", "description": "Filter jobs created before this timestamp (ISO 8601). Default: now.", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Jobs list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobStatus" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Cursor for the next page of results. Absent if no more results." } } } } }, "examples": { "mixed_jobs": { "summary": "List of jobs with different types and states", "value": { "data": [ { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "import/project_media", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:35:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "result": { "status": "success", "media_status": { "Misc/intro.mp4": { "status": "success", "duration_seconds": 10.5 } }, "media_seconds_used": 11 } }, { "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_type": "agent", "job_state": "running", "created_at": "2025-11-18T11:00:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "progress": { "label": "Applying Studio Sound to clip 2...", "last_update_at": "2025-11-18T11:01:00Z" } } ], "pagination": { "next_cursor": "YTFiMmMzZDQtNTY3OC05MGFiLWNkZWYtMTIzNDU2Nzg5MGFi" } } } } } } }, "400": { "description": "Bad request - `project_id` is not a valid UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/jobs/{job_id}": { "get": { "tags": [ "API Endpoints" ], "summary": "Get job status", "security": [ { "bearerAuth": [] } ], "description": "Retrieve the status of any job.\n\nThe response format varies based on job type and includes type-specific fields.\n", "operationId": "getJob", "parameters": [ { "in": "path", "name": "job_id", "description": "The job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" }, "examples": { "import_success": { "summary": "Import job completed successfully", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "import/project_media", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:35:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb/0171c", "result": { "status": "success", "media_status": { "Misc/intro.mp4": { "status": "success", "duration_seconds": 10.5 }, "demo.mp4": { "status": "success", "duration_seconds": 125 } }, "media_seconds_used": 136, "created_compositions": [ { "id": "0171c", "name": "Rough Cut" } ] } } }, "import_partial": { "summary": "Import job partially completed", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "import/project_media", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:35:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb/0171c", "result": { "status": "partial", "media_status": { "Misc/intro.mp4": { "status": "success", "duration_seconds": 10.5 }, "demo.mp4": { "status": "success", "duration_seconds": 125 }, "outro.mp4": { "status": "failed", "error_message": "URL is not accessible or does not support Range requests" } }, "media_seconds_used": 136, "created_compositions": [ { "id": "0171c", "name": "Rough Cut" } ] } } }, "agent_success": { "summary": "Agent job completed successfully", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "agent", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:32:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "result": { "status": "success", "agent_response": "I added Studio Sound to all 3 clips in your composition", "project_changed": true, "media_seconds_used": 0, "ai_credits_used": 150 } } }, "job_running": { "summary": "Job still running", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "import/project_media", "job_state": "running", "created_at": "2025-11-18T10:30:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" } }, "agent_running": { "summary": "Agent job running with progress", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "agent", "job_state": "running", "created_at": "2025-11-18T10:30:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "progress": { "label": "Applying Studio Sound to clip 2", "last_update_at": "2025-11-18T10:32:00Z" } } }, "publish_success": { "summary": "Publish job completed successfully", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "publish", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:35:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb/39677", "result": { "status": "success", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "share_url": "https://share.descript.com/view/abc123", "download_url": "https://storage.googleapis.com/bucket/object?X-Goog-Signature=...", "download_url_expires_at": "2025-11-18T11:35:00Z" } } }, "publish_running": { "summary": "Publish job running with share URL in progress", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "publish", "job_state": "running", "created_at": "2025-11-18T10:30:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "progress": { "label": "Rendering video export", "last_update_at": "2025-11-18T10:32:00Z", "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5", "share_url": "https://share.descript.com/view/abc123" } } }, "publish_failed": { "summary": "Publish job failed", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "publish", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:31:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "result": { "status": "error", "error_message": "Export failed during render" } } }, "job_failed": { "summary": "Job failed", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "import/project_media", "job_state": "stopped", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:31:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "result": { "status": "error", "error_message": "Failed to download media file from URL" } } }, "job_cancelled": { "summary": "Job cancelled", "value": { "job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "job_type": "agent", "job_state": "cancelled", "created_at": "2025-11-18T10:30:00Z", "stopped_at": "2025-11-18T10:31:00Z", "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "403": { "description": "Forbidden - user does not have access to this job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "forbidden": { "summary": "No access to job", "value": { "error": "forbidden", "message": "User does not have access to this job" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "not_found": { "summary": "Job does not exist", "value": { "error": "not_found", "message": "No job found for job_id \"6dc3f30a-58c2-4174-96a6-dc18cf3c7776\"." } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } }, "delete": { "tags": [ "API Endpoints" ], "summary": "Cancel job", "description": "Cancel a running job.\n", "operationId": "cancelJob", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "job_id", "description": "The job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Job cancelled successfully" }, "401": { "description": "Unauthorized - invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } }, "403": { "description": "Forbidden - user does not have access to this job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" }, "examples": { "forbidden": { "summary": "No access to job", "value": { "error": "forbidden", "message": "User does not have access to this job" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" }, "examples": { "not_found": { "summary": "Job does not exist", "value": { "error": "not_found", "message": "No job found for job_id \"6dc3f30a-58c2-4174-96a6-dc18cf3c7776\"." } } } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/projects": { "get": { "tags": [ "API Endpoints" ], "summary": "List projects", "description": "List projects accessible to the authenticated user within a drive.\n\nThe drive is determined from the access token.\n\nResults are paginated. Use the `cursor` from the response `pagination.next_cursor`\nto fetch subsequent pages.\n", "operationId": "listProjects", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "name", "description": "Filter projects whose name contains this string (case-insensitive).", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "folder_path", "description": "Filter projects by folder path (e.g. \"Clients/Acme/Videos\"). Use \"/\" to separate nested folders. Returns only projects directly inside the deepest folder.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "created_by", "description": "Filter projects created by this user UUID. Pass `me` to filter by the authenticated user.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "created_after", "description": "Filter projects created after this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "created_before", "description": "Filter projects created before this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "updated_after", "description": "Filter projects updated after this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "updated_before", "description": "Filter projects updated before this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "sort", "description": "Sort field. Defaults to created_at.", "required": false, "schema": { "type": "string", "enum": [ "name", "created_at", "updated_at", "last_viewed_at" ], "default": "created_at" } }, { "in": "query", "name": "direction", "description": "Sort direction. Defaults to desc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "in": "query", "name": "cursor", "description": "Pagination cursor from a previous response's `pagination.next_cursor`.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "description": "Number of projects per page (1-100). Defaults to 20.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Projects listed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Project ID", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "name": { "type": "string", "description": "Project name", "example": "Marketing Video" }, "created_at": { "type": "string", "format": "date-time", "description": "When the project was created", "example": "2025-11-18T10:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the project was last updated", "example": "2025-11-19T14:00:00Z" }, "folder_path": { "type": "string", "description": "Full folder path for the project (e.g. \"Clients/Acme/Videos\"). Absent when the project is at the drive root.", "example": "Clients/Acme/Videos" } } } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Cursor for the next page. Absent if no more results." } } } } } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/projects/{project_id}": { "get": { "tags": [ "API Endpoints" ], "summary": "Get project details", "description": "Get a detailed project summary including all media files, compositions,\nand existing publishes.\n\nReturns the project's id, name, drive_id, a map of media files (keyed by\ndisplay path) with type and duration, a list of compositions with id,\nname, duration, and media type, and a list of successfully published\nshare pages with their URLs, access levels, and publish times.\n\nUse this to inspect a project's contents before editing or importing media,\nor to retrieve existing share URLs without triggering a republish.\n", "operationId": "getProject", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "project_id", "description": "The project UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "drive_id", "created_at", "updated_at", "media_files", "compositions", "publishes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Project ID" }, "name": { "type": "string", "description": "Project name" }, "drive_id": { "type": "string", "format": "uuid", "description": "Drive ID the project belongs to" }, "created_at": { "type": "string", "format": "date-time", "description": "When the project was created (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the project was last updated (ISO 8601)" }, "folder_path": { "type": "string", "description": "Full folder path for the project (e.g. \"Clients/Acme/Videos\"). Absent when the project is at the drive root.", "example": "Clients/Acme/Videos" }, "media_files": { "type": "object", "description": "Map of display path to media file info", "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "audio", "video", "image", "sequence", "other" ], "description": "Media type" }, "duration": { "type": "number", "format": "float", "description": "Duration in seconds (absent for images)" } } } }, "compositions": { "type": "array", "description": "Compositions in the project", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Composition ID" }, "name": { "type": "string", "description": "Composition name" }, "duration": { "type": "number", "format": "float", "description": "Duration in seconds" }, "media_type": { "type": "string", "description": "Media type of the composition" } } } }, "publishes": { "type": "array", "description": "Successfully published share pages for this project. Each entry represents a composition that has been published and is accessible via its share_url.", "items": { "type": "object", "required": [ "share_url", "composition_id", "access_level", "media_type", "published_at", "updated_at", "name" ], "properties": { "share_url": { "type": "string", "format": "uri", "description": "URL of the published share page", "example": "https://share.descript.com/view/abc123" }, "composition_id": { "type": "string", "format": "uuid", "description": "ID of the composition that was published" }, "access_level": { "type": "string", "enum": [ "public", "unlisted", "drive", "private", "password" ], "description": "Access level of the published share page" }, "media_type": { "type": "string", "enum": [ "video", "audio", "audiogram" ], "description": "Media type of the published output" }, "published_at": { "type": "string", "format": "date-time", "description": "When the publish was created (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the publish was last updated (ISO 8601)" }, "name": { "type": "string", "description": "Name of the published share page" } } } } } } } } }, "400": { "description": "Bad request - `project_id` is not a valid UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "403": { "description": "Forbidden - user does not have access to this project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error403" } } } }, "404": { "description": "Project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/search": { "get": { "tags": [ "API Endpoints" ], "summary": "Search a drive", "description": "Search the drive tied to the personal API token. Matches project names,\nfolder names, layout pack names, media file names, composition text,\nand transcripts across projects, the drive media library, and Brand\nStudio. Returns up to 100 results ranked by relevance.\n", "operationId": "search", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "query", "description": "Search term. Matched against names and contents. Must be non-empty.\n", "required": true, "schema": { "type": "string", "minLength": 1 }, "example": "quarterly update" }, { "in": "query", "name": "updated_after", "description": "Return results updated at or after this time. Accepts an ISO 8601\ndate (`2026-08-01`, interpreted as the start of that UTC day) or\ntimestamp (`2026-08-01T09:30:00Z`). Values without a timezone\noffset are read as UTC.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-01T00:00:00Z" }, { "in": "query", "name": "updated_before", "description": "Return results updated at or before this time. Accepts an ISO 8601\ndate (`2026-08-01`, interpreted as the end of that UTC day) or\ntimestamp (`2026-08-01T23:59:59Z`). Values without a timezone\noffset are read as UTC.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-08-31T23:59:59Z" }, { "in": "query", "name": "owner", "description": "Return items owned by these user UUIDs. Repeat this parameter to\ninclude more than one owner. If omitted, results from all owners\nare returned.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "example": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ] }, { "in": "query", "name": "type", "description": "Result types to search. Repeat this parameter to search more than\none type. If omitted, all result types are returned.\n\n- `project`: Projects\n- `layout_pack`: Layout packs\n- `project_folder`: Folders that hold projects\n- `media_library_folder`: Folders in the drive media library\n- `video`, `image`, `audio`: Files of that media type in the drive\n media library, Brand Studio, and inside projects\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "video", "image", "audio", "project_folder", "media_library_folder", "layout_pack" ] } }, "example": [ "project", "media_library_folder" ] }, { "in": "query", "name": "match", "description": "How the query may match. Repeat this parameter to allow more than\none kind. `name` matches project, file, folder, and layout pack\nnames. `content` matches transcripts and composition text. If\nomitted, names and contents both contribute.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "content" ] } }, "example": [ "content" ] }, { "in": "query", "name": "sort", "description": "How to sort results:\n\n- `relevance`: closest matches first. This is the default.\n- `newest`: most recently modified first.\n- `oldest`: least recently modified first.\n", "required": false, "schema": { "type": "string", "enum": [ "relevance", "newest", "oldest" ], "default": "relevance" }, "example": "newest" }, { "in": "query", "name": "limit", "description": "Maximum number of results to return. Defaults to 30. Maximum is\n100.\n", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "example": 30 } ], "responses": { "200": { "description": "Search completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "mixed": { "summary": "A project hit and a media-library file hit", "value": { "results": [ { "type": "project", "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb", "name": "Quarterly update", "owner": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Ada Lovelace" }, "updated_at": "2026-08-15T14:00:00.000Z" }, { "type": "video", "asset_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "name": "standup.mp4", "location": "media_library", "owner": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Ada Lovelace" }, "updated_at": "2026-08-12T09:30:00.000Z", "duration": 184.5 } ] } }, "brand_studio": { "summary": "A media file in Brand Studio", "value": { "results": [ { "type": "image", "asset_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776", "brand_studio_id": "7c1e2a90-4b3d-4f6a-9c8e-1a2b3c4d5e6f", "name": "logo.png", "location": "brand_studio", "owner": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Ada Lovelace" }, "updated_at": "2026-08-12T09:30:00.000Z" } ] } } } } } }, "400": { "description": "The query is missing or the token is not associated with a drive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error400" } } } }, "401": { "description": "The personal API token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" } } } }, "404": { "description": "The search endpoint is not enabled for the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error404" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/status": { "get": { "tags": [ "API Endpoints" ], "summary": "Check API status", "security": [ { "bearerAuth": [] } ], "description": "Check API availability and validate authentication token.\n\nThis endpoint can be used to:\n- Verify that your authentication token is valid\n- Check API connectivity without performing any heavy operations\n- Identify which drive (workspace) your token is connected to\n\nReturns the connected drive ID and name, plus the API version.\n", "operationId": "getStatus", "responses": { "200": { "description": "Token is valid and API is available", "content": { "application/json": { "schema": { "type": "object", "properties": { "drive_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The drive ID associated with the authentication token, or null if the token has no associated drive", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "drive_name": { "type": "string", "nullable": true, "description": "Human-readable name of the connected drive (workspace), or null if unavailable", "example": "My Team Workspace" }, "api_version": { "type": "string", "description": "Current API version", "example": "1.2" } }, "required": [ "drive_id", "drive_name", "api_version" ] }, "examples": { "success": { "summary": "Successful status check with drive", "value": { "drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2", "drive_name": "My Team Workspace", "api_version": "1.2" } }, "no_drive": { "summary": "Token without associated drive", "value": { "drive_id": null, "drive_name": null, "api_version": "1.2" } } } } } }, "401": { "description": "Unauthorized - missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error401" }, "examples": { "unauthorized": { "summary": "Missing authentication token", "value": { "error": "unauthorized", "message": "Missing or invalid authentication token" } } } } } } } } }, "/published_projects/{publishedProjectSlug}": { "get": { "tags": [ "Export from Descript" ], "summary": "Get Published Project Metadata", "description": "Retrieve metadata for a published Descript project by its URL slug. This endpoint provides information\nabout the published project including title, duration, publisher details, privacy settings, and subtitles.\n\nThis endpoint requires authentication using a personal token and is subject to rate limiting of 1000\nrequests per hour per user.\n", "operationId": "getPublishedProjectMetadata", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "publishedProjectSlug", "description": "The unique URL slug identifying the published project", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved published project metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedProjectMetadata" } } } }, "401": { "description": "Unauthorized - invalid or missing authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedProjectPrivateError" } } } }, "403": { "description": "Forbidden - user does not have access to this published project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedProjectForbiddenError" } } } }, "404": { "description": "Not found - published project does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedProjectError" } } } }, "409": { "description": "Conflict - published project is in an invalid state (processing or failed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedProjectConflictError" } } } }, "429": { "$ref": "#/components/responses/Error429Response" } } } }, "/edit_in_descript/schema": { "post": { "tags": [ "Edit in Descript" ], "summary": "Create Import URL", "description": "Create an Import URL by sending a Project schema to Descript API from your service's backend.\n\n### Import Schema\nOur import schemas are specified as a minimal JSON list of files which is detailed in full at the bottom of this\nsection. At it's smallest, the request body looks like:\n\n```\n{\n \"partner_drive_id\": \"162c61d1-6ced-4b25-a622-7dba922983ee\",\n \"project_schema\": {\n \"schema_version\": \"1.0.0\",\n \"files\": [{\"uri\": \"https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955\"}]\n }\n}\n```\n\n### File Access\nThe file paths provided in the schema need to either be public or pre-signed URIs with enough time before\nexpiration for failures and retries, we suggest URIs that won't expire for 48 hours. We ask that the files have\nalready been saved when the import link is generated to minimize cases where we're waiting for eventually\nconsistent storage of files that will never be written. We will, however, wait for eventual consistency of the\nstorage layer and retry fetching files before eventually timing out.\n\nFiles must be hosted on preapproved hosts as our import process has an allow list which it checks URIs against.\nFiles will be requested with `User-Agent: Descriptbot/1.0` (version may change) for tracking purposes.\n\n### Import link expiration\nImport links are no longer valid after a user imports their data once. Viewing an already used import link will\nnot allow for importing again and will not provide access to a previously created Descript Project. Partners are\nable to generate a new import link at any time, regardless of if a previous import link has been used.\n\nThe API does not currently provide partners with a link to the Descript Project, though users will be redirected\nto it from Descript's web interface the first time they import files, and can always find the Project in Descript.\n\nImport links expire after 3 hours and attempting to use an import link after the pre-signed links in the schema\nfile have expired will result in an error, so we recommend generating the import link after the user has clicked\nthe Edit in Descript button.\n\n### Supported media specification\nWe recommend sending the highest quality, uncompressed versions of files available to you. If you have multiple\ntracks, we recommend prioritizing sending us the full multi-track sequence over a combined file.\n\n* Audio: WAV, FLAC, AAC, MP3\n* Video: h264, HEVC (container: MOV, MP4)\n", "operationId": "postEditInDescriptSchema", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "Edit in Descript schema POST body.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditInDescriptSchemaPostBody" } } } }, "responses": { "201": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditInDescriptSchemaPostResponse" } } } }, "400": { "description": "Invalid input." }, "403": { "description": "Associated drive does not have Edit in Descript permissions." }, "429": { "$ref": "#/components/responses/Error429Response" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Personal API token created in Descript Settings → API Tokens. See the Authentication section for details." } }, "schemas": { "Error400": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_input" }, "message": { "type": "string", "example": "Invalid request body" } }, "required": [ "error", "message" ] }, "Error401": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Missing or invalid authentication token" } }, "required": [ "error", "message" ] }, "Error402": { "type": "object", "properties": { "error": { "type": "string", "example": "payment_required" }, "message": { "type": "string", "example": "Insufficient media minutes to start the job" } }, "required": [ "error", "message" ] }, "Error403": { "type": "object", "properties": { "error": { "type": "string", "example": "forbidden" }, "message": { "type": "string", "example": "User does not have access to this resource" } }, "required": [ "error", "message" ] }, "Error404": { "type": "object", "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "error", "message" ] }, "Error429": { "description": "Rate limit exceeded response. When this error is returned, the response includes headers\nto help you implement proper retry logic:\n- `Retry-After`: Number of seconds to wait before retrying\n- `X-RateLimit-Remaining`: Requests remaining in current window\n- `X-RateLimit-Consumed`: Requests consumed in current window\n", "type": "object", "properties": { "error": { "type": "string", "description": "Error code indicating rate limit was exceeded", "example": "rate_limit_exceeded" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Too many requests" } }, "required": [ "error", "message" ] }, "SearchResponse": { "type": "object", "description": "Ranked search results.", "required": [ "results" ], "properties": { "results": { "type": "array", "description": "Search results ranked by relevance, best match first.", "items": { "oneOf": [ { "type": "object", "title": "Project search result", "description": "A project matched.", "required": [ "type", "project_id", "name", "updated_at", "url" ], "properties": { "type": { "type": "string", "description": "Always `project` for a project result.", "enum": [ "project" ] }, "project_id": { "type": "string", "format": "uuid", "description": "ID of the project. Endpoints that take a\n`project_id` accept it.\n" }, "name": { "type": "string", "description": "Name of the project." }, "url": { "type": "string", "format": "uri", "description": "Link that opens this project in Descript." }, "owner": { "$ref": "#/components/schemas/SearchOwner" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the project was last modified. This is the\nfield `updated_after` and `updated_before` filter\non.\n" } } }, { "type": "object", "title": "Media search result", "description": "A video, audio, or image file in the drive media library,\nBrand Studio, or a project.\n", "required": [ "type", "asset_id", "name", "location", "updated_at", "url" ], "properties": { "type": { "type": "string", "description": "The kind of media: `video`, `audio`, or `image`.\n", "enum": [ "video", "image", "audio" ] }, "asset_id": { "type": "string", "format": "uuid", "description": "ID of the file. Endpoints that take an `asset_id` accept it." }, "project_id": { "type": "string", "format": "uuid", "description": "ID of the project that contains the file. Present\nonly when `location` is `project`.\n" }, "brand_studio_id": { "type": "string", "format": "uuid", "description": "ID of the Brand Studio that contains the file.\nPresent only when `location` is `brand_studio`.\n" }, "name": { "type": "string", "description": "File name of the media file." }, "location": { "type": "string", "description": "Where the file lives: `media_library` in the drive\nmedia library, `project` inside a project, or\n`brand_studio` in Brand Studio.\n", "enum": [ "media_library", "project", "brand_studio" ] }, "url": { "type": "string", "format": "uri", "description": "Link that opens this file in Descript. Files\ninside a project open that project with the file\nhighlighted.\n" }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL of a preview image for\nvideo and image files. Omitted for audio and when\na thumbnail is unavailable.\n" }, "owner": { "$ref": "#/components/schemas/SearchOwner" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the file was last modified. This is the\nfield `updated_after` and `updated_before` filter\non.\n" }, "duration": { "type": "number", "description": "Playback length of the file in seconds. Omitted\nfor images and for files with no duration.\n" } } }, { "type": "object", "title": "Layout pack search result", "description": "A layout pack matched.", "required": [ "type", "project_id", "name", "updated_at", "url" ], "properties": { "type": { "type": "string", "description": "Always `layout_pack` for a layout pack result.", "enum": [ "layout_pack" ] }, "project_id": { "type": "string", "format": "uuid", "description": "ID of the layout pack." }, "name": { "type": "string", "description": "Name of the layout pack." }, "url": { "type": "string", "format": "uri", "description": "Link that opens this layout pack in Descript." }, "owner": { "$ref": "#/components/schemas/SearchOwner" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the layout pack was last modified. This is\nthe field `updated_after` and `updated_before`\nfilter on.\n" } } }, { "type": "object", "title": "Project folder search result", "description": "A folder that holds projects.", "required": [ "type", "folder_id", "name", "updated_at", "url" ], "properties": { "type": { "type": "string", "description": "Always `project_folder`. The folder holds projects.", "enum": [ "project_folder" ] }, "folder_id": { "type": "string", "format": "uuid", "description": "ID of the folder." }, "name": { "type": "string", "description": "Name of the folder." }, "url": { "type": "string", "format": "uri", "description": "Link that opens this project folder in Descript." }, "owner": { "$ref": "#/components/schemas/SearchOwner" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the folder was last modified. This is the\nfield `updated_after` and `updated_before` filter\non.\n" } } }, { "type": "object", "title": "Media library folder search result", "description": "A folder in the drive media library.", "required": [ "type", "folder_id", "name", "location", "updated_at", "url" ], "properties": { "type": { "type": "string", "description": "Always `media_library_folder`. The folder holds\nmedia library files.\n", "enum": [ "media_library_folder" ] }, "folder_id": { "type": "string", "format": "uuid", "description": "ID of the folder." }, "name": { "type": "string", "description": "Name of the folder." }, "location": { "type": "string", "description": "Always `media_library` for a media-library folder.", "enum": [ "media_library" ] }, "url": { "type": "string", "format": "uri", "description": "Link that opens this media library folder in\nDescript.\n" }, "owner": { "$ref": "#/components/schemas/SearchOwner" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the folder was last modified. This is the\nfield `updated_after` and `updated_before` filter\non.\n" } } } ] } } } }, "EditInDescriptSchemaPostBody": { "type": "object", "properties": { "partner_drive_id": { "type": "string", "format": "uuid", "description": "The drive id associated with the auth token.", "example": "aa3b2d8d-e5ca-41c2-8801-683328293fb9" }, "project_schema": { "type": "object", "description": "The Project schema", "properties": { "schema_version": { "type": "string", "format": "string", "description": "Schema version id.", "example": "1.0.0" }, "source_id": { "type": "string", "format": "string", "description": "External source id to be included in Descript export pages, see Export from Descript section for details. This ID is not currently used to deduplicate data coming into Descript, a new Project is created for each import.", "example": "06b3f5bb-68a2-468a-a5d9-df155c1e3588" }, "files": { "type": "array", "description": "List of remote files to import into Descript.", "items": { "type": "object", "properties": { "name": { "type": "string", "format": "string", "description": "A name for the file." }, "uri": { "type": "string", "format": "url", "description": "A public/pre-signed uri to the audio or video asset, see supported media specifications section." }, "start_offset": { "type": "object", "description": "The amount of time into the Project's timeline this audio or video file should start at.", "properties": { "seconds": { "type": "number", "description": "Float number of seconds into the timeline." } } } }, "example": { "name": "Jane's studio recording", "uri": "https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955", "start_offset": { "seconds": 10 } }, "required": [ "uri" ] } } }, "required": [ "schema_version", "files" ] } }, "required": [ "partner_drive_id", "project_schema" ] }, "EditInDescriptSchemaPostResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "example": "https://web.descript.com/import?nonce=6e3625ca-f885-460d-b2e3-e3faac79c788", "description": "A url for partners to redirect their user to in order to start the import process—expires after 3 hours." } } }, "PublishedProjectMetadata": { "type": "object", "description": "Metadata for a successfully published Descript project", "properties": { "download_url": { "type": "string", "format": "uri", "description": "A time-limited signed URL for downloading the original published media file. See download_url_expires_at for expiration date.", "example": "https://storage.googleapis.com/bucket/file.mp4?X-Goog-Signature=..." }, "download_url_expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp indicating when the download_url expires. Present when download_url is present.", "example": "2025-01-16T10:30:00.000Z" }, "project_id": { "type": "string", "format": "uuid", "description": "The unique identifier of the source Descript project", "example": "12345678-1234-5678-1234-567812345678" }, "publish_type": { "type": "string", "enum": [ "audio", "video", "audiogram" ], "description": "The type of published project", "example": "video" }, "privacy": { "type": "string", "enum": [ "public", "unlisted", "private", "drive", "password" ], "description": "The access permission level for this published project", "example": "unlisted" }, "metadata": { "type": "object", "description": "Detailed metadata about the published project", "properties": { "title": { "type": "string", "description": "The title of the published project", "example": "My Video Project" }, "duration_seconds": { "type": "number", "description": "Duration of the published content in seconds (rounded to nearest millisecond)", "example": 125.456 }, "duration_formatted": { "type": "string", "description": "Human-readable duration in HH:MM:SS format", "example": "00:02:05" }, "published_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the project was published", "example": "2025-01-15T10:30:00.000Z" }, "published_by": { "type": "object", "description": "Information about the user who published the project", "properties": { "first_name": { "type": "string", "description": "First name of the publisher", "example": "Jane" }, "last_name": { "type": "string", "description": "Last name of the publisher", "example": "Doe" } } } } }, "subtitles": { "type": "string", "description": "Full VTT-formatted subtitle/caption content for the published project", "example": "WEBVTT\\n\\n00:00:00.000 --> 00:00:02.000\\nWelcome to my video" } }, "required": [ "project_id", "publish_type", "privacy", "metadata", "subtitles" ] }, "PublishedProjectError": { "type": "object", "description": "Error response for published project requests", "properties": { "error": { "type": "string", "enum": [ "not_found", "unauthorized", "forbidden" ], "description": "Error type identifier", "example": "not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Published project not found" } }, "required": [ "error", "message" ] }, "PublishedProjectPrivateError": { "type": "object", "description": "Error response when published project is private to drive and user is unauthenticated", "properties": { "error": { "type": "string", "enum": [ "unauthorized" ], "description": "Error type identifier", "example": "unauthorized" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Private to drive, user must log in to account with access." } } }, "PublishedProjectForbiddenError": { "type": "object", "description": "Error response when the user does not have access to the published project", "properties": { "error": { "type": "string", "enum": [ "forbidden" ], "description": "Error type identifier", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "User id 00000000-0000-0000-0000-000000000000 does not have access to this project" } } }, "PublishedProjectConflictError": { "type": "object", "description": "Error response when published project is in an invalid state", "properties": { "error": { "type": "string", "enum": [ "conflict" ], "description": "Error type identifier", "example": "conflict" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Published in invalid state" }, "state": { "type": "string", "enum": [ "processing", "failed" ], "description": "Current state of the published project", "example": "processing" } }, "required": [ "error", "message", "state" ] }, "ImportSuccessResult": { "type": "object", "title": "ImportSuccessResult", "description": "Result when media was imported (fully or partially)", "properties": { "status": { "type": "string", "enum": [ "success", "partial" ], "description": "- success: All media imported successfully\n- partial: Some media imported successfully, some failed\n", "example": "success" }, "media_status": { "type": "object", "description": "Status of each media item in the import.\nKeys are the media reference IDs from the request.\n", "additionalProperties": { "type": "object", "description": "Status information for a single media import", "properties": { "status": { "type": "string", "enum": [ "success", "failed" ], "description": "Status of this individual media import" }, "duration_seconds": { "type": "number", "format": "float", "description": "Duration of the imported media in seconds (only present for successful imports)", "example": 125.5 }, "error_message": { "type": "string", "description": "Error message if the import failed (only present for failed imports)", "example": "URL is not accessible or does not support Range requests" } }, "required": [ "status" ] }, "example": { "Misc/intro.mp4": { "status": "success", "duration_seconds": 10.5 }, "demo.mp4": { "status": "success", "duration_seconds": 125 } } }, "media_seconds_used": { "type": "integer", "description": "Total media seconds consumed by this import", "example": 75 }, "created_compositions": { "type": "array", "description": "Compositions created during import", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "0daabc7a-437a-43eb-b04b-b398d502f393" }, "name": { "type": "string", "example": "Rough Cut" } } } } }, "required": [ "status", "media_status", "media_seconds_used" ] }, "ImportErrorResult": { "type": "object", "title": "ImportErrorResult", "description": "Result when job failed completely", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Job failed completely", "example": "error" }, "error_message": { "type": "string", "description": "Human-readable error message", "example": "Failed to import media files" }, "error_code": { "type": "string", "description": "Machine-readable error code", "example": "import_failed" } }, "required": [ "status", "error_message" ] }, "ImportJobStatus": { "type": "object", "description": "Status of an import job", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "job_type": { "type": "string", "enum": [ "import/project_media" ], "description": "Type of job" }, "job_state": { "type": "string", "enum": [ "queued", "running", "stopped", "cancelled" ], "description": "Current state of the job:\n- queued: Job is waiting to start\n- running: Job is actively processing\n- stopped: Job has finished (check result.status for outcome)\n- cancelled: Job was cancelled by user\n", "example": "stopped" }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created", "example": "2025-11-18T10:30:00Z" }, "stopped_at": { "type": "string", "format": "date-time", "description": "When the job stopped (only present when job_state is stopped or cancelled)", "example": "2025-11-18T10:35:00Z" }, "drive_id": { "type": "string", "format": "uuid", "description": "The drive ID", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "project_id": { "type": "string", "format": "uuid", "description": "The project ID", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "progress": { "type": "object", "description": "Progress information for the workflow (only present when job_state is running)", "properties": { "label": { "type": "string", "description": "Human-readable label describing the current action", "example": "Importing media..." }, "percent": { "type": "integer", "description": "Percentage of the workflow that has been completed", "example": 50 }, "last_update_at": { "type": "string", "format": "date-time", "description": "When the progress was last updated", "example": "2025-11-18T10:32:00Z" } }, "required": [ "label" ] }, "result": { "description": "Job result (only present when job_state is stopped)", "oneOf": [ { "$ref": "#/components/schemas/ImportSuccessResult" }, { "$ref": "#/components/schemas/ImportErrorResult" } ], "discriminator": { "propertyName": "status", "mapping": { "success": "#/components/schemas/ImportSuccessResult", "partial": "#/components/schemas/ImportSuccessResult", "error": "#/components/schemas/ImportErrorResult" } } } }, "required": [ "job_id", "job_type", "job_state", "created_at", "drive_id", "project_id", "project_url" ] }, "AgentSuccessResult": { "type": "object", "title": "AgentSuccessResult", "description": "Result when Agent edit completed successfully", "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Indicates successful completion", "example": "success" }, "agent_response": { "type": "string", "description": "AI response describing what was done", "example": "I added Studio Sound to all 3 clips in your composition" }, "project_changed": { "type": "boolean", "description": "Whether the agent made modifications to the project", "example": true }, "media_seconds_used": { "type": "integer", "description": "Media minutes (in seconds) consumed by this operation", "example": 34 }, "ai_credits_used": { "type": "integer", "description": "AI credits consumed by this operation", "example": 5 }, "resolved_model": { "type": "string", "description": "Model reported for this job: the canonical id for an explicit model or\nalias (e.g. `claude-opus-4.8` for `claude-opus`), `auto` for an `auto`\nrequest, or `inherited` when a resume keeps the conversation's model.\nPresent on jobs submitted via the public API after the model-aliases\nlaunch; older jobs may omit it.\n", "example": "claude-opus-4.8" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID for this agent session. Pass this value as `conversation_id` in a\nsubsequent [POST /jobs/agent](#operation/agentEditJob) request to continue the conversation.\n", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "required": [ "status", "agent_response", "project_changed" ] }, "AgentErrorResult": { "type": "object", "title": "AgentErrorResult", "description": "Result when Agent edit failed", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Indicates the job failed", "example": "error" }, "error_message": { "type": "string", "description": "Human-readable error message", "example": "AI agent failed to process the request" }, "error_code": { "type": "string", "description": "Machine-readable error code", "example": "agent_execution_failed" }, "resolved_model": { "type": "string", "description": "Model reported for this job: the canonical id for an explicit model or\nalias, `auto` for an `auto` request, or `inherited` when a resume keeps\nthe conversation's model. Present on jobs submitted via the public API\nafter the model-aliases launch; older jobs may omit it.\n", "example": "claude-opus-4.8" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID for this agent session, if one was created before the error occurred.\n", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "required": [ "status", "error_message" ] }, "AgentJobStatus": { "type": "object", "description": "Status of an Agent edit job", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "job_type": { "type": "string", "enum": [ "agent" ], "description": "Type of job", "example": "agent" }, "job_state": { "type": "string", "enum": [ "queued", "running", "stopped", "cancelled" ], "description": "Current state of the job:\n- queued: Job is waiting to start\n- running: Job is actively processing\n- stopped: Job has finished (check result.status for outcome)\n- cancelled: Job was cancelled by user\n", "example": "stopped" }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created", "example": "2025-11-18T10:30:00Z" }, "stopped_at": { "type": "string", "format": "date-time", "description": "When the job stopped (only present when job_state is stopped or cancelled)", "example": "2025-11-18T10:35:00Z" }, "drive_id": { "type": "string", "format": "uuid", "description": "The drive ID", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "project_id": { "type": "string", "format": "uuid", "description": "The project ID", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "progress": { "type": "object", "description": "Progress information for the workflow (only present when job_state is running)", "properties": { "label": { "type": "string", "description": "Human-readable label describing the current action", "example": "Applying Studio Sound to clip 2..." }, "percent": { "type": "integer", "description": "Percentage of the workflow that has been completed", "example": 50 }, "last_update_at": { "type": "string", "format": "date-time", "description": "When the progress was last updated", "example": "2025-11-18T10:32:00Z" } }, "required": [ "label" ] }, "result": { "description": "Job result (only present when job_state is stopped)", "oneOf": [ { "$ref": "#/components/schemas/AgentSuccessResult" }, { "$ref": "#/components/schemas/AgentErrorResult" } ], "discriminator": { "propertyName": "status", "mapping": { "success": "#/components/schemas/AgentSuccessResult", "error": "#/components/schemas/AgentErrorResult" } } } }, "required": [ "job_id", "job_type", "job_state", "created_at", "drive_id", "project_id", "project_url" ] }, "PublishSuccessResult": { "type": "object", "description": "Result when publish completed successfully", "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Indicates successful completion" }, "composition_id": { "type": "string", "description": "Identifier of the published composition", "example": "39677a40-1c43-4c36-8449-46cfbc4de2b5" }, "share_url": { "type": "string", "format": "uri", "description": "Public URL to view the published content", "example": "https://share.descript.com/view/abc123" }, "media_type": { "type": "string", "enum": [ "Video", "Audio" ], "description": "The media type the composition was actually published as. For an audio-only composition published with the default Video request, this is Audio.\n", "example": "Audio" }, "download_url": { "type": "string", "format": "uri", "description": "Time-limited signed URL to download the original published media file. Present when the job completed successfully and signing succeeded.\n", "example": "https://storage.googleapis.com/bucket/object?X-Goog-Signature=..." }, "download_url_expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 time when download_url expires (if download_url is set)" } }, "required": [ "status", "composition_id", "share_url" ] }, "PublishErrorResult": { "type": "object", "description": "Result when publish failed", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Indicates the publish job failed" }, "error_message": { "type": "string", "description": "Human-readable error message", "example": "Export failed during render" } }, "required": [ "status", "error_message" ] }, "PublishJobStatus": { "type": "object", "description": "Status of a publish job", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the job", "example": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776" }, "job_type": { "type": "string", "enum": [ "publish" ], "description": "Type of job" }, "job_state": { "type": "string", "enum": [ "queued", "running", "stopped", "cancelled" ], "description": "Current state of the job:\n- queued: Job is waiting to start\n- running: Job is actively processing\n- stopped: Job has finished (check result.status for outcome)\n- cancelled: Job was cancelled by user\n", "example": "stopped" }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created", "example": "2025-11-18T10:30:00Z" }, "stopped_at": { "type": "string", "format": "date-time", "description": "When the job stopped (only present when job_state is stopped or cancelled)", "example": "2025-11-18T10:35:00Z" }, "drive_id": { "type": "string", "format": "uuid", "description": "The drive ID", "example": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2" }, "project_id": { "type": "string", "format": "uuid", "description": "The project ID", "example": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "project_url": { "type": "string", "format": "uri", "description": "URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.", "example": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb" }, "progress": { "type": "object", "description": "Progress information for the workflow (only present when job_state is running)", "properties": { "label": { "type": "string", "description": "Human-readable label describing the current action", "example": "Exporting composition..." }, "percent": { "type": "integer", "description": "Percentage of the workflow that has been completed", "example": 50 }, "last_update_at": { "type": "string", "format": "date-time", "description": "When the progress was last updated", "example": "2025-11-18T10:32:00Z" }, "composition_id": { "type": "string", "description": "Composition being published (present when known)", "example": "39677a40-1c43-4c36-8449-46cfbc4de2b5" }, "share_url": { "type": "string", "format": "uri", "description": "Share URL when available before the job completes", "example": "https://share.descript.com/view/abc123" } }, "required": [ "label" ] }, "result": { "description": "Job result (only present when job_state is stopped)", "oneOf": [ { "$ref": "#/components/schemas/PublishSuccessResult" }, { "$ref": "#/components/schemas/PublishErrorResult" } ], "discriminator": { "propertyName": "status", "mapping": { "success": "#/components/schemas/PublishSuccessResult", "error": "#/components/schemas/PublishErrorResult" } } } }, "required": [ "job_id", "job_type", "job_state", "created_at", "drive_id", "project_id", "project_url" ] }, "JobStatus": { "oneOf": [ { "$ref": "#/components/schemas/ImportJobStatus" }, { "$ref": "#/components/schemas/AgentJobStatus" }, { "$ref": "#/components/schemas/PublishJobStatus" } ], "discriminator": { "propertyName": "job_type", "mapping": { "import/project_media": "#/components/schemas/ImportJobStatus", "agent": "#/components/schemas/AgentJobStatus", "publish": "#/components/schemas/PublishJobStatus", "export/timeline": "#/components/schemas/TimelineExportJobStatus" } }, "description": "Status of an async job. The response structure varies based on the job type.\nUse the `job_type` field to determine which fields will be present.\n" }, "SearchOwner": { "type": "object", "description": "Owner of the search result. Omitted when the owner is unavailable.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "User ID of the owner." }, "name": { "type": "string", "description": "Display name of the owner." } } } }, "responses": { "Error429Response": { "description": "Too many requests - rate limit exceeded.\nUse the `Retry-After` header to determine when to retry.\n", "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying the request", "schema": { "type": "integer" }, "example": 30 }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current rate limit window", "schema": { "type": "integer" }, "example": 0 }, "X-RateLimit-Consumed": { "description": "Number of requests consumed in the current rate limit window", "schema": { "type": "integer" }, "example": 100 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error429" }, "examples": { "rate_limit": { "summary": "Rate limit exceeded", "value": { "error": "rate_limit_exceeded", "message": "Too many requests. Please try again later." } } } } } } } }, "x-tagGroups": [ { "name": "Public API", "tags": [ "Getting started", "Using the CLI", "API Endpoints", "Direct file upload", "Authentication", "Rate Limiting" ] }, { "name": "Partner APIs", "tags": [ "Edit in Descript", "Export from Descript" ] } ] }