> ## Documentation Index
> Fetch the complete documentation index at: https://help.descript.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> 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](https://descript.com/api).
## Create an API token
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.
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](/developers/api-reference/import/import-project-media). 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](/developers/guides/direct-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](/developers/api-reference/jobs/get-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**
```bash theme={null}
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**
```json theme={null}
{
"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](/developers/api-reference/jobs/get-job) 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**
```bash theme={null}
curl https://descriptapi.com/v1/jobs/project-media-import-9d635d5b \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
**Response**
```json theme={null}
{
"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](/developers/api-reference/agent/create-agent-edit) 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](/developers/api-reference/jobs/get-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**
```bash theme={null}
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**
```json theme={null}
{
"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](/developers/api-reference/jobs/get-job) 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**
```bash theme={null}
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**
```json theme={null}
{
"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
}
}
```