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
• 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/ 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/.

POST /jobs/agent

cURL

create_new_project

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

201

Example

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

Authorizations

Authorization · string · header · required

Personal API token created in Descript Settings → API Tokens. See the Authentication section for details.

Body

application/json

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.

prompt · string · 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"

Example:

"add studio sound to every clip"

project_id · string<uuid>

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

Example:

"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"

project_name · string

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

Example:

"My New Project"

composition_id · string<uuid>

[Work in progress] This property is accepted but not yet functional. It will be ignored.

Optional composition ID within the project to edit.

Example:

"39677a40-1c43-4c36-8449-46cfbc4de2b5"

model · string

AI model to use for editing. Defaults to the default model.

team_access · enum<string>

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.

Available options: edit, comment, view, none

callback_url · string<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:

"https://example.com/webhooks/descript/job_callback"

Response

201

application/json

Agent edit job created successfully

job_id · string<uuid> · required

Unique identifier for the Agent edit job

Example:

"6dc3f30a-58c2-4174-96a6-dc18cf3c7776"

drive_id · string<uuid> · required

Drive ID where the project is located

Example:

"c9c5c47e-158a-49f7-846b-4f6ee2a229a2"

project_id · string<uuid> · required

The project ID (existing or newly created)

Example:

"9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"

project_url · string<uri> · required

URL to access the project in Descript web app

Example:

"https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb"