---
title: "Sharing API"
description: "Publish a section or a whole project at a stable public link, read its sharing state, or revoke the link."
canonical_url: https://lyricwinter.com/docs/api/sharing
markdown_url: https://lyricwinter.com/docs/api/sharing.md
last_updated: 2026-09-30
status: beta
---
# LyricWinter API reference: Sharing

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

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

### Get section sharing

`GET /studio/sections/{sectionId}/share`

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

Returns whether the section is public and its active public link, if any.

#### Path parameters

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

#### Response 200

Current section sharing state.

Fields inside `data`:

- `schema_version` (1; required)
- `section_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public section page URL of the form <origin>/s/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

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

### Share a section

`POST /studio/sections/{sectionId}/share`

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

Creates a stable public link for the section, or returns the existing one. The public page always plays the latest saved version. Send an empty JSON object as the body.

#### Path parameters

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

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

- object: Must be an empty JSON object.

#### Response 201

Section published with its active link (also returned when already public).

Fields inside `data`:

- `schema_version` (1; required)
- `section_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public section page URL of the form <origin>/s/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

```bash
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 '{}'
```

### Stop sharing a section

`DELETE /studio/sections/{sectionId}/share`

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

Revokes the section's public link and makes the section private.

#### Path parameters

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

#### Response 200

Section is private and the prior link is revoked.

Fields inside `data`:

- `schema_version` (1; required)
- `section_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public section page URL of the form <origin>/s/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

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

### Get project sharing

`GET /studio/projects/{projectId}/share`

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

Returns whether the project has a public link and the active link, if any.

#### Path parameters

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

#### Response 200

Current project public-link state.

Fields inside `data`:

- `schema_version` (1; required)
- `project_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public project page URL of the form <origin>/p/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

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

### Share a project

`POST /studio/projects/{projectId}/share`

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

Creates a stable public link for the whole project, or returns the existing one. Send an empty JSON object as the body.

#### Path parameters

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

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

- object: Must be an empty JSON object.

#### Response 201

Stable project public link.

Fields inside `data`:

- `schema_version` (1; required)
- `project_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public project page URL of the form <origin>/p/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

```bash
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 '{}'
```

### Stop sharing a project

`DELETE /studio/projects/{projectId}/share`

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

Revokes the project's public link. Send no request body.

#### Path parameters

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

#### Response 200

Project sharing is revoked.

Fields inside `data`:

- `schema_version` (1; required)
- `project_id` (string, uuid; required)
- `is_public` (boolean; required)
- `share` (object | null; required): Active link; non-null exactly when is_public is true.
  - `id` (string, uuid; required)
  - `url` (string, uri; required): Public project page URL of the form <origin>/p/<token>.
  - `created_at` (string, date-time; required)

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

#### Example request

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