---
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

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

Check API health, read the account 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 /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)

### [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.

- `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)

Read the generated audio state for a section, compile a playback manifest for the current document version, and mint short-lived URLs for individual media assets.

- `GET /studio/sections/{sectionId}/media`: [Get section media](https://lyricwinter.com/docs/api/media#get-studio-section-media)
- `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 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.

- `GET /studio/projects/{projectId}/mastering-profile`: [Get the mastering profile](https://lyricwinter.com/docs/api/exports#get-studio-mastering-profile)
- `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)
- `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 your own sound effects and ambience into the Studio sound library, manage their metadata, and link them to projects so Create Audio can place them automatically.

- `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)