Descript API

Early Access: These APIs are still under active development, and may change and evolve over time. We're thankful for your input, and excited to build with you.

The Descript API lets you programmatically create projects, import media, and edit your projects — all without opening the app.

To learn more, visit descript.com/api.

1. In Descript, open Settings and select API tokens from the sidebar. Then click Create token.

2. Give your token a name and select the Drive it should be associated with. Click Create token.

3. 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.

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.

Include the token as a Bearer token in the Authorization header of your API requests.

You can create a new project, import media, and place the media into a composition all in one API request using the import endpoint. This step also transcribes and processes the media so that it's ready for you or the agent to edit.

To 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.

Importing and processing is an asynchronous job, so the response payload will contain a job_id for you to query the status of the job 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.

Request

curl -X POST https://descriptapi.com/v1/jobs/import/project_media \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "My First Video",
    "add_media": {
      "demo.mp4": {
        "url": "https://test-files.descriptapi.com/demo_video.mp4"
      }
    },
    "add_compositions": [
      {
        "name": "Demo Video",
        "clips": [
          { "media": "demo.mp4" }
        ]
      }
    ]
  }'

Response

{
  "job_id": "project-media-import-9d635d5b",
  "drive_id": "c9c5c47e",
  "project_id": "e2f89ce6",
  "project_url": "https://web.descript.com/e2f89ce6"
}

Poll the job status endpoint 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.

You 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.

Request

curl https://descriptapi.com/v1/jobs/project-media-import-9d635d5b \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "job_id": "project-media-import-9d635d5b",
  "job_type": "import/project_media",
  "job_state": "stopped",
  "project_id": "e2f89ce6",
  "project_url": "https://web.descript.com/e2f89ce6",
  "result": {
    "status": "success",
    "media_status": {
      "main.mp4": {
        "status": "success",
        "duration_seconds": 69.477006
      }
    },
    "created_compositions": [
      { "id": "f8e5088a-4d53-4aab-9d4f-c6624b7d7622", "name": "Demo Video" }
    ]
  }
}

Once your media is imported, you can use the agent edit endpoint 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.

Editing can take some time, so the response also returns a job_id that you can use to check the status of the job. 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.

Request

curl -X POST https://descriptapi.com/v1/jobs/agent \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "e2f89ce6",
    "prompt": "Add studio sound and captions"
  }'

Response

{
  "job_id": "project-agent-edit-e2f89ce6",
  "drive_id": "c9c5c47e",
  "project_id": "e2f89ce6",
  "project_url": "https://web.descript.com/e2f89ce6"
}

Poll the job status endpoint 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.

Request

curl https://descriptapi.com/v1/jobs/project-agent-edit-e2f89ce6 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Once 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.

Response

{
    "job_id":"project-agent-edit-e2f89ce6",
    "job_type":"agent",
  "project_id":"YOUR_PROJECT_ID",
    "project_url":"https://web.descript.com/e2f89ce6",
    "job_state":"stopped",
    "created_at":"2026-02-09T05:42:27.554Z",
    "stopped_at":"2026-02-09T05:43:15.296Z",
    "drive_id":"1df135a5-dc4a-4dc3-8f7d-681cfbe961e4",
    "result":{
        "status":"success",
    "agent_response":"Done! I've applied Studio Sound to enhance your audio quality and added classic karaoke-style captions to your video.",
        "project_changed":true,
        "media_seconds_used":0,
        "ai_credits_used":32
  }
}

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.

Before installing the CLI, you'll need Node.js 24 or higher. Visit nodejs.org to download and install the latest LTS version for your operating system.

First, install the latest version of the CLI using npm.

npm install -g @descript/platform-cli@latest

Next, configure the CLI with your API key.

descript-api config set api-key

Use 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.

descript-api import \
  --name "My First Project" \
  --media "https://test-files.descriptapi.com/demo-video.mp4"

Use the agent command to edit a project by passing in the project id and an Underlord prompt.

descript-api agent \
  --project-id YOUR_PROJECT_ID \
  --prompt "Remove filler words and add Studio Sound to all clips"

You can also ask Underlord create a new project from a prompt alone by writing the script for you!

descript-api edit --new \
  --prompt "Write a script about how to make great coffee"

Run descript-api help to see the full list of available commands and options.

Import media, edit projects with AI, and query jobs and projects.

The Descript API uses personal API tokens to authenticate requests. Tokens are scoped to a specific Drive and inherit your permissions on that Drive.

To create a token, see the Getting Started guide.

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.

Include the token as a Bearer token in the Authorization header of your API requests.

Example

curl -H "Authorization: Bearer YOUR_API_TOKEN" https://descriptapi.com/v1/status

The Descript API implements rate limiting to ensure fair usage and protect service availability. When you exceed the rate limit, the API returns a 429 Too Many Requests response.

When a rate limit is exceeded, the response includes the following headers:

When you receive a 429 response, use the Retry-After header to determine how long to wait before retrying. This approach is more efficient than using fixed delays or exponential backoff alone.

Note: The Edit in Descript integration requires contacting Descript for access. Reach out to us to get started.

Edit in Descript API enables partners to give their users the ability to transfer audio or video content to Descript for editing.

Edit in Descript buttons work by generating one-time use, public Import URLs to the Descript import UI that users can be automatically sent to. On that page, they can make a few simple selections before kicking off a Partner cloud storage to Descript cloud storage transfer. This will redirect them to a Descript Project ready for editing.

Partners can initiate the request by securely sending an information schema backend-to-backend to the Descript API using a token, in exchange for the Import URL to redirect the user. Partners do not need to store this schema, as Descript will do so and use it to start fetching the files when the user confirms the action

1. When a user clicks Edit in Descript, partner's backend service makes POST request to: https://descriptapi.com/v1/edit_in_descript/schema with an authorization bearer token header and JSON schema body
2. Descript responds with either an Import URL or an error
3. Partner redirects the user's browser to the URL returned in step 2 or display an error message and link to help documentation

Partner User Experience

Some guidelines for partners as you consider this integration:

• We recommend placing the Edit in Descript option next to your download options
  • If you offer multiple download options, such as combined vs. split audio/video files, we recommend placing this integration clearly in context with each option, or only the supported option, to help users understand what will be exported.
  • Each time you request an import link, a new one is generated. Import links expire after 3 hours. After using an import link, the only way to find an imported Project again is in Descript.
  • If an import link has expired or the contents of the schema has changed, please request a new import link with the updated schema. This will create a new Descript Project when used.
• We will provide Descript-branded assets to fit your proposed placement of the Edit in Descript CTA and ask that you don't edit the assets beyond what we provide. We are happy to work with you on getting you the right assets for your placement.
• Partners should provide error-handling for the POST request, at minimum displaying a generic error message and linking to a help article (we can provide a link for this if you prefer).
• Progress will be conveyed to the user in the Descript side of the user experience.

Descript User Experience

When users are directed to a Descript Import URL, they'll be asked to either create an account or login in order to proceed.

Next, they will be presented with a few options about how they'd like to import the data, such as where the new Descript Project should be created.

They'll then be redirected to the Project, where they can monitor the progress of the import and start editing.

Users of Descript currently have three options to export their edited content. They can export files in various formats, share a Descript link, or use our one-click cloud export to publish directly to a partner.

Roundtrip Metadata

If Project data previously came from a partner via an Edit in Descript schema then any Descript Export pages will include <meta/> tags which contains the partner_drive_id and source_id provided when originally importing into Descript. This allows partners to deduplicate data returning back to partner systems after editing in Descript. Both partner and source properties are included on all public Descript Export pages.

<meta property="descript:partner" content="9121bf3a-60fe-4a31-ad59-ed32df610cc3" />
<meta property="descript:source" content="409148bd-81aa-4af6-a9c3-29b761506f3a" />