API reference

Sharing API

Share chapters at one story link once Stories publishing opens for your account, inspect sharing state, or unpublish chapters. Before your rollout, these endpoints retain the older listening-link behavior. New chapters start as drafts.

BetaUpdated October 24, 2026

Markdown Ask ChatGPT Ask Claude

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

GET/studio/sections/{sectionId}/share

Scope studio:read

Returns the section’s sharing state and active link, if any. Older-link controls remain available until the link is converted; afterward the link is the story’s /stories/<id>-<slug> page. is_public means the chapter is shared, not that the story is listed as Public. Stories shares also include share.studio_url, the same path under /studio/, opening the owner’s editor or Studio’s shared view with Make a copy. When the owner turns Allow copies off, studio_url is null and visitors use the Stories reading link. The setting defaults to on for Unlisted and Public stories. Both links keep the same visibility and sign-in requirements.

Path parameters

sectionIdstringrequireduuid

Response 200

Current section sharing state. Fields below are inside data.

schema_version1required
section_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

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

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

import os
import requests

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

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

POST/studio/sections/{sectionId}/share

Scope studio:write

Once Stories publishing opens for your account, publishes this chapter and returns the story’s /stories/<id>-<slug> link in share.url. A Private story becomes Unlisted; an existing Unlisted or Public story keeps its visibility and metadata. Blank saved text cannot be published. New chapters start as drafts until explicitly shared or published. Before your rollout, creates or returns the older unlisted listening link. Send an empty JSON object, or name the source surface you shared from. Stories shares also include share.studio_url, the same path under /studio/, opening the owner’s editor or Studio’s shared view with Make a copy. When the owner turns Allow copies off, studio_url is null and visitors use the Stories reading link. The setting defaults to on for Unlisted and Public stories. Both links keep the same visibility and sign-in requirements.

Path parameters

sectionIdstringrequireduuid

Request body application/json

sourcestring
Studio surface the owner shared from.
One oftoolbarplayback_menulibrarycompletion_prompt

Response 201

Section shared with its active link (also returned when it was already shared). Fields below are inside data.

schema_version1required
section_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

curl -X POST "https://lyricwinter.com/api/v1/studio/sections/$SECTION_ID/share" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sections/${sectionId}/share`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const { data, error, request_id } = await response.json();

import os
import requests

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

Response 201 (example)

{
  "data": {
    "schema_version": 1,
    "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

DELETE/studio/sections/{sectionId}/share

Scope studio:write

Once Stories publishing opens for your account, unpublishes this chapter while preserving the story’s visibility and link identity. Sharing again restores the same story link. Before your rollout, revokes the older section link and makes the section private. Send no request body.

Path parameters

sectionIdstringrequireduuid

Response 200

Chapter unpublished, or the older section link revoked before the account rollout. Fields below are inside data.

schema_version1required
section_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

curl -X DELETE "https://lyricwinter.com/api/v1/studio/sections/$SECTION_ID/share" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

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

import os
import requests

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

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

GET/studio/projects/{projectId}/share

Scope studio:read

Returns the project’s sharing state and active link, if any. Older-link controls remain available until the link is converted; afterward the link is the story’s /stories/<id>-<slug> page. is_public describes sharing state, not whether the story is listed as Public. Stories shares also include share.studio_url, the same path under /studio/, opening the owner’s editor or Studio’s shared view with Make a copy. When the owner turns Allow copies off, studio_url is null and visitors use the Stories reading link. The setting defaults to on for Unlisted and Public stories. Both links keep the same visibility and sign-in requirements.

Path parameters

projectIdstringrequireduuid

Response 200

Current project sharing state. Fields below are inside data.

schema_version1required
project_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

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

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/share`, {
  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}/share",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Share a project

POST/studio/projects/{projectId}/share

Scope studio:write

Once Stories publishing opens for your account, publishes the project’s current chapters with saved story text and returns the story’s /stories/<id>-<slug> link in share.url. Blank drafts are skipped; existing chapter publications stay as they are. If no chapters have words, publishes nothing and returns not shared. A Private story becomes Unlisted when chapters are published; existing Unlisted/Public visibility and metadata are preserved. New chapters start as drafts; share the project again or explicitly publish each chapter when ready. Before your rollout, creates or returns the older project listening link. Send an empty JSON object, or name the source surface you shared from. Stories shares also include share.studio_url, the same path under /studio/, opening the owner’s editor or Studio’s shared view with Make a copy. When the owner turns Allow copies off, studio_url is null and visitors use the Stories reading link. The setting defaults to on for Unlisted and Public stories. Both links keep the same visibility and sign-in requirements.

Path parameters

projectIdstringrequireduuid

Request body application/json

sourcestring
Studio surface the owner shared from.
One oftoolbarplayback_menulibrarycompletion_prompt

Response 201

Project shared with its active link, also returned when already shared. Fields below are inside data.

schema_version1required
project_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

curl -X POST "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/share" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/share`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
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}/share",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={},
)
payload = response.json()

Response 201 (example)

{
  "data": {
    "schema_version": 1,
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

DELETE/studio/projects/{projectId}/share

Scope studio:write

Once Stories publishing opens for your account, unpublishes the project’s current chapters while preserving the story’s visibility and link identity. Before your rollout, revokes the older project listening link. Send no request body.

Path parameters

projectIdstringrequireduuid

Response 200

Current chapters unpublished, or the older project listening link revoked before the account rollout. Fields below are inside data.

schema_version1required
project_idstringrequireduuid
is_publicbooleanrequired
shareobject | nullrequired
Active link; non-null exactly when is_public is true.
4 child attributes
- idstringrequireduuid
  Sharing identity; may be the owning project UUID for a story link.
- urlstringrequireduri
  Story URL of the form <origin>/stories/<id>-<slug> once Stories publishing opens for the account; otherwise the older token URL.
- studio_urlstring | nulluri
  For Stories shares, the same story URL under /studio/ opens the owner's editor or Studio's shared view with Make a copy when Allow copies is on (the default for Unlisted and Public stories). Null when Allow copies is off. The same visibility and sign-in requirements apply. Absent for older token shares.
- created_atstringrequireddate-time

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

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

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/share`, {
  method: "DELETE",
  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(
    "DELETE",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/share",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "is_public": true,
    "share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "url": "https://lyricwinter.com/…",
      "studio_url": "https://lyricwinter.com/…",
      "created_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get section sharing

Path parameters

Response 200

Share a section

Path parameters

Request body application/json

Response 201

Stop sharing a section

Path parameters

Response 200

Get project sharing

Path parameters

Response 200

Share a project

Path parameters

Request body application/json

Response 201

Stop sharing a project

Path parameters

Response 200