Documentation Powered by ReDoc

Descript API (1)

Download OpenAPI specification:Download

Authentication

Descript API uses a personal token to authenticate your request. You can get your personal token by contacting us. The personal token should be used as a bearer token in the authorization header.

Authentication example

curl -H "authorization: Bearer ${YOUR_PERSONAL_TOKEN}" -d @datafile.json https://descriptapi.com/v1/edit_in_descript/schema

Edit in Descript

Edit in Descript API enables partners to give their users the ability to transfer audio or video content to Descript for editing.

Edit in Descript buttons work by generating one-time use, public Import URLs to the Descript import UI that users can be automatically sent to. On that page, they can make a few simple selections before kicking off a Partner cloud storage to Descript cloud storage transfer. This will redirect them to a Descript Project ready for editing.

Partners can initiate the request by securely sending an information schema backend-to-backend to the Descript API using a token, in exchange for the Import URL to redirect the user. Partners do not need to store this schema, as Descript will do so and use it to start fetching the files when the user confirms the action

  1. When a user clicks Edit in Descript, partner’s backend service makes POST request to: https://descriptapi.com/v1/edit_in_descript/schema with an authorization bearer token header and JSON schema body
  2. Descript responds with either an Import URL or an error
  3. Partner redirects the user’s browser to the URL returned in step 2 or display an error message and link to help documentation

Partner User Experience

Some guidelines for partners as you consider this integration:

  • We recommend placing the Edit in Descript option next to your download options
    • If you offer multiple download options, such as combined vs. split audio/video files, we recommend placing this integration clearly in context with each option, or only the supported option, to help users understand what will be exported.
    • Each time you request an import link, a new one is generated. Import links expire after 3 hours. After using an import link, the only way to find an imported Project again is in Descript.
    • If an import link has expired or the contents of the schema has changed, please request a new import link with the updated schema. This will create a new Descript Project when used.
  • We will provide Descript-branded assets to fit your proposed placement of the Edit in Descript CTA and ask that you don’t edit the assets beyond what we provide. We are happy to work with you on getting you the right assets for your placement.
  • Partners should provide error-handling for the POST request, at minimum displaying a generic error message and linking to a help article (we can provide a link for this if you prefer).
  • Progress will be conveyed to the user in the Descript side of the user experience.

Descript User Experience

When users are directed to a Descript Import URL, they’ll be asked to either create an account or login in order to proceed.

Next, they will be presented with a few options about how they’d like to import the data, such as where the new Descript Project should be created.

They’ll then be redirected to the Project, where they can monitor the progress of the import and start editing.

Create Import URL

Create an Import URL by sending a Project schema to Descript API from your service's backend.

Import Schema

Our import schemas are specified as a minimal JSON list of files which is detailed in full at the bottom of this section. At it’s smallest, the request body looks like:

{
  "partner_drive_id": "162c61d1-6ced-4b25-a622-7dba922983ee",
  "project_schema": {
    "schema_version": "1.0.0",
    "files": [{"uri": "https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955"}]
  }
}

File Access

The file paths provided in the schema need to either be public or pre-signed URIs with enough time before expiration for failures and retries, we suggest URIs that won’t expire for 48 hours. We ask that the files have already been saved when the import link is generated to minimize cases where we’re waiting for eventually consistent storage of files that will never be written. We will, however, wait for eventual consistency of the storage layer and retry fetching files before eventually timing out.

Files must be hosted on preapproved hosts as our import process has an allow list which it checks URIs against. Files will be requested with User-Agent: Descriptbot/1.0 (version may change) for tracking purposes.

Import links are no longer valid after a user imports their data once. Viewing an already used import link will not allow for importing again and will not provide access to a previously created Descript Project. Partners are able to generate a new import link at any time, regardless of if a previous import link has been used.

The API does not currently provide partners with a link to the Descript Project, though users will be redirected to it from Descript’s web interface the first time they import files, and can always find the Project in Descript.

Import links expire after 3 hours and attempting to use an import link after the pre-signed links in the schema file have expired will result in an error, so we recommend generating the import link after the user has clicked the Edit in Descript button.

Supported media specification

We recommend sending the highest quality, uncompressed versions of files available to you. If you have multiple tracks, we recommend prioritizing sending us the full multi-track sequence over a combined file.

  • Audio: WAV, FLAC, AAC, MP3
  • Video: h264, HEVC (container: MOV, MP4)
Request Body schema: application/json

Edit in Descript schema POST body.

partner_drive_id
required
uuid

The drive id associated with the auth token.

required
object

The Project schema

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Export from Descript

Users of Descript currently have three options to export their edited content. They can export files in various formats, share a Descript link, or use our one-click cloud export to publish directly to a partner.

Roundtrip Metadata

If Project data previously came from a partner via an Edit in Descript schema then any Descript Export pages will include <meta/> tags which contains the partner_drive_id and source_id provided when originally importing into Descript. This allows partners to deduplicate data returning back to partner systems after editing in Descript. Both partner and source properties are included on all public Descript Export pages.

<meta property="descript:partner" content="9121bf3a-60fe-4a31-ad59-ed32df610cc3" />
<meta property="descript:source" content="409148bd-81aa-4af6-a9c3-29b761506f3a" />