---
title: "LyricWinter REST API reference (beta)"
description: "Base URL, authentication, response envelope, and every endpoint group in the LyricWinter REST API beta, generated from the public OpenAPI 3.1 contract."
canonical_url: https://lyricwinter.com/docs/api
markdown_url: https://lyricwinter.com/docs/api.md
last_updated: 2026-09-30
status: beta
---
# LyricWinter REST API reference (beta)

> Base URL, authentication, response envelope, and every endpoint group in the LyricWinter REST API beta, generated from the public OpenAPI 3.1 contract.

The LyricWinter REST API is a JSON-over-HTTPS API for LyricWinter Studio. It is in beta. This reference is generated from the public OpenAPI 3.1 contract, the same file that API tools and code generators can download.

| Property | Value |
| --- | --- |
| Base URL | `https://lyricwinter.com/api/v1` |
| Authentication | `Authorization: Bearer lw_...` ([details](/docs/authentication)) |
| Request format | `Content-Type: application/json`, UTF-8 |
| Response format | `{ "data": ..., "request_id": "req_..." }` ([details](/docs/errors-and-retries)) |
| IDs | Lowercase UUIDs |
| Timestamps | ISO 8601 in UTC |
| OpenAPI contract | [`/api/v1/openapi.json`](https://lyricwinter.com/api/v1/openapi.json) |

## Use the OpenAPI contract

Load `https://lyricwinter.com/api/v1/openapi.json` into Postman, Insomnia, Bruno, or an OpenAPI code generator to get a typed client for every endpoint below. Coding agents should read the contract instead of guessing field names.

```bash
curl https://lyricwinter.com/api/v1/openapi.json -o lyricwinter-openapi.json
```

## Conventions

- **Scopes.** Each endpoint lists the API key scope it requires. Studio endpoints need `studio:read` or `studio:write`.
- **Versions.** Writes that change shared state take the version you last read, such as `document_version`, and fail with `409` instead of overwriting newer work. See [Studio concepts](/docs/studio-concepts#versions-and-optimistic-concurrency).
- **Safe retries.** Studio writes take a `client_mutation_id`; exports take an `Idempotency-Key` header. See [Errors and retries](/docs/errors-and-retries#idempotency).
- **Asynchronous work.** Workflows and exports return `202 Accepted`. Poll the returned resource until it reaches a terminal status.
- **Media.** Audio is served from short-lived signed URLs returned by the API. Fetch fresh URLs instead of storing them.

## Endpoint groups

### [Voice preparation](https://lyricwinter.com/docs/api/voice-preparation)

Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. ElevenLabs v4 requires a paid plan. This read-only check does not create voices or reserve provider allowance.

- `GET /voices/preparation-status`: [Check voice preparation readiness](https://lyricwinter.com/docs/api/voice-preparation#get-voice-preparation-status)

### [Account and API keys](https://lyricwinter.com/docs/api/account)

Check API health, read the account and available generation balance behind an API key, and create, list, or revoke scoped API keys.

- `GET /health`: [Check API health](https://lyricwinter.com/docs/api/account#get-health)
- `GET /me`: [Get the current account](https://lyricwinter.com/docs/api/account#get-current-account-profile)
- `GET /me/generation-preferences`: [Read generation preferences](https://lyricwinter.com/docs/api/account#get-generation-preferences)
- `PATCH /me/generation-preferences`: [Save generation preferences](https://lyricwinter.com/docs/api/account#update-generation-preferences)
- `GET /me/balance`: [Get the current account balance](https://lyricwinter.com/docs/api/account#get-current-account-balance)
- `GET /studio/account-capabilities`: [Get available Studio funding and actions](https://lyricwinter.com/docs/api/account#get-studio-account-capabilities)
- `GET /api-keys`: [List API keys](https://lyricwinter.com/docs/api/account#list-api-keys)
- `POST /api-keys`: [Create an API key](https://lyricwinter.com/docs/api/account#create-api-key)
- `DELETE /api-keys/{apiKeyId}`: [Revoke an API key](https://lyricwinter.com/docs/api/account#revoke-api-key)

### [Projects](https://lyricwinter.com/docs/api/projects)

A Studio project groups ordered sections (chapters) that share one cast of speakers. Standalone stories appear as unassigned stories until you turn them into a named project.

- `GET /studio/projects`: [List projects and standalone stories](https://lyricwinter.com/docs/api/projects#list-studio-projects)
- `PATCH /studio/projects/{projectId}`: [Turn a standalone story into a project](https://lyricwinter.com/docs/api/projects#promote-studio-project)
- `GET /studio/projects/{projectId}/deletion-info`: [Preview project deletion](https://lyricwinter.com/docs/api/projects#get-studio-project-deletion-info)
- `DELETE /studio/projects/{projectId}`: [Delete a project](https://lyricwinter.com/docs/api/projects#delete-studio-project)

### [Sections](https://lyricwinter.com/docs/api/sections)

A section is one chapter or scene of story text inside a project. Create a standalone story with one section, add sections to a project, reorder them, or delete them.

- `POST /studio/sections`: [Create a standalone story](https://lyricwinter.com/docs/api/sections#create-standalone-studio-section)
- `GET /studio/projects/{projectId}/sections`: [List project sections](https://lyricwinter.com/docs/api/sections#list-studio-project-sections)
- `POST /studio/projects/{projectId}/sections`: [Add a section to a project](https://lyricwinter.com/docs/api/sections#create-studio-section)
- `PATCH /studio/projects/{projectId}/sections/{sectionId}`: [Move a section](https://lyricwinter.com/docs/api/sections#move-studio-section)
- `GET /studio/projects/{projectId}/sections/{sectionId}/deletion-info`: [Preview section deletion](https://lyricwinter.com/docs/api/sections#get-studio-section-deletion-info)
- `DELETE /studio/projects/{projectId}/sections/{sectionId}`: [Delete a section](https://lyricwinter.com/docs/api/sections#delete-studio-section)

### [Documents and speakers](https://lyricwinter.com/docs/api/documents)

Every section has a versioned document of narration and dialogue blocks attributed to speakers. Read the document before editing it or generating audio, and list the project's speakers and casting.

- `GET /studio/sections/{sectionId}/document`: [Get a section document](https://lyricwinter.com/docs/api/documents#get-studio-document)
- `PATCH /studio/sections/{sectionId}/document`: [Edit a section document](https://lyricwinter.com/docs/api/documents#save-studio-document)
- `POST /studio/sections/{sectionId}/script`: [Import a speaker-labeled script](https://lyricwinter.com/docs/api/documents#import-studio-script)
- `GET /studio/projects/{projectId}/speakers`: [List project speakers](https://lyricwinter.com/docs/api/documents#get-studio-project-speaker-usage)
- `PATCH /studio/projects/{projectId}/speakers/{speakerId}/casting`: [Assign a speaker's voice and model](https://lyricwinter.com/docs/api/documents#update-studio-project-speaker-casting)

### [Workflows](https://lyricwinter.com/docs/api/workflows)

Workflows are durable, asynchronous jobs. A prepare workflow structures text into narration and dialogue; a Create Audio workflow casts voices and generates multi-voice audio. Poll a workflow until it reaches a terminal status. A provider-account limit is reported as a failed step with `STUDIO_WORKFLOW_PROVIDER_QUOTA_EXCEEDED`; generation-batch targets use `PROVIDER_QUOTA_EXCEEDED`. Completed audio remains available. For a shared provider limit, contact us to restore provider access before explicitly resuming. When the failure message says the account's monthly ElevenLabs voice preparation allowance is used up, choose a cached ElevenLabs voice or another engine, or wait for the allowance to reset on the first of the month (UTC). Do not automatically resubmit quota failures.

- `POST /studio/projects/{projectId}/workflows`: [Start a workflow](https://lyricwinter.com/docs/api/workflows#create-studio-workflow)
- `GET /studio/projects/{projectId}/workflows`: [Get the latest project workflow](https://lyricwinter.com/docs/api/workflows#get-latest-studio-workflow)
- `GET /studio/workflows/{workflowRunId}`: [Get a workflow](https://lyricwinter.com/docs/api/workflows#get-studio-workflow)
- `GET /studio/workflows/{workflowRunId}/progress`: [Get workflow audio progress](https://lyricwinter.com/docs/api/workflows#get-studio-workflow-progress)
- `POST /studio/workflows/{workflowRunId}/cancel`: [Cancel a workflow](https://lyricwinter.com/docs/api/workflows#cancel-studio-workflow)
- `POST /studio/workflows/{workflowRunId}/resume`: [Resume a failed workflow](https://lyricwinter.com/docs/api/workflows#resume-studio-workflow)

### [Media and playback](https://lyricwinter.com/docs/api/media)

Check whether generation can start separately from whether audio already exists. Read per-block media freshness and generation activity, compile a playback manifest for current audio, and mint short-lived URLs. Generation availability checks plan access, voice/compiler eligibility, and confirmed ElevenLabs preparation exhaustion; it is not a promise of audio, synthesis quota, or funding. Free accounts cannot generate with ElevenLabs v4, but existing audio remains playable.

- `GET /studio/sections/{sectionId}/media`: [Get section media](https://lyricwinter.com/docs/api/media#get-studio-section-media)
- `GET /studio/sections/{sectionId}/generation-availability`: [Check generation eligibility](https://lyricwinter.com/docs/api/media#get-studio-section-generation-availability)
- `GET /studio/sections/{sectionId}/playback-manifest`: [Get a playback manifest](https://lyricwinter.com/docs/api/media#get-studio-playback-manifest)
- `POST /studio/media-assets/{assetId}/access-url`: [Create a media access URL](https://lyricwinter.com/docs/api/media#create-studio-media-access-url)

### [Exports](https://lyricwinter.com/docs/api/exports)

Render one section or a project's selected sections into downloadable MP3, WAV, M4B, synchronized EPUB, or SRT files. Poll a project job for every child export, then download files individually and fetch each child's immutable manifest for matching timings. No ZIP is produced. Freshness compares document, cast, and mastering versions only, not newer audio takes or artifact readiness.

- `GET /studio/projects/{projectId}/mastering-profile`: [Get the mastering profile](https://lyricwinter.com/docs/api/exports#get-studio-mastering-profile)
- `POST /studio/projects/{projectId}/exports`: [Export a project's sections](https://lyricwinter.com/docs/api/exports#create-studio-project-export)
- `GET /studio/projects/{projectId}/exports`: [List project export jobs](https://lyricwinter.com/docs/api/exports#list-studio-project-exports)
- `GET /studio/projects/{projectId}/exports/{exportId}`: [Poll a project export job](https://lyricwinter.com/docs/api/exports#get-studio-project-export)
- `GET /studio/projects/{projectId}/export-freshness`: [Compare section export versions](https://lyricwinter.com/docs/api/exports#get-studio-project-export-freshness)
- `GET /studio/exports`: [List exports](https://lyricwinter.com/docs/api/exports#list-studio-exports)
- `POST /studio/exports`: [Create an export](https://lyricwinter.com/docs/api/exports#create-studio-export)
- `GET /studio/exports/{exportId}`: [Get an export](https://lyricwinter.com/docs/api/exports#get-studio-export)
- `GET /studio/exports/{exportId}/manifest`: [Get an export's immutable timeline](https://lyricwinter.com/docs/api/exports#get-studio-export-manifest)
- `POST /studio/exports/{exportId}/cancel`: [Cancel an export](https://lyricwinter.com/docs/api/exports#cancel-studio-export)

### [Sharing](https://lyricwinter.com/docs/api/sharing)

Publish a section or a whole project at a stable public link, read its sharing state, or revoke the link.

- `GET /studio/sections/{sectionId}/share`: [Get section sharing](https://lyricwinter.com/docs/api/sharing#get-studio-public-share)
- `POST /studio/sections/{sectionId}/share`: [Share a section](https://lyricwinter.com/docs/api/sharing#ensure-studio-public-share)
- `DELETE /studio/sections/{sectionId}/share`: [Stop sharing a section](https://lyricwinter.com/docs/api/sharing#revoke-studio-public-share)
- `GET /studio/projects/{projectId}/share`: [Get project sharing](https://lyricwinter.com/docs/api/sharing#get-studio-project-share-state)
- `POST /studio/projects/{projectId}/share`: [Share a project](https://lyricwinter.com/docs/api/sharing#publish-studio-project)
- `DELETE /studio/projects/{projectId}/share`: [Stop sharing a project](https://lyricwinter.com/docs/api/sharing#revoke-studio-project-share)

### [Sound library](https://lyricwinter.com/docs/api/sounds)

Upload sound effects and ambience up to 256 MiB and 65 minutes into the Studio sound library, manage their metadata, publish them to the public catalog, and link them to projects so Create Audio can place them automatically. Processing verifies duration; the sanitized WAV can be up to 720 MiB. Pinned project sounds can play as long ambience overlays; provider-generated SFX remain limited to five minutes.

- `GET /studio/sounds`: [List sounds](https://lyricwinter.com/docs/api/sounds#list-studio-sounds)
- `POST /studio/sounds`: [Start a sound upload](https://lyricwinter.com/docs/api/sounds#create-studio-sound-upload)
- `POST /studio/sounds/{soundId}/uploads/{uploadId}/complete`: [Complete a sound upload](https://lyricwinter.com/docs/api/sounds#complete-studio-sound-upload)
- `GET /studio/sounds/{soundId}/uploads/latest`: [Get sound upload status](https://lyricwinter.com/docs/api/sounds#get-studio-sound-upload-status)
- `GET /studio/sounds/{soundId}`: [Get a sound](https://lyricwinter.com/docs/api/sounds#get-studio-sound)
- `PATCH /studio/sounds/{soundId}`: [Update a sound](https://lyricwinter.com/docs/api/sounds#update-studio-sound)
- `DELETE /studio/sounds/{soundId}`: [Delete a sound](https://lyricwinter.com/docs/api/sounds#delete-studio-sound)
- `POST /studio/sounds/{soundId}/preview-url`: [Create a sound preview URL](https://lyricwinter.com/docs/api/sounds#create-studio-sound-preview-url)
- `GET /studio/projects/{projectId}/sounds`: [List project sounds](https://lyricwinter.com/docs/api/sounds#list-studio-project-sounds)
- `POST /studio/projects/{projectId}/sounds`: [Link a sound to a project](https://lyricwinter.com/docs/api/sounds#add-studio-project-sound)
- `DELETE /studio/projects/{projectId}/sounds/{soundId}`: [Unlink a sound from a project](https://lyricwinter.com/docs/api/sounds#remove-studio-project-sound)
- `GET /sounds`: [List public sounds](https://lyricwinter.com/docs/api/sounds#list-public-sounds)
- `GET /sounds/{soundId}`: [Get a public sound](https://lyricwinter.com/docs/api/sounds#get-public-sound)

### [Feedback](https://lyricwinter.com/docs/api/feedback)

Send product feedback with screenshots and other images so our team can see what you mean.

- `POST /feedback`: [Send feedback and images](https://lyricwinter.com/docs/api/feedback#submit-feedback)