Create an API token, import media into a new project, and prompt Underlord for edits.
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.
In Descript, open Settings and select API tokens from the sidebar. Then 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.
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
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
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" }'
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
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 }}
Assistant
Responses are generated using AI and may contain mistakes.
