Descript API (1.0)

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

To sign up for access and learn more, visit descript.com/enterprise/api-early-access.

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 installed on your computer. Node.js is a JavaScript runtime that allows you to run JavaScript programs from the command line.

Required version: Node.js 24 or higher

Check if Node.js is already installed

Open your terminal (or Command Prompt on Windows) and run:

node --version

If you see a version number like v24.x.x or higher, you're all set and can skip to the next section. If you see an error or a lower version number, follow the installation steps below.

Installing Node.js

Choose the installation method for your operating system:

macOS

Option 1: Using the installer (recommended for beginners)

1. Visit nodejs.org
2. Download the "LTS" (Long Term Support) version
3. Open the downloaded file and follow the installation prompts

Option 2: Using Homebrew

brew install node

Windows

1. Visit nodejs.org
2. Download the "LTS" (Long Term Support) version for Windows
3. Run the downloaded installer and follow the installation prompts

Linux

Ubuntu/Debian:

# Install Node.js from NodeSource
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora/RHEL/CentOS:

# Install Node.js from NodeSource
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs

After installation, verify it worked by running node --version again.

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"

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

Descript API uses a personal token to authenticate your request. You can get your personal token by contacting us.

The personal token should be used as a bearer token in the authorization header.

Example

curl -H "authorization: Bearer ${YOUR_PERSONAL_TOKEN}" -d @datafile.json https://descriptapi.com/v1/edit_in_descript/schema

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.