API reference

Sections API

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.

BetaUpdated November 11, 2026

Markdown Ask ChatGPT Ask Claude

Base URL: https://lyricwinter.com/api/v1
Authentication: Authorization: Bearer lw_…
Contract: openapi.json

Create a standalone story

POST/studio/sections

Scope studio:writeRetry with the same client_mutation_id

Creates a standalone Studio story with one section containing the exact text you send. Returns 201 with the new project ID, section, and document, or 200 with idempotent_replay: true when the same client_mutation_id was already applied.

Request body application/json

schema_version1required
actor_session_idstringrequireduuid
client_mutation_idstringrequireduuid
Idempotency key; a replay with the same canonical request returns the committed result.
titlestringrequiredmax 500 chars
At most 500 UTF-16 code units. Must not contain null characters or malformed Unicode.
raw_textstringrequired
Exact section text stored as one unparsed block. At most 8 MiB of UTF-8 (the whole request body is also limited to 8 MiB). Must not contain null characters or malformed Unicode.

Response 200

Idempotent replay of the existing standalone story. Fields below are inside data.

project_idstringrequireduuid
sectionobjectrequired
11 child attributes
- last_opened_atstring | nulldate-time
- has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
- idstringrequireduuid
- project_idstringrequireduuid
- titlestringrequired
- document_versionintegerrequired≥ 1
- source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
- source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
- activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
documentobjectrequired
The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
section_order_versionintegerrequired≥ 1
speaker_registry_versionintegerrequired≥ 1
idempotent_replaybooleanrequired
True when client_mutation_id matched an already committed creation (HTTP 200); false for a new section (HTTP 201).

Response 201

Standalone Studio story created. Fields below are inside data.

project_idstringrequireduuid
sectionobjectrequired
11 child attributes
- last_opened_atstring | nulldate-time
- has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
- idstringrequireduuid
- project_idstringrequireduuid
- titlestringrequired
- document_versionintegerrequired≥ 1
- source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
- source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
- activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
documentobjectrequired
The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
section_order_versionintegerrequired≥ 1
speaker_registry_versionintegerrequired≥ 1
idempotent_replaybooleanrequired
True when client_mutation_id matched an already committed creation (HTTP 200); false for a new section (HTTP 201).

Errors 400, 401, 409, 500 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/sections" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "title": "Chapter One",
  "raw_text": "A bell rang. \"Who is there?\" Mira asked."
}'

const response = await fetch(`https://lyricwinter.com/api/v1/studio/sections`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "title": "Chapter One",
    "raw_text": "A bell rang. \"Who is there?\" Mira asked."
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/sections",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "title": "Chapter One",
      "raw_text": "A bell rang. \"Who is there?\" Mira asked."
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "section": {
      "last_opened_at": "2026-09-30T17:00:00.000Z",
      "has_audio": true,
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "project_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "title": "Chapter One",
      "document_version": 1,
      "source_text_length": 1,
      "source_word_count": 1,
      "activity_status": "blank",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z"
    },
    "document": {
      "blocks": [],
      "different_speaker_gap_ms": 1,
      "document_version": 1,
      "sfx_enabled": true,
      "same_speaker_gap_ms": 1,
      "schema_version": "studio-ast-2",
      "section_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "speaker_registry_version": 1,
      "speakers": [],
      "title": "Chapter One"
    },
    "section_order_version": 1,
    "speaker_registry_version": 1,
    "idempotent_replay": true
  },
  "request_id": "req_01J9Z3K8QF4"
}

List project sections

GET/studio/projects/{projectId}/sections

Scope studio:read

Returns a project's sections in order with the project's section_order_version and speaker_registry_version. Section summaries include source_word_count when available: the word count of saved source text, including text excluded from narration. A project that has not been opened in Studio yet returns initialized: false.

Path parameters

projectIdstringrequireduuid

Response 200

Studio project state and sections. Fields below are inside data.

project_idstringrequireduuid
initializedbooleanrequired
False when the owned project has no Studio state yet; the nullable fields are then null and sections is empty.
casting_defaults_modestring | nullrequired
One ofapply_exactsuggestignore
default_automation_profilestring | nullrequired
One ofquickbalanceddirected
section_order_versioninteger | nullrequired≥ 1
speaker_registry_versioninteger | nullrequired≥ 1
sectionsarray of objectrequired
Active sections in project order.
11 item attributes
- last_opened_atstring | nulldate-time
- has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
- idstringrequireduuid
- project_idstringrequireduuid
- titlestringrequired
- document_versionintegerrequired≥ 1
- source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
- source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
- activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
- created_atstringrequireddate-time
- updated_atstringrequireddate-time

Errors 400, 401, 403, 500 use the standard error envelope.

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

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sections`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sections",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "initialized": true,
    "casting_defaults_mode": "apply_exact",
    "default_automation_profile": "quick",
    "section_order_version": 1,
    "speaker_registry_version": 1,
    "sections": [
      {
        "last_opened_at": "2026-09-30T17:00:00.000Z",
        "has_audio": true,
        "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "project_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "title": "Chapter One",
        "document_version": 1,
        "source_text_length": 1,
        "source_word_count": 1,
        "activity_status": "blank",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Add a section to a project

POST/studio/projects/{projectId}/sections

Scope studio:writeRetry with the same client_mutation_id

Adds one section of unstructured text to a project. Standalone projects allow only one active section; adding another returns 400 STUDIO_COMMAND_REJECTED. Use a named project created through POST /projects for multiple sections. Send the section_order_version you last read as base_section_order_version; a stale version returns 409.

Path parameters

projectIdstringrequireduuid

Request body application/json

schema_version1required
actor_session_idstringrequireduuid
client_mutation_idstringrequireduuid
Idempotency key; a replay with the same canonical request returns the committed result.
base_section_order_versioninteger | nullrequired≥ 1
Section-order version the client last observed; null when the project has not initialized Studio.
titlestringrequiredmax 500 chars
At most 500 UTF-16 code units. Must not contain null characters or malformed Unicode.
raw_textstringrequired
Exact section text stored as one unparsed block. At most 8 MiB of UTF-8 (the whole request body is also limited to 8 MiB). Must not contain null characters or malformed Unicode.

Response 200

Idempotent replay of the existing section. Fields below are inside data.

project_idstringrequireduuid
sectionobjectrequired
11 child attributes
- last_opened_atstring | nulldate-time
- has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
- idstringrequireduuid
- project_idstringrequireduuid
- titlestringrequired
- document_versionintegerrequired≥ 1
- source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
- source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
- activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
documentobjectrequired
The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
section_order_versionintegerrequired≥ 1
speaker_registry_versionintegerrequired≥ 1
idempotent_replaybooleanrequired
True when client_mutation_id matched an already committed creation (HTTP 200); false for a new section (HTTP 201).

Response 201

Studio section created. Fields below are inside data.

project_idstringrequireduuid
sectionobjectrequired
11 child attributes
- last_opened_atstring | nulldate-time
- has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
- idstringrequireduuid
- project_idstringrequireduuid
- titlestringrequired
- document_versionintegerrequired≥ 1
- source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
- source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
- activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
documentobjectrequired
The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
section_order_versionintegerrequired≥ 1
speaker_registry_versionintegerrequired≥ 1
idempotent_replaybooleanrequired
True when client_mutation_id matched an already committed creation (HTTP 200); false for a new section (HTTP 201).

Errors 400, 401, 403, 409, 500 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sections" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "base_section_order_version": 1,
  "title": "Chapter One",
  "raw_text": "A bell rang. \"Who is there?\" Mira asked."
}'

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sections`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "base_section_order_version": 1,
    "title": "Chapter One",
    "raw_text": "A bell rang. \"Who is there?\" Mira asked."
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sections",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "base_section_order_version": 1,
      "title": "Chapter One",
      "raw_text": "A bell rang. \"Who is there?\" Mira asked."
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "section": {
      "last_opened_at": "2026-09-30T17:00:00.000Z",
      "has_audio": true,
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "project_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "title": "Chapter One",
      "document_version": 1,
      "source_text_length": 1,
      "source_word_count": 1,
      "activity_status": "blank",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z"
    },
    "document": {
      "blocks": [],
      "different_speaker_gap_ms": 1,
      "document_version": 1,
      "sfx_enabled": true,
      "same_speaker_gap_ms": 1,
      "schema_version": "studio-ast-2",
      "section_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "speaker_registry_version": 1,
      "speakers": [],
      "title": "Chapter One"
    },
    "section_order_version": 1,
    "speaker_registry_version": 1,
    "idempotent_replay": true
  },
  "request_id": "req_01J9Z3K8QF4"
}

Move a section

PATCH/studio/projects/{projectId}/sections/{sectionId}

Scope studio:writeRetry with the same client_mutation_id

Moves a section to a new position in the project. Send the current section_order_version; a stale version returns 409.

Path parameters

projectIdstringrequireduuid
sectionIdstringrequireduuid

Request body application/json

schema_version1required
actor_session_idstringrequireduuid
client_mutation_idstringrequireduuid
Idempotency key; a replay with the same canonical request returns the committed result.
base_section_order_versionintegerrequired≥ 1
to_indexintegerrequired0–4999
Zero-based target index in the active section order.

Response 200

Section move committed or replayed. Fields below are inside data.

operationstringrequired
move_section for PATCH and delete_section for DELETE.
One ofmove_sectiondelete_section
project_idstringrequireduuid
section_idstringrequireduuid
section_order_versionintegerrequired≥ 1
Section-order version committed by this mutation.
idempotent_replaybooleanrequired

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.

curl -X PATCH "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sections/$SECTION_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "base_section_order_version": 1,
  "to_index": 1
}'

const projectId = "<projectId>";
const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sections/${sectionId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "base_section_order_version": 1,
    "to_index": 1
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
section_id = "<sectionId>"
response = requests.request(
    "PATCH",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sections/{section_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "base_section_order_version": 1,
      "to_index": 1
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "operation": "move_section",
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_order_version": 1,
    "idempotent_replay": true
  },
  "request_id": "req_01J9Z3K8QF4"
}

Preview section deletion

GET/studio/projects/{projectId}/sections/{sectionId}/deletion-info

Scope studio:read

Returns counts of the script blocks, generated clips, and active share links that deleting the section would make inaccessible.

Path parameters

projectIdstringrequireduuid
sectionIdstringrequireduuid

Response 200

Section deletion preview. Fields below are inside data.

project_idstringrequireduuid
section_idstringrequireduuid
block_countintegerrequired≥ 0
generated_clip_countintegerrequired≥ 0
active_share_link_countintegerrequired≥ 0

Errors 400, 401, 403, 404, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sections/$SECTION_ID/deletion-info" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sections/${sectionId}/deletion-info`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
section_id = "<sectionId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sections/{section_id}/deletion-info",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "block_count": 1,
    "generated_clip_count": 1,
    "active_share_link_count": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

Delete a section

DELETE/studio/projects/{projectId}/sections/{sectionId}

Scope studio:writeRetry with the same client_mutation_id

Deletes a section after checking both the section order version and the document version. This cannot be undone through the API.

Path parameters

projectIdstringrequireduuid
sectionIdstringrequireduuid

Request body application/json

schema_version1required
actor_session_idstringrequireduuid
client_mutation_idstringrequireduuid
Idempotency key; a replay with the same canonical request returns the committed result.
base_section_order_versionintegerrequired≥ 1
base_document_versionintegerrequired≥ 1

Response 200

Section deletion committed or replayed. Fields below are inside data.

operationstringrequired
move_section for PATCH and delete_section for DELETE.
One ofmove_sectiondelete_section
project_idstringrequireduuid
section_idstringrequireduuid
section_order_versionintegerrequired≥ 1
Section-order version committed by this mutation.
idempotent_replaybooleanrequired

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.

curl -X DELETE "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sections/$SECTION_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "base_section_order_version": 1,
  "base_document_version": 1
}'

const projectId = "<projectId>";
const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sections/${sectionId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "base_section_order_version": 1,
    "base_document_version": 1
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
section_id = "<sectionId>"
response = requests.request(
    "DELETE",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sections/{section_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "base_section_order_version": 1,
      "base_document_version": 1
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "operation": "move_section",
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_order_version": 1,
    "idempotent_replay": true
  },
  "request_id": "req_01J9Z3K8QF4"
}

Read a story in one request

GET/studio/projects/{projectId}/story

Scope studio:read

Read all ordered sections with full documents and text, cast, per-block audio freshness, Studio play links, the five newest existing section exports, and the newest project export. Export artifacts include signed download links when available; inspect status, authority and expiry. This operation never generates audio, starts exports or creates shares. It aggregates authorized reads; it is not a cross-section transactional snapshot.

Path parameters

projectIdstringrequireduuid

Response 200

Read-only story state. Fields below are inside data.

project_idstringrequireduuid
initializedbooleanrequired
False when the owned project has no Studio state yet; the nullable fields are then null and sections is empty.
casting_defaults_modestring | nullrequired
One ofapply_exactsuggestignore
default_automation_profilestring | nullrequired
One ofquickbalanceddirected
section_order_versioninteger | nullrequired≥ 1
speaker_registry_versioninteger | nullrequired≥ 1
sectionsarray of objectrequired
6 item attributes
- summaryobjectrequired
  11 child attributes
  last_opened_atstring | nulldate-time
  has_audioboolean
  Present, and true, only with activity_status needs_audio: at least one line already has finished audio, so the section needs updating or finishing rather than creating.
  idstringrequireduuid
  project_idstringrequireduuid
  titlestringrequired
  document_versionintegerrequired≥ 1
  source_text_lengthintegerrequired≥ 0
  Length of the section's exact source-text projection in UTF-16 code units.
  source_word_countinteger≥ 0
  Word count of the saved source text using Unicode word segmentation. Includes text excluded from narration; sound prompts and notes are not source text. Omitted when unavailable.
  activity_statusstringrequired
  Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate).
  One ofblankworkingneeds_audioaudio_readyaudio_failed
  created_atstringrequireddate-time
  updated_atstringrequireddate-time
- documentobjectrequired
  The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
  Full shape: Get a section document
- textstringrequired
- mediaobjectrequired
  Current per-block media state for a Studio section.
  3 child attributes
  section_idstringrequireduuid
  playback_duration_msinteger | nullrequired≥ 0
  Duration of the newest saved render manifest for the section's current document and speaker-registry versions; null when none exists.
  blocksarray of objectrequired
  One entry per document block, in document order.
  18 item attributes
  block_idstringrequireduuid
  freshnessstringrequired
  absent: no active rendition. current: the active rendition matches the block's current generation intent. stale: it differs (see stale_reasons). unsupported: the block kind is not speech, narration, or sfx.
  One ofabsentcurrentstaleunsupported
  activitystringrequired
  generating: a pending rendition is queued, running, or waiting to retry, or imported audio is being copied. failed: the latest request or import failed. idle otherwise. Independent of freshness.
  One ofidlegeneratingfailed
  active_block_versioninteger | nullrequired≥ 1
  Block version the active rendition was requested for.
  requested_block_versioninteger | nullrequired≥ 1
  Block version of the pending rendition or import, if any.
  active_rendition_idstring | nullrequireduuid
  audio_version_countintegerrequired≥ 0
  Number of completed audio versions for the block.
  generation_batch_idstring | nullrequireduuid
  Generation batch of the pending rendition.
  playback_urlstring | nullrequireduri
  Short-lived signed URL for the active rendition's audio; null without an active asset.
  playback_url_expires_atstring | nullrequireddate-time
  content_typestring | nullrequired
  size_bytesinteger | nullrequired≥ 1
  analysis_integrated_lufsnumber | nullrequired-120–24
  analysis_sample_peak_dbfsnumber | nullrequired-200–24
  providerstring | nullrequired
  Provider that actually produced the active rendition (stored metadata for imports).
  modelstring | nullrequired
  Model that actually produced the active rendition (stored metadata for imports).
  errorstring | nullrequired
  Latest generation or import error message.
  stale_reasonsarray of string
  Present for speech, narration, and sfx blocks; non-empty only when freshness is stale.
  One ofblock_kindtextpronunciationexcluded_texttimingvoicegeneration_profiledelivery_controlssound_effect
- play_urlstringrequireduri
- latest_exportsarray of objectrequiredmax 5 items
  15 item attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
schema_version1required
play_urlstringrequireduri
castarray of object | nullrequired
Null when the story has no live section; read list_project_speakers for its retained characters.
5 item attributes
- generation_profileobject | nullrequired
  Saved profile read shape, including historical options. For new full-profile requests use StudioGenerationProfileRequest; its provider/model branches list accepted option keys. Generation eligibility and actual audio readiness are separate reads.
  5 child attributes
  providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
  modelstringrequired1–200 chars
  fallbackstringrequired
  One ofstrictbest_effort
  controlsstringrequired
  One ofstrictbest_effort
  optionsobjectrequired
- idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
- namestringrequired1–200 chars
- speaker_versionintegerrequired> 0
- voice_idstring | nullrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
latest_project_exportsarray of objectrequiredmax 1 items
9 item attributes
- schema_version1required
- idstringrequireduuid
  Parent project export job ID.
- project_idstringrequireduuid
- formatstringrequired
  One ofmp3wavm4bepubsrt
- statusstringrequired
  queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion.
  One ofqueuedrunningcompletedpartial_failedfailed
- percentintegerrequired0–100
  Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate.
- created_atstringrequireddate-time
- sectionsarray of objectrequired1–100 items
  Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.
  6 item attributes
  section_idstringrequireduuid
  titlestringrequiredmax 500 chars
  Section title captured for this parent.
  export_idstringrequireduuid
  Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible.
  authorityobjectrequired
  Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.
  3 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  exportobject | nullrequired
  Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
  errorobject | nullrequired
  Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.
  2 child attributes
  codestringrequiredmin 1 chars
  messagestringrequired
- archiveany | nullrequired
  No combined archive or ZIP is produced. Download child artifacts individually.

Errors 400, 401, 403, 500 use the standard error envelope.

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

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/story`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/story",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "initialized": true,
    "casting_defaults_mode": "apply_exact",
    "default_automation_profile": "quick",
    "section_order_version": 1,
    "speaker_registry_version": 1,
    "sections": [
      {
        "summary": {
          "last_opened_at": "2026-09-30T17:00:00.000Z",
          "has_audio": true,
          "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "project_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "title": "Chapter One",
          "document_version": 1,
          "source_text_length": 1,
          "source_word_count": 1,
          "activity_status": "blank",
          "created_at": "2026-09-30T17:00:00.000Z",
          "updated_at": "2026-09-30T17:00:00.000Z"
        },
        "document": {
          "blocks": [],
          "different_speaker_gap_ms": 1,
          "document_version": 1,
          "sfx_enabled": true,
          "same_speaker_gap_ms": 1,
          "schema_version": "studio-ast-2",
          "section_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
          "speaker_registry_version": 1,
          "speakers": [],
          "title": "Chapter One"
        },
        "text": "A bell rang. \"Who is there?\" Mira asked.",
        "media": {
          "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "playback_duration_ms": 1,
          "blocks": [
            {
              "block_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
              "freshness": "absent",
              "activity": "idle",
              "active_block_version": 1,
              "requested_block_version": 1,
              "active_rendition_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
              "audio_version_count": 1,
              "generation_batch_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
              "playback_url": "https://lyricwinter.com/…",
              "playback_url_expires_at": "2026-09-30T17:00:00.000Z",
              "content_type": "string",
              "size_bytes": 1,
              "analysis_integrated_lufs": -120,
              "analysis_sample_peak_dbfs": -200,
              "provider": "string",
              "model": "string",
              "error": "string",
              "stale_reasons": [
                "block_kind"
              ]
            }
          ]
        },
        "play_url": "https://lyricwinter.com/…",
        "latest_exports": [
          {
            "schema_version": 1,
            "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
            "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
            "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
            "format": "mp3",
            "status": "queued",
            "phase": "queued",
            "percent": 1,
            "cache_result": "miss",
            "authority": {
              "document_version": 1,
              "speaker_registry_version": 1,
              "mastering_version": 1,
              "is_current": true
            },
            "created_at": "2026-09-30T17:00:00.000Z",
            "started_at": "2026-09-30T17:00:00.000Z",
            "completed_at": "2026-09-30T17:00:00.000Z",
            "error": {
              "code": "string",
              "message": "string"
            },
            "artifact": {
              "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
              "filename": "string",
              "content_type": "string",
              "size_bytes": 1,
              "download_url": "https://lyricwinter.com/…",
              "download_url_expires_at": "2026-09-30T17:00:00.000Z",
              "artifact_expires_at": "2026-09-30T17:00:00.000Z"
            }
          }
        ]
      }
    ],
    "schema_version": 1,
    "play_url": "https://lyricwinter.com/…",
    "cast": [
      {
        "generation_profile": {
          "provider": "string",
          "model": "string",
          "fallback": "strict",
          "controls": "strict",
          "options": {}
        },
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "name": "My integration",
        "speaker_version": 1,
        "voice_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20"
      }
    ],
    "latest_project_exports": [
      {
        "schema_version": 1,
        "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "project_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "format": "mp3",
        "status": "queued",
        "percent": 1,
        "created_at": "2026-09-30T17:00:00.000Z",
        "sections": [
          {
            "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
            "title": "Chapter One",
            "export_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
            "authority": {
              "document_version": 1,
              "speaker_registry_version": 1,
              "mastering_version": 1
            },
            "export": {
              "schema_version": 1,
              "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
              "project_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
              "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
              "format": "mp3",
              "status": "queued",
              "phase": "queued",
              "percent": 1,
              "cache_result": "miss",
              "authority": {
                "document_version": null,
                "speaker_registry_version": null,
                "mastering_version": null,
                "is_current": null
              },
              "created_at": "2026-09-30T17:00:00.000Z",
              "started_at": "2026-09-30T17:00:00.000Z",
              "completed_at": "2026-09-30T17:00:00.000Z",
              "error": {
                "code": null,
                "message": null
              },
              "artifact": {
                "asset_id": null,
                "filename": null,
                "content_type": null,
                "size_bytes": null,
                "download_url": null,
                "download_url_expires_at": null,
                "artifact_expires_at": null
              }
            },
            "error": {
              "code": "string",
              "message": "string"
            }
          }
        ],
        "archive": null
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}