curl --request POST \
--url https://descriptapi.com/v1/jobs/agent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"project_name": "Cooking Tips Video",
"prompt": "create a 30-second video about cooking tips with background music"
}
'{
"job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776",
"drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2",
"project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
"project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
"conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resolved_model": "claude-opus-4.8",
"drive_name": "My Team Workspace"
}Agent edit
Use a background agent to create and edit projects using a natural language prompt.
- Edit existing project: Provide a
project_idto edit an existing project - Target a specific composition: Provide both
project_idandcomposition_idto direct the agent to a specific composition within the project - Create new project: Provide a
project_nameinstead ofproject_idto create a new project
Common use cases
- Create new content: “create a 30-second video about cooking tips”
- Apply audio effects: “add studio sound to every clip”
- Remove filler words: “remove all filler words from the transcript”
- Create highlights: “create a 30-second highlight reel”
- Content editing: “remove the section from 1:30 to 2:15”
Async Operations
Agent edits run in the background and return a job_id. Monitor progress via the GET /jobs/ endpoint.
Dynamic webhook
If callback_url is provided, Descript will POST the job status to that URL when the job completes or fails.
The payload will match the format returned by GET /jobs/.
curl --request POST \
--url https://descriptapi.com/v1/jobs/agent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"project_name": "Cooking Tips Video",
"prompt": "create a 30-second video about cooking tips with background music"
}
'{
"job_id": "6dc3f30a-58c2-4174-96a6-dc18cf3c7776",
"drive_id": "c9c5c47e-158a-49f7-846b-4f6ee2a229a2",
"project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
"project_url": "https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
"conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resolved_model": "claude-opus-4.8",
"drive_name": "My Team Workspace"
}Authorizations
Personal API token created in Descript Settings → API Tokens. See the Authentication section for details.
Body
AI agent request
Request to run Agent edit.
The agent will interpret the prompt and either edit an existing project or create a new one.
You must provide exactly one of project_id or project_name.
Natural language instruction for the agent to execute. Examples: "add studio sound to every clip", "remove all filler words", "create a 30-second highlight reel"
"add studio sound to every clip"
The ID of an existing project to edit. Mutually exclusive with project_name.
"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"
Name for creating a new project. Mutually exclusive with project_id.
"My New Project"
Composition to target within the project. When provided,
the agent will focus its edits on this specific composition rather
than choosing one automatically. Only valid when project_id is also
provided. Requires project_id.
Accepts any of the following formats:
- A full composition UUID (e.g.
39677a40-1c43-4c36-8449-46cfbc4de2b5) - A 5-character short ID from a Descript URL (e.g.
39677) - A full Descript project URL (e.g.
https://web.descript.com/{project_id}/39677)
"39677a40-1c43-4c36-8449-46cfbc4de2b5"
AI model to use for editing. Accepts a canonical model id
(e.g. claude-opus-4.8) or a friendly alias that tracks the
stable version of a family (e.g. claude-opus). Call
GET /agent/models for the current
set of supported models and aliases.
Defaults to auto when omitted, which selects a recommended
model for your account.
Access level for team members when creating a new project.
Only applicable when project_name is provided (not when using project_id).
Defaults to none if not specified.
edit, comment, view, none Optional webhook URL to call when the job completes or fails. Descript will POST the job status (same format as GET /jobs/{job_id}) to this URL.
"https://example.com/webhooks/descript/job_callback"
Response
Agent edit job created successfully
Unique identifier for the Agent edit job
"6dc3f30a-58c2-4174-96a6-dc18cf3c7776"
Drive ID where the project is located
"c9c5c47e-158a-49f7-846b-4f6ee2a229a2"
The project ID (existing or newly created)
"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"
URL to access the project in Descript web app
"https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"
Conversation ID for this agent run. Always returned on POST — no need
to wait for the job to complete to learn the id. Pass it back as
conversation_id on a subsequent call to continue this conversation.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Model reported for this request: the canonical id for an explicit
model or alias (e.g. claude-opus-4.8 for claude-opus), or
auto for an auto request. Lets you confirm the selection
immediately, without waiting for the job result. Matches
result.resolved_model on GET /jobs/{job_id}.
"claude-opus-4.8"
Human-readable name of the connected drive (workspace)
"My Team Workspace"