--- title: "Agent edit" method: POST path: "/jobs/agent" tags: ["API Endpoints"] --- # Agent edit `POST /jobs/agent` 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}](#operation/getJob) 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}](#operation/getJob). ## Request body - object — 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`. - `project_id` string, uuid — The ID of an existing project to edit. Mutually exclusive with `project_name`. - `project_name` string — Name for creating a new project. Mutually exclusive with `project_id`. - `composition_id` string — 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`) - `model` string — 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](#operation/listAgentModels) for the current set of supported models and aliases. Defaults to `auto` when omitted, which selects a recommended model for your account. - `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" - `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_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}](#operation/getJob)) to this URL. ## Response `201` Agent edit job created successfully - object - `job_id` string, uuid, required — Unique identifier for the Agent edit job - `drive_id` string, uuid, required — Drive ID where the project is located - `drive_name` string, nullable — Human-readable name of the connected drive (workspace) - `project_id` string, uuid, required — The project ID (existing or newly created) - `project_url` string, uri, required — URL to access the project in Descript web app - `conversation_id` string, 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_model` string, 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}](#operation/getJob). ## Other responses - `400` — Invalid input: - Malformed request body - Invalid project_id or composition_id format - Empty or invalid prompt - `401` — Unauthorized - missing or invalid authentication token - `402` — Payment Required - insufficient AI credits to start the job - `403` — Forbidden - the drive admin has disabled agent usage for this drive - `404` — Not found: - Project doesn't exist - Composition doesn't exist in the specified project (when composition_id is provided) - `429` — Too many requests - rate limit exceeded. Use the `Retry-After` header to determine when to retry. ## Changes > 4 revisions in range; 1 could not be searched. - **2026-07-26** `9c6aee76d48f` — 1 warning, 1 info - removed the request property `conversation_id` - added the required property `conversation_id` to the response with the `201` status [Change history](https://skmtc.dev/descriptapi/apis/descript-api/changes/jobs/agent/post.md) --- [API](https://skmtc.dev/descriptapi/apis/descript-api.md) · [All operations](https://skmtc.dev/descriptapi/apis/descript-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/descriptapi/descript-api/revisions/04c0005aef70/schema)