v3

latestOpenAPI 3.0.0Proprietary2026-08-041323140.2 KB

API Endpoints

Agent edit

Use a background agent to create and edit projects using a natural language prompt.

Edit existing project: Provide a project_id to edit an existing project
Target a specific composition: Provide both project_id and composition_id to direct the agent to a specific composition within the project
Create new project: Provide a project_name instead of project_id to 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/{job_id} 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/{job_id}.

post/jobs/agent

Request body

project_idstring uuid

The ID of an existing project to edit. Mutually exclusive with project_name.

project_namestring

Name for creating a new project. Mutually exclusive with project_id.

composition_idstring

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)

modelstring

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.

promptstring required

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"

team_access'edit' | 'comment' | 'view' | 'none'

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.

callback_urlstring uri

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.

Example request

{
  "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
  "project_name": "My New Project",
  "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5",
  "prompt": "add studio sound to every clip",
  "callback_url": "https://example.com/webhooks/descript/job_callback"
}

Response

Agent edit job created successfully

job_idstring uuid required

Unique identifier for the Agent edit job

drive_idstring uuid required

Drive ID where the project is located

project_idstring uuid required

The project ID (existing or newly created)

project_urlstring uri required

URL to access the project in Descript web app

conversation_idstring uuid required

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.

resolved_modelstring required

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

Example response

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