Descript API Endpoints API

openapi: 3.0.0
info:
  description: Descript API documentation.
  version: '1.2'
  title: Descript API Endpoints API
  x-logo:
    url: assets/descript-logo.svg
    altText: Descript
  license:
    name: Proprietary
    url: https://www.descript.com/terms
servers:
- url: https://descriptapi.com/v1
tags:
- name: API Endpoints
  description: Import media, edit projects with AI, and query jobs and projects.
paths:
  /jobs/import/project_media:
    post:
      tags:
      - API Endpoints
      summary: Import media and sequences
      security:
      - bearerAuth: []
      description: '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](https://help.descript.com/hc/en-us/articles/10164098416909-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](#tag/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}](#operation/getJob) 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}](#operation/getJob).

        '
      operationId: importProjectMedia
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: '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

                '
              properties:
                project_id:
                  type: string
                  format: uuid
                  description: '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:
                  type: string
                  description: Name for the new project. Only used when project_id is not provided.
                  example: Marketing Video
                team_access:
                  type: string
                  description: '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)

                    '
                  enum:
                  - edit
                  - comment
                  - view
                  - none
                  default: none
                  example: edit
                folder_name:
                  type: string
                  description: '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
                add_media:
                  type: object
                  description: '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).

                    '
                  additionalProperties:
                    type: object
                    description: 'Defines how to import a single media item. Can be either a URL import or a multitrack sequence.

                      '
                    oneOf:
                    - type: object
                      title: URL Import
                      description: Import media from a URL
                      required:
                      - url
                      properties:
                        url:
                          type: string
                          format: uri
                          description: 'URL to import media from. Must be accessible by Descript servers and support Range requests.

                            Recommended to sign URLs for 12-48 hours to reduce chance of failure.

                            '
                          example: https://example.com/intro.mp4
                        language:
                          type: string
                          description: 'ISO 639-1 language code for transcription (e.g., "en", "es", "fr").

                            If not specified, language is auto-detected from the audio.

                            '
                          example: en
                      additionalProperties: false
                    - type: object
                      title: Direct Upload
                      description: 'Upload a file directly to Descript. The API returns a signed upload URL

                        in the response. PUT your file to that URL, then the import job will

                        process it automatically.

                        '
                      required:
                      - content_type
                      - file_size
                      properties:
                        content_type:
                          type: string
                          description: MIME type of the file (e.g., "video/mp4", "audio/wav")
                          example: video/mp4
                        file_size:
                          type: integer
                          description: File size in bytes
                          example: 52428800
                        language:
                          type: string
                          description: 'ISO 639-1 language code for transcription (e.g., "en", "es", "fr").

                            If not specified, language is auto-detected from the audio.

                            '
                          example: en
                      additionalProperties: false
                    - type: object
                      title: Multitrack Sequence
                      description: Create a multitrack sequence from multiple media files
                      required:
                      - tracks
                      properties:
                        tracks:
                          type: array
                          description: Array of tracks to combine into a multitrack sequence
                          minItems: 1
                          items:
                            type: object
                            required:
                            - media
                            properties:
                              media:
                                type: string
                                description: Media reference ID (display name) of the media to include in this track
                                example: Recordings/camera1.mp4
                              offset:
                                type: number
                                format: float
                                description: Optional time offset in seconds for syncing this track
                                example: 50
                                default: 0
                            additionalProperties: false
                      additionalProperties: false
                  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:
                  type: array
                  description: Optional list of compositions to create in the project
                  items:
                    type: object
                    description: Defines a composition to create in the project
                    properties:
                      name:
                        type: string
                        description: Name of the composition. If not provided, uses default naming.
                        example: Rough Cut
                      width:
                        type: integer
                        description: Width of the composition in pixels
                        example: 1920
                        default: 1920
                      height:
                        type: integer
                        description: Height of the composition in pixels
                        example: 1080
                        default: 1080
                      fps:
                        type: number
                        description: '**[Work in progress]** This property is not yet supported and will be ignored if provided.


                          Frame rate for the composition in frames per second.

                          Common values: 24, 25, 29.97, 30, 60.

                          '
                        default: 30
                        example: 30
                      clips:
                        type: array
                        description: Ordered list of clips to include in the composition
                        items:
                          type: object
                          required:
                          - media
                          properties:
                            media:
                              type: string
                              description: Media reference ID (display name) of the media to add as a clip
                              example: Misc/intro.mp4
                          additionalProperties: false
                    required:
                    - clips
                    additionalProperties: false
                callback_url:
                  type: string
                  format: uri
                  description: '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.

                    '
                  example: https://example.com/webhooks/descript/job_callback
              additionalProperties: false
            examples:
              create_with_composition:
                summary: Create project with initial composition
                description: Most common use case for seeding a project with a simple composition
                value:
                  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
              import_only:
                summary: Import media without composition
                description: Import files for later composition creation
                value:
                  project_name: Video Project
                  add_media:
                    Assets/intro.mp4:
                      url: https://example.com/intro.mp4
                    Assets/logo.png:
                      url: https://example.com/logo.png
              direct_upload:
                summary: Direct file upload
                description: Upload a local file directly instead of providing a URL
                value:
                  project_name: Upload Project
                  add_media:
                    recording.mp4:
                      content_type: video/mp4
                      file_size: 52428800
                  add_compositions:
                  - name: Main
                    clips:
                    - media: recording.mp4
              multitrack_sequence:
                summary: Create multitrack sequence
                description: Combine multiple tracks with time offsets
                value:
                  project_name: Interview Edit
                  add_media:
                    Misc/intro.mp4:
                      url: https://example.com/intro.mp4
                    Recordings/camera1.mp4:
                      url: https://example.com/camera1.mp4
                    Recordings/camera2.mp4:
                      url: https://example.com/camera2.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
                    clips:
                    - media: Misc/intro.mp4
                    - media: Multicam_Track
        description: Media import and project creation request
        required: true
      responses:
        '201':
          description: Import job created successfully
          content:
            application/json:
              schema:
                type: object
                description: Response returned when creating an import job
                properties:
                  job_id:
                    type: string
                    format: uuid
                    description: Unique identifier for the job
                    example: 6dc3f30a-58c2-4174-96a6-dc18cf3c7776
                  drive_id:
                    type: string
                    format: uuid
                    description: Drive ID where the project is located
                    example: c9c5c47e-158a-49f7-846b-4f6ee2a229a2
                  project_id:
                    type: string
                    format: uuid
                    description: Project ID (newly created or existing)
                    example: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  project_url:
                    type: string
                    format: uri
                    description: URL to access the project in Descript web app
                    example: https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  upload_urls:
                    type: object
                    description: '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.

                      '
                    additionalProperties:
                      type: object
                      properties:
                        upload_url:
                          type: string
                          format: uri
                          description: Signed URL to PUT the file to. Expires after 3 hours.
                        asset_id:
                          type: string
                          format: uuid
                          description: GAT asset ID for the uploaded file
                        artifact_id:
                          type: string
                          format: uuid
                          description: GAT artifact ID for the uploaded file
                      required:
                      - upload_url
                      - asset_id
                      - artifact_id
                required:
                - job_id
                - drive_id
                - project_id
                - project_url
        '400':
          description: 'Invalid input:

            - Malformed request body

            - Invalid media URLs

            - URLs not accessible or don''t support Range requests

            - Media filename conflicts with existing files (when importing to existing project)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
              examples:
                invalid_url:
                  summary: Invalid media URL
                  value:
                    error: invalid_input
                    message: Invalid media URL format
                url_not_accessible:
                  summary: URL not accessible
                  value:
                    error: invalid_input
                    message: Media URL is not accessible or does not support Range requests
                filename_conflict:
                  summary: Filename conflict
                  value:
                    error: invalid_input
                    message: Media filename conflicts with existing files in the project
        '401':
          description: Unauthorized - missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                unauthorized:
                  summary: Missing authentication token
                  value:
                    error: unauthorized
                    message: Missing or invalid authentication token
        '402':
          description: Payment Required - insufficient media minutes to start the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
              examples:
                insufficient_minutes:
                  summary: Insufficient media minutes
                  value:
                    error: payment_required
                    message: Insufficient media minutes to start the job (300 minutes required, 50 available)
        '403':
          description: Forbidden - user does not have access to this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
              examples:
                forbidden:
                  summary: No access to drive or project
                  value:
                    error: forbidden
                    message: User does not have access to this drive or project
        '404':
          description: 'Not found:

            - Drive doesn''t exist

            - Project doesn''t exist (when project_id is provided)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
              examples:
                project_not_found:
                  summary: Project not found
                  value:
                    error: not_found
                    message: Project not found
                drive_not_found:
                  summary: Drive not found
                  value:
                    error: not_found
                    message: Drive not found
        '429':
          $ref: '#/components/responses/Error429Response'
  /jobs/agent:
    post:
      tags:
      - API Endpoints
      summary: Agent edit
      security:
      - bearerAuth: []
      description: '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).

        '
      operationId: agentEditJob
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: '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`.

                '
              properties:
                project_id:
                  type: string
                  format: uuid
                  description: 'The ID of an existing project to edit. Mutually exclusive with `project_name`.

                    '
                  example: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                project_name:
                  type: string
                  description: 'Name for creating a new project. Mutually exclusive with `project_id`.

                    '
                  example: My New Project
                composition_id:
                  type: string
                  description: '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`)

                    '
                  example: 39677a40-1c43-4c36-8449-46cfbc4de2b5
                model:
                  type: string
                  description: 'AI model to use for editing. Defaults to the default model.

                    '
                prompt:
                  type: string
                  description: '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
                team_access:
                  type: string
                  enum:
                  - edit
                  - comment
                  - view
                  - none
                  description: '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:
                  type: string
                  format: uri
                  description: '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.

                    '
                  example: https://example.com/webhooks/descript/job_callback
              required:
              - prompt
              additionalProperties: false
            examples:
              create_new_project:
                summary: Create a new project
                value:
                  project_name: Cooking Tips Video
                  prompt: create a 30-second video about cooking tips with background music
              add_studio_sound:
                summary: Add Studio Sound effect
                value:
                  project_id: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  model: haiku-4.5
                  prompt: add studio sound to every clip
              remove_filler_words:
                summary: Remove filler words
                value:
                  project_id: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  prompt: remove all filler words
              create_highlight:
                summary: Create highlight reel
                value:
                  project_id: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  composition_id: 39677a40-1c43-4c36-8449-46cfbc4de2b5
                  prompt: create a 30-second highlight reel with the best moments
              with_callback:
                summary: Agent job with webhook callback
                value:
                  project_id: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  prompt: add studio sound to every clip
                  callback_url: https://example.com/webhooks/descript/job_callback
        description: AI agent request
        required: true
      responses:
        '201':
          description: Agent edit job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
                    format: uuid
                    description: Unique identifier for the Agent edit job
                    example: 6dc3f30a-58c2-4174-96a6-dc18cf3c7776
                  drive_id:
                    type: string
                    format: uuid
                    description: Drive ID where the project is located
                    example: c9c5c47e-158a-49f7-846b-4f6ee2a229a2
                  project_id:
                    type: string
                    format: uuid
                    description: The project ID (existing or newly created)
                    example: 9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                  project_url:
                    type: string
                    format: uri
                    description: URL to access the project in Descript web app
                    example: https://web.descript.com/9f36ee32-5a2c-47e7-b1a3-94991d3e3ddb
                required:
                - job_id
                - drive_id
                - project_id
                - project_url
        '400':
          description: 'Invalid input:

            - Malformed request body

            - Invalid project_id or composition_id

            - Empty or invalid prompt

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
              examples:
                empty_prompt:
                  summary: Empty prompt
                  value:
                    error: invalid_input
                    message: Prompt cannot be empty
                invalid_project:
                  summary: Invalid project ID
                  value:
                    error: invalid_input
                    message: Invalid project_id format
        '401':
          description: Unauthorized - missing or invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                unauthorized:
                  summary: Missing authentication token
                  value:
                    error: unauthorized
                    message: Missing or invalid authentication token
        '402':
          description: Payment Required - insufficient AI credits to start the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error402'
              examples:
                insufficient_credits:
                  summary: Insufficient AI credits
                  value:
                    error: payment_required
                    message: Insufficient AI credits to start the job (100 credits required, 25 available)
        '404':
          description: 'Not found:

            - Project doesn''t exist

            - Composition doesn''t exist (when composition_id is provided)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
              examples:
                project_not_found:
                  summary: Project not found
                  value:
                    error: not_found
                    message: Project not found
                composition_not_found:
                  summary: Composition not found
                  value:
                    error: not_found
                    message: Composition not found
        '429':
          $ref: '#/components/responses/Error429Response'
  /jobs/publish:
    post:
      tags:
      - API Endpoints
      summary: Publish project media
      security:
      - bearerAuth: []
      description: "Publish a project composition to create a shareable link and download the exported file.\n\nPublishes a specific composition from a project, rendering the output as video or audio\nat the specified resolution. When the job completes successfully the result contains both:\n\n- `share_url`: a public URL that can be used to view the published content on Descript's share site.\n- `download_url`: a time-limited signed URL to download the exported media file directly,\n  along with `download_url_expires_at` indicating when the link expires.\n\n### Republishing\n\nPublishing the same composition a second time automatically reuses the previous share URL,\noverwriting its content — so bookmarks and links handed out for the first publish keep working.\nRepublish matching is keyed on `(project_id, composition_id, media_type)`, so a Video publish\nand an Audio publish of the same composition produce two separate share URLs.\n\n### Async Operations\n\nPublish jobs run in the background and return a `job_id`. Monitor progress via the [GET /jobs/{job_id}](#operation/getJob) endpoint,\nwhich returns the `share_url`, `download_url`, and `download_url_expires_at` fields once the job finishes.\n\n### Dynamic webhook\n\nIf `callback_url` is provided, Descript will POST the job status to that URL when the job completes or fails.\nThe payload will match the format returned by [GET /jobs/{job_id}](#operation/getJob).\n"
      operationId: publishJob
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: 'Request to publish a project composition.

                '
            

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/descript/refs/heads/main/openapi/descript-api-endpoints-api-openapi.yml