Quickstart

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.

Create an API token

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

Navigate to Settings > API tokens and click Create token

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

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.

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.

Import media into a new project

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. To upload a local file instead, see Direct file upload. 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"
}

Check for import completion

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" }
    ]
  }
}

Prompt for edits with Agent Underlord

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"
}

Wait for the agent to complete its job

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
  }
}

Get started

Guides

MCP

Partner integrations

API endpoints

Create an API token

Import media into a new project

Check for import completion

Prompt for edits with Agent Underlord

Wait for the agent to complete its job

​Create an API token

​Import media into a new project

​Check for import completion

​Prompt for edits with Agent Underlord

​Wait for the agent to complete its job

Create an API token

Import media into a new project

Check for import completion

Prompt for edits with Agent Underlord

Wait for the agent to complete its job