curl --request POST \
  --url https://descriptapi.com/v1/jobs/import/project_media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_name": "Marketing Video",
  "add_media": {
    "Misc/intro.mp4": {
      "url": "https://example.com/intro.mp4"
    },
    "demo.mp4": {
      "url": "https://example.com/demo.mp4"
    },
    "Misc/outro.mp4": {
      "url": "https://example.com/outro.mp4"
    }
  },
  "add_compositions": [
    {
      "name": "Rough Cut",
      "clips": [
        {
          "media": "Misc/intro.mp4"
        },
        {
          "media": "demo.mp4"
        },
        {
          "media": "Misc/outro.mp4"
        }
      ]
    }
  ]
}
'

{
  "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",
  "drive_name": "My Team Workspace",
  "upload_urls": {}
}

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: the API accepts more containers and codecs than the app, including MXF, MPEG-TS, and AVI

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

POST

jobs

import

project_media

curl --request POST \
  --url https://descriptapi.com/v1/jobs/import/project_media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_name": "Marketing Video",
  "add_media": {
    "Misc/intro.mp4": {
      "url": "https://example.com/intro.mp4"
    },
    "demo.mp4": {
      "url": "https://example.com/demo.mp4"
    },
    "Misc/outro.mp4": {
      "url": "https://example.com/outro.mp4"
    }
  },
  "add_compositions": [
    {
      "name": "Rough Cut",
      "clips": [
        {
          "media": "Misc/intro.mp4"
        },
        {
          "media": "demo.mp4"
        },
        {
          "media": "Misc/outro.mp4"
        }
      ]
    }
  ]
}
'

{
  "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",
  "drive_name": "My Team Workspace",
  "upload_urls": {}
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Media import and project creation request

Request to import media into a project and optionally create compositions. This operation will:

Create a new project if project_id is not provided (using the drive associated with the personal token)
Import media files from URLs or create multitrack sequences
Optionally create one or more compositions
Trigger transcription and other background processing

project_id

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

Example:

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

project_name

string

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

Example:

"Marketing Video"

team_access

enum<string>

default: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)

Available options:

edit,

comment,

view,

none

Example:

"edit"

folder_name

string

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.

Example:

"Clients/Acme"

workspace_name

string

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.

Example:

"Marketing"

add_media

object

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

Show child attributes

Example:

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

object[]

Optional list of compositions to create in the project

Show child attributes

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

Import job created successfully

Response returned when creating an import job

job_id

string<uuid>

required

Unique identifier for the 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

Project ID (newly created or existing)

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"

drive_name

string | null

Human-readable name of the connected drive (workspace)

Example:

"My Team Workspace"

upload_urls

object

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.

Show child attributes

Get started

Guides

MCP

Partner integrations

API endpoints

Import media and sequences

Media URL requirements

Direct file upload

Async Operations

Dynamic webhook

Authorizations

Body

Response