Sign in

v3

latestOpenAPI 3.0.0Proprietary2026-08-041323140.2 KB
API Endpoints

Publish project media

Publish a project composition to create a shareable link and download the exported file.

Publishes a specific composition from a project, rendering the output as video or audio at the specified resolution. When the job completes successfully the result contains both:

  • share_url: a public URL that can be used to view the published content on Descript's share site.
  • download_url: a time-limited signed URL to download the exported media file directly, along with download_url_expires_at indicating when the link expires.

Republishing

Publishing the same composition a second time automatically reuses the previous share URL, overwriting its content — so bookmarks and links handed out for the first publish keep working. Republish matching is keyed on (project_id, composition_id, media_type), so a Video publish and an Audio publish of the same composition produce two separate share URLs.

Async Operations

Publish jobs run in the background and return a job_id. Monitor progress via the GET /jobs/{job_id} endpoint, which returns the share_url, download_url, and download_url_expires_at fields once the job finishes.

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/publish

Request body

project_idstring uuid required

The ID of the project to publish.

composition_idstring

Composition to publish. If omitted, the first composition in the project is used.

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)
media_type'Video' | 'Audio'

Media type of the published output. Defaults to Video when omitted.

If the target composition has no video content:

  • omitting media_type publishes it as Audio (the completed job result reports media_type: Audio),
  • explicitly requesting Video is rejected with a 422.
resolution'480p' | '720p' | '1080p' | '1440p' | '4K'

Resolution for the published output. Only applicable when media_type is Video.

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.

access_level'public' | 'unlisted' | 'drive' | 'private'

Desired access level for the published share page. If omitted, the drive's configured default is used. Returns 403 if the requested level is not permitted by the drive's publish settings (e.g. requesting public when search engine indexing is disabled).

Example request

{
  "project_id": "9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb",
  "composition_id": "39677a40-1c43-4c36-8449-46cfbc4de2b5",
  "callback_url": "https://example.com/webhooks/descript/job_callback"
}

Response

Publish job created successfully

job_idstring uuid required

Unique identifier for the publish job

drive_idstring uuid required

Drive ID where the project is located

project_idstring uuid required

The project ID being published

project_urlstring uri required

URL to access the project in Descript web app

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