---
title: "Exports API"
description: "Render a section into a downloadable MP3, WAV, M4B, synchronized EPUB, or SRT file. Exports are pinned to the current document, cast, and mastering versions and run asynchronously; poll an export until its file is ready."
canonical_url: https://lyricwinter.com/docs/api/exports
markdown_url: https://lyricwinter.com/docs/api/exports.md
last_updated: 2026-09-30
status: beta
---
# LyricWinter API reference: Exports

> Render a section into a downloadable MP3, WAV, M4B, synchronized EPUB, or SRT file. Exports are pinned to the current document, cast, and mastering versions and run asynchronously; poll an export until its file is ready.

The LyricWinter API is in beta. Base URL: `https://lyricwinter.com/api/v1`. Authenticate every request with `Authorization: Bearer lw_...`. Successful responses are wrapped as `{ "data": ..., "request_id": "req_..." }`. Machine-readable contract: https://lyricwinter.com/api/v1/openapi.json.

## Endpoints

- [Get the mastering profile](https://lyricwinter.com/docs/api/exports#get-studio-mastering-profile): `GET /studio/projects/{projectId}/mastering-profile`
- [List exports](https://lyricwinter.com/docs/api/exports#list-studio-exports): `GET /studio/exports`
- [Create an export](https://lyricwinter.com/docs/api/exports#create-studio-export): `POST /studio/exports`
- [Get an export](https://lyricwinter.com/docs/api/exports#get-studio-export): `GET /studio/exports/{exportId}`
- [Cancel an export](https://lyricwinter.com/docs/api/exports#cancel-studio-export): `POST /studio/exports/{exportId}/cancel`

### Get the mastering profile

`GET /studio/projects/{projectId}/mastering-profile`

Scope: `studio:read` · Operation ID: `getStudioMasteringProfile`

Returns the project's loudness and mastering settings and its `mastering_version`, which exports require.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string, uuid | Yes |  |

#### Response 200

Current mastering authority and profile.

Fields inside `data`:

- `schema_version` (1; required)
- `project_id` (string, uuid; required)
- `project_kind` (string, one of `standalone`, `named`; required)
- `mastering_version` (integer, ≥ 1; required)
- `scope` (string, one of `document`, `project`; required)
- `profile` (object; required)
  - `schema_version` (1; required)
  - `enabled` (boolean; required)
  - `target_lufs` (number, -30–-10; required)
  - `strength` (number, 0–1; required)
  - `max_boost_db` (number, 0–24; required)
  - `max_reduction_db` (number, 0–24; required)
  - `silence_threshold_lufs` (number, -120–-20; required)
  - `peak_ceiling_db` (number, -12–-0.1; required)
  - `speaker_adjustments_db` (map of number; required)
  - `sfx_bus_gain_db` (number, -24–24, default 0; required)
- `sfx_adjustments` (object; optional)
  - `nonzero_count` (integer, ≥ 0; required)
  - `nonzero_section_count` (integer, ≥ 0; required)
  - `fingerprint` (string, pattern ^[a-f0-9]{64}$; required)

Errors: `400`, `401`, `403`, `404`, `409`, `500` return the standard error envelope.

#### Example request

```bash
curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/mastering-profile" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"
```

### List exports

`GET /studio/exports`

Scope: `studio:read` · Operation ID: `listStudioExports`

Lists the account's exports, newest first. Completed exports include a download URL that is valid for twelve hours; the file itself is kept for thirty days.

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `section_id` | string, uuid | No |  |
| `format` | string, one of `mp3`, `wav`, `m4b`, `epub`, `srt` | No |  |
| `status` | string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded` | No |  |
| `cursor` | integer, ≥ 0, default 0 | No |  |
| `limit` | integer, 1–100, default 25 | No |  |

#### Response 200

One export page.

Fields inside `data`:

- `schema_version` (1; required)
- `exports` (array of object; required)
  - `schema_version` (1; required)
  - `id` (string, uuid; required)
  - `project_id` (string, uuid; required)
  - `section_id` (string, uuid; required)
  - `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)
  - `status` (string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded`; required)
  - `phase` (string, one of `queued`, `compiling`, `claiming_artifact`, `downloading`, `mixing`, `encoding`, `packaging`, `uploading`, `complete`, `failed`, `cancelled`; required)
  - `percent` (integer, 0–100; required)
  - `cache_result` (string, one of `miss`, `reused`, `coalesced`; required)
  - `authority` (object; required)
    - `document_version` (integer, ≥ 1; required)
    - `speaker_registry_version` (integer, ≥ 1; required)
    - `mastering_version` (integer, ≥ 1; required)
    - `is_current` (boolean; required)
  - `created_at` (string, date-time; required)
  - `started_at` (string | null, date-time; required)
  - `completed_at` (string | null, date-time; required)
  - `error` (object | null; required)
    - `code` (string; required)
    - `message` (string; required)
  - `artifact` (object | null; required)
    - `asset_id` (string, uuid; required)
    - `filename` (string, 1–255 chars; required)
    - `content_type` (string, min 1 chars; required)
    - `size_bytes` (integer, ≥ 1; required)
    - `download_url` (string, uri; required)
    - `download_url_expires_at` (string, date-time; required)
    - `artifact_expires_at` (string, date-time; required)
- `next_cursor` (string | null, min 1 chars; required)

Errors: `400`, `401`, `403`, `404`, `409`, `500`, `503` return the standard error envelope.

#### Example request

```bash
curl "https://lyricwinter.com/api/v1/studio/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"
```

### Create an export

`POST /studio/exports`

Scope: `studio:write` · Retries: send an `Idempotency-Key` header · Operation ID: `createStudioExport`

Renders one section into `mp3`, `wav`, `m4b`, synchronized `epub`, or `srt`, pinned to the document, speaker registry, and mastering versions you send. Returns `202` for new work or `200` when an identical, unexpired file is reused. Requires an `Idempotency-Key` header.

#### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string, 1–255 chars | Yes | Opaque caller key. The same key and request replay safely; the same key with a different request conflicts. |

#### Request body (application/json, required)

- `schema_version` (1; required)
- `section_id` (string, uuid; required)
- `document_version` (integer, ≥ 1; required)
- `speaker_registry_version` (integer, ≥ 1; required)
- `mastering_version` (integer, ≥ 1; required)
- `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)

#### Response 200

An unexpired identical artifact was reused.

Fields inside `data`:

- `schema_version` (1; required)
- `id` (string, uuid; required)
- `project_id` (string, uuid; required)
- `section_id` (string, uuid; required)
- `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)
- `status` (string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded`; required)
- `phase` (string, one of `queued`, `compiling`, `claiming_artifact`, `downloading`, `mixing`, `encoding`, `packaging`, `uploading`, `complete`, `failed`, `cancelled`; required)
- `percent` (integer, 0–100; required)
- `cache_result` (string, one of `miss`, `reused`, `coalesced`; required)
- `authority` (object; required)
  - `document_version` (integer, ≥ 1; required)
  - `speaker_registry_version` (integer, ≥ 1; required)
  - `mastering_version` (integer, ≥ 1; required)
  - `is_current` (boolean; required)
- `created_at` (string, date-time; required)
- `started_at` (string | null, date-time; required)
- `completed_at` (string | null, date-time; required)
- `error` (object | null; required)
  - `code` (string; required)
  - `message` (string; required)
- `artifact` (object | null; required)
  - `asset_id` (string, uuid; required)
  - `filename` (string, 1–255 chars; required)
  - `content_type` (string, min 1 chars; required)
  - `size_bytes` (integer, ≥ 1; required)
  - `download_url` (string, uri; required)
  - `download_url_expires_at` (string, date-time; required)
  - `artifact_expires_at` (string, date-time; required)

#### Response 202

New durable export work accepted.

Fields inside `data`:

- `schema_version` (1; required)
- `id` (string, uuid; required)
- `project_id` (string, uuid; required)
- `section_id` (string, uuid; required)
- `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)
- `status` (string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded`; required)
- `phase` (string, one of `queued`, `compiling`, `claiming_artifact`, `downloading`, `mixing`, `encoding`, `packaging`, `uploading`, `complete`, `failed`, `cancelled`; required)
- `percent` (integer, 0–100; required)
- `cache_result` (string, one of `miss`, `reused`, `coalesced`; required)
- `authority` (object; required)
  - `document_version` (integer, ≥ 1; required)
  - `speaker_registry_version` (integer, ≥ 1; required)
  - `mastering_version` (integer, ≥ 1; required)
  - `is_current` (boolean; required)
- `created_at` (string, date-time; required)
- `started_at` (string | null, date-time; required)
- `completed_at` (string | null, date-time; required)
- `error` (object | null; required)
  - `code` (string; required)
  - `message` (string; required)
- `artifact` (object | null; required)
  - `asset_id` (string, uuid; required)
  - `filename` (string, 1–255 chars; required)
  - `content_type` (string, min 1 chars; required)
  - `size_bytes` (integer, ≥ 1; required)
  - `download_url` (string, uri; required)
  - `download_url_expires_at` (string, date-time; required)
  - `artifact_expires_at` (string, date-time; required)

Errors: `400`, `401`, `403`, `404`, `409`, `500`, `502`, `503` return the standard error envelope.

#### Example request

```bash
curl -X POST "https://lyricwinter.com/api/v1/studio/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "section_id": "11111111-1111-4111-8111-111111111111",
  "document_version": 7,
  "speaker_registry_version": 3,
  "mastering_version": 4,
  "format": "mp3"
}'
```

### Get an export

`GET /studio/exports/{exportId}`

Scope: `studio:read` · Operation ID: `getStudioExport`

Returns an export's status, phase, percent complete, and, when `status` is `completed`, its downloadable `artifact`. Poll about once per second while it runs.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `exportId` | string, uuid | Yes |  |

#### Response 200

Current durable export state.

Fields inside `data`:

- `schema_version` (1; required)
- `id` (string, uuid; required)
- `project_id` (string, uuid; required)
- `section_id` (string, uuid; required)
- `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)
- `status` (string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded`; required)
- `phase` (string, one of `queued`, `compiling`, `claiming_artifact`, `downloading`, `mixing`, `encoding`, `packaging`, `uploading`, `complete`, `failed`, `cancelled`; required)
- `percent` (integer, 0–100; required)
- `cache_result` (string, one of `miss`, `reused`, `coalesced`; required)
- `authority` (object; required)
  - `document_version` (integer, ≥ 1; required)
  - `speaker_registry_version` (integer, ≥ 1; required)
  - `mastering_version` (integer, ≥ 1; required)
  - `is_current` (boolean; required)
- `created_at` (string, date-time; required)
- `started_at` (string | null, date-time; required)
- `completed_at` (string | null, date-time; required)
- `error` (object | null; required)
  - `code` (string; required)
  - `message` (string; required)
- `artifact` (object | null; required)
  - `asset_id` (string, uuid; required)
  - `filename` (string, 1–255 chars; required)
  - `content_type` (string, min 1 chars; required)
  - `size_bytes` (integer, ≥ 1; required)
  - `download_url` (string, uri; required)
  - `download_url_expires_at` (string, date-time; required)
  - `artifact_expires_at` (string, date-time; required)

Errors: `400`, `401`, `403`, `404`, `409`, `500`, `503` return the standard error envelope.

#### Example request

```bash
curl "https://lyricwinter.com/api/v1/studio/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"
```

### Cancel an export

`POST /studio/exports/{exportId}/cancel`

Scope: `studio:write` · Operation ID: `cancelStudioExport`

Cancels a queued export immediately or asks a running one to stop. Files already produced for other requests are not deleted.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `exportId` | string, uuid | Yes |  |

#### Response 200

Current cancelled or canceling export state.

Fields inside `data`:

- `schema_version` (1; required)
- `id` (string, uuid; required)
- `project_id` (string, uuid; required)
- `section_id` (string, uuid; required)
- `format` (string, one of `mp3`, `wav`, `m4b`, `epub`, `srt`; required)
- `status` (string, one of `queued`, `running`, `retry_wait`, `canceling`, `completed`, `failed`, `cancelled`, `superseded`; required)
- `phase` (string, one of `queued`, `compiling`, `claiming_artifact`, `downloading`, `mixing`, `encoding`, `packaging`, `uploading`, `complete`, `failed`, `cancelled`; required)
- `percent` (integer, 0–100; required)
- `cache_result` (string, one of `miss`, `reused`, `coalesced`; required)
- `authority` (object; required)
  - `document_version` (integer, ≥ 1; required)
  - `speaker_registry_version` (integer, ≥ 1; required)
  - `mastering_version` (integer, ≥ 1; required)
  - `is_current` (boolean; required)
- `created_at` (string, date-time; required)
- `started_at` (string | null, date-time; required)
- `completed_at` (string | null, date-time; required)
- `error` (object | null; required)
  - `code` (string; required)
  - `message` (string; required)
- `artifact` (object | null; required)
  - `asset_id` (string, uuid; required)
  - `filename` (string, 1–255 chars; required)
  - `content_type` (string, min 1 chars; required)
  - `size_bytes` (integer, ≥ 1; required)
  - `download_url` (string, uri; required)
  - `download_url_expires_at` (string, date-time; required)
  - `artifact_expires_at` (string, date-time; required)

Errors: `400`, `401`, `403`, `404`, `409`, `500` return the standard error envelope.

#### Example request

```bash
curl -X POST "https://lyricwinter.com/api/v1/studio/exports/$EXPORT_ID/cancel" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"
```