v3

latestOpenAPI 3.0.0Proprietary2026-08-041323140.2 KB

API Endpoints

Import media and sequences

Import media files into a new or existing project and create compositions.

This endpoint can:

Create a new project if project_id is not provided
Import media files from URLs
Create multitrack sequences
Create compositions (timelines) from existing or new media in the project
Trigger transcription and other background processing tasks

Media URL requirements

URLs must be accessible by Descript servers
URLs must support HTTP Range requests
Recommended to sign URLs for 12-48 hours to reduce chance of failure
Supported file types

Direct file upload

Instead of providing a URL, you can upload files directly by specifying content_type and file_size for a media item. The response will include a signed upload_url for each direct upload item. PUT the file bytes to that URL, and the import job will process it automatically. See the Direct file upload guide for a full walkthrough.

Async Operations

Imports 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 finishes (successfully or not).

The payload will match the format returned by GET /jobs/{job_id}.

post/jobs/import/project_media

Request body

project_idstring uuid

Existing project ID to import media into. If not provided, a new project will be created. When importing into an existing project, media filenames must not conflict with existing files.

project_namestring

Name for the new project. Only used when project_id is not provided.

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

Access level for drive members. Only applicable when creating a new project (when project_id is not provided). Defaults to none if not specified.

edit: Users can edit the project
comment: Users can view and comment but not edit
view: Users can view but not comment or edit
none: No shared access (private to owner)

folder_namestring

Folder path to place the new project in (e.g. "Clients/Acme/Videos"). Supports nested paths using "/" as separator. Only applicable when creating a new project (when project_id is not provided). Existing folders along the path are reused; missing segments are created automatically.

workspace_namestring

Existing workspace to create the new project in, matched by name (case-insensitive). Only applicable when creating a new project (when project_id is not provided).

Reserved names: Personal (your private space) and General (the shared drive workspace). Any other value is looked up as a custom workspace name; unknown names return 404.

When omitted, team_access is passed through unchanged. When set to Personal, team_access must be none or omitted. When set to General or a custom workspace name, team_access must be edit, comment, or view; omitting it defaults to view, and none is rejected.

For custom workspaces, the caller must be a member of that workspace.

add_mediaobject

Map of media reference IDs (display names with optional folder paths) to media import items. Keys are the display names that will appear in the project (e.g., "Misc/intro.mp4" or "demo.mp4"). Values define how to import each media item (URL import or multitrack sequence).

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": "Marketing Video",
  "team_access": "edit",
  "folder_name": "Clients/Acme",
  "workspace_name": "Marketing",
  "add_media": {
    "Misc/intro.mp4": {
      "url": "https://example.com/intro.mp4"
    },
    "demo.mp4": {
      "url": "https://example.com/demo.mp4"
    },
    "Multicam_Track": {
      "tracks": [
        {
          "media": "Recordings/camera1.mp4",
          "offset": 0
        },
        {
          "media": "Recordings/camera2.mp4",
          "offset": 50
        }
      ]
    }
  },
  "add_compositions": [
    {
      "name": "Rough Cut",
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "clips": [
        {
          "media": "Misc/intro.mp4"
        }
      ]
    }
  ],
  "callback_url": "https://example.com/webhooks/descript/job_callback"
}

Response

Import job created successfully

job_idstring uuid required

Unique identifier for the job

drive_idstring uuid required

Drive ID where the project is located

project_idstring uuid required

Project ID (newly created or existing)

project_urlstring uri required

URL to access the project in Descript web app

upload_urlsobject

Signed upload URLs for each direct upload media item. Only present when the request includes direct upload references. PUT the file contents to the upload_url with Content-Type: application/octet-stream. The import job will automatically detect the upload and process the file.

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

All 13 operations