Descript Edit in Descript API

openapi: 3.0.0
info:
  description: Descript API documentation.
  version: '1.2'
  title: Descript API Endpoints Edit in Descript 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: Edit in Descript
  description: "> **Note:** The Edit in Descript integration requires contacting Descript for access. [Reach out to us](https://descript.com/api) to get started.\n\nEdit in Descript API enables partners to give their users the ability to transfer audio or video content to Descript for editing.\n\nEdit in Descript buttons work by generating one-time use, public Import URLs to the Descript import UI that users\ncan be automatically sent to. On that page, they can make a few simple selections before kicking off a Partner cloud\nstorage to Descript cloud storage transfer. This will redirect them to a Descript Project ready for editing.\n\nPartners can initiate the request by securely sending an information schema backend-to-backend to the Descript API\nusing a token, in exchange for the Import URL to redirect the user. Partners do not need to store this schema, as\nDescript will do so and use it to start fetching the files when the user confirms the action\n\n1. When a user clicks `Edit in Descript`, partner's backend service makes POST request to:\n    `https://descriptapi.com/v1/edit_in_descript/schema` with an authorization bearer token header and JSON schema body\n2. Descript responds with either an Import URL or an error\n3. Partner redirects the user's browser to the URL returned in step 2 or display an error message and link to help documentation\n\n### Partner User Experience\nSome guidelines for partners as you consider this integration:\n* We recommend placing the `Edit in Descript` option next to your download options\n  * If you offer multiple download options, such as combined vs. split audio/video files, we recommend placing\nthis integration clearly in context with each option, or only the supported option, to help users understand\nwhat will be exported.\n  * Each time you request an import link, a new one is generated. Import links expire after 3 hours. After using an\nimport link, the only way to find an imported Project again is in Descript.\n  * If an import link has expired or the contents of the schema has changed, please request a new import link with\nthe updated schema. This will create a new Descript Project when used.\n* We will provide Descript-branded assets to fit your proposed placement of the `Edit in Descript` CTA and ask\nthat you don't edit the assets beyond what we provide. We are happy to work with you on getting you the right\nassets for your placement.\n* Partners should provide error-handling for the POST request, at minimum displaying a generic error message and\nlinking to a help article (we can provide a link for this if you prefer).\n* Progress will be conveyed to the user in the Descript side of the user experience.\n\n### Descript User Experience\nWhen users are directed to a Descript Import URL, they'll be asked to either create an account or login in order\nto proceed.\n\nNext, they will be presented with a few options about how they'd like to import the data, such as where the new\nDescript Project should be created.\n\nThey'll then be redirected to the Project, where they can monitor the progress of the import and start editing.\n"
paths:
  /edit_in_descript/schema:
    post:
      tags:
      - Edit in Descript
      summary: Create Import URL
      description: "Create an Import URL by sending a Project schema to Descript API from your service's backend.\n\n### Import Schema\nOur import schemas are specified as a minimal JSON list of files which is detailed in full at the bottom of this\nsection. At it's smallest, the request body looks like:\n\n```\n{\n  \"partner_drive_id\": \"162c61d1-6ced-4b25-a622-7dba922983ee\",\n  \"project_schema\": {\n    \"schema_version\": \"1.0.0\",\n    \"files\": [{\"uri\": \"https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955\"}]\n  }\n}\n```\n\n### File Access\nThe file paths provided in the schema need to either be public or pre-signed URIs with enough time before\nexpiration for failures and retries, we suggest URIs that won't expire for 48 hours. We ask that the files have\nalready been saved when the import link is generated to minimize cases where we're waiting for eventually\nconsistent storage of files that will never be written. We will, however, wait for eventual consistency of the\nstorage layer and retry fetching files before eventually timing out.\n\nFiles must be hosted on preapproved hosts as our import process has an allow list which it checks URIs against.\nFiles will be requested with `User-Agent: Descriptbot/1.0` (version may change) for tracking purposes.\n\n### Import link expiration\nImport links are no longer valid after a user imports their data once. Viewing an already used import link will\nnot allow for importing again and will not provide access to a previously created Descript Project. Partners are\nable to generate a new import link at any time, regardless of if a previous import link has been used.\n\nThe API does not currently provide partners with a link to the Descript Project, though users will be redirected\nto it from Descript's web interface the first time they import files, and can always find the Project in Descript.\n\nImport links expire after 3 hours and attempting to use an import link after the pre-signed links in the schema\nfile have expired will result in an error, so we recommend generating the import link after the user has clicked\nthe Edit in Descript button.\n\n### Supported media specification\nWe recommend sending the highest quality, uncompressed versions of files available to you. If you have multiple\ntracks, we recommend prioritizing sending us the full multi-track sequence over a combined file.\n\n* Audio: WAV, FLAC, AAC, MP3\n* Video: h264, HEVC (container: MOV, MP4)\n"
      operationId: postEditInDescriptSchema
      security:
      - bearerAuth: []
      requestBody:
        description: Edit in Descript schema POST body.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditInDescriptSchemaPostBody'
      responses:
        '201':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditInDescriptSchemaPostResponse'
        '400':
          description: Invalid input.
        '403':
          description: Associated drive does not have Edit in Descript permissions.
        '429':
          $ref: '#/components/responses/Error429Response'
components:
  responses:
    Error429Response:
      description: 'Too many requests - rate limit exceeded.

        Use the `Retry-After` header to determine when to retry.

        '
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request
          schema:
            type: integer
          example: 30
        X-RateLimit-Remaining:
          description: Number of requests remaining in the current rate limit window
          schema:
            type: integer
          example: 0
        X-RateLimit-Consumed:
          description: Number of requests consumed in the current rate limit window
          schema:
            type: integer
          example: 100
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error429'
          examples:
            rate_limit:
              summary: Rate limit exceeded
              value:
                error: rate_limit_exceeded
                message: Too many requests. Please try again later.
  schemas:
    Error429:
      description: 'Rate limit exceeded response. When this error is returned, the response includes headers

        to help you implement proper retry logic:

        - `Retry-After`: Number of seconds to wait before retrying

        - `X-RateLimit-Remaining`: Requests remaining in current window

        - `X-RateLimit-Consumed`: Requests consumed in current window

        '
      type: object
      properties:
        error:
          type: string
          description: Error code indicating rate limit was exceeded
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message
          example: Too many requests
      required:
      - error
      - message
    EditInDescriptSchemaPostResponse:
      type: object
      properties:
        url:
          type: string
          format: url
          example: https://web.descript.com/import?nonce=6e3625ca-f885-460d-b2e3-e3faac79c788
          description: A url for partners to redirect their user to in order to start the import process—expires after 3 hours.
    EditInDescriptSchemaPostBody:
      type: object
      properties:
        partner_drive_id:
          type: string
          format: uuid
          description: The drive id associated with the auth token.
          example: aa3b2d8d-e5ca-41c2-8801-683328293fb9
        project_schema:
          type: object
          description: The Project schema
          properties:
            schema_version:
              type: string
              format: string
              description: Schema version id.
              example: 1.0.0
            source_id:
              type: string
              format: string
              description: External source id to be included in Descript export pages, see Export from Descript section for details. This ID is not currently used to deduplicate data coming into Descript, a new Project is created for each import.
              example: 06b3f5bb-68a2-468a-a5d9-df155c1e3588
            files:
              type: array
              description: List of remote files to import into Descript.
              items:
                type: object
                properties:
                  name:
                    type: string
                    format: string
                    description: A name for the file.
                  uri:
                    type: string
                    format: url
                    description: A public/pre-signed uri to the audio or video asset, see supported media specifications section.
                  start_offset:
                    type: object
                    description: The amount of time into the Project's timeline this audio or video file should start at.
                    properties:
                      seconds:
                        type: number
                        description: Float number of seconds into the timeline.
                example:
                  name: Jane's studio recording
                  uri: https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955
                  start_offset:
                    seconds: 10
                required:
                - uri
          required:
          - schema_version
          - files
      required:
      - partner_drive_id
      - project_schema
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal API token created in Descript Settings → API Tokens. See the Authentication section for details.
x-tagGroups:
- name: Early Access Public API
  tags:
  - Getting started
  - Using the CLI
  - API Endpoints
  - Direct file upload
  - Authentication
  - Rate Limiting
- name: Partner APIs
  tags:
  - Edit in Descript
  - Export from Descript