> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/publish-project-share/.

# Publish a project's share

Publishes a project's public playback share (or updates what an existing share plays), returning a 17-character share `id` readable without an API key at [Get a share](https://diffio.ai/docs/api-reference/get-share/).

PUT `https://api.diffio.ai/v2/projects/{project_id}/share`

- Key scope: `projects:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

## Request

Send `{}` to share the project's newest finished generation in full, or pass optional `generation_id` and `preview_seconds`.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `generation_id` | string | No | Optional finished generation ID to pin the share to; omit to follow the project's newest finished generation automatically. |
| `preview_seconds` | integer | No | Optional playback limit in seconds, from `4` to `3600` (rounded up to whole 4-second segments); omits full-length download files from `files`. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

share = client.shares.publish(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const share =
  await client.shares.publish(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  )
```

**cURL**

```bash
curl -X PUT "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/share" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**JSON: JSON body**

```json
{}
```

## Response

Returns the published `project_share` with its public `id` and playback `files`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"project_share"`. |
| `id` | string | Always | Public 17-character share identifier passed to `GET /shares/{share_id}`. |
| `generation_id` | string \| null | Always | Identifier of the shared generation, or `null` until the project has a finished generation. |
| `files` | object | Always | Map of shared playback artifact names to signed media URLs (never includes `original`); `{}` until a generation finishes. |
| `base_url` | string \| null | Always | URL prefix shared by every entry in `files` (plays `hls_master` in standard HLS players), or `null` until a generation finishes. |

**Other response fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `project_id` | string | Always | Identifier of the shared project. |
| `file_name` | string \| null | Always | Recording filename on the project, or `null`. |
| `content_type` | string \| null | Always | Recording MIME type, or `null`. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the share was first published, or `null`. |
| `has_video` | boolean | Always | True when the project contains video. |
| `duration_seconds` | number \| null | Always | Duration of the shared recording in seconds, or `null`. |
| `preview_seconds` | integer \| null | Always | Playback cap in seconds (rounded up to whole 4-second segments), or `null` when the full recording is shared. |

## Example response (200)

**Response, key fields: Response: key fields**

```json
{
  "object": "project_share",
  "id": "Hq7cTnWm3RkZpY2vB",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "base_url": "https://media.diffio.io/s/v1.REDACTED/",
  "files": {
    "audio": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3",
    "audio_mixed": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3",
    "hls_master": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8",
    "hls_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8",
    "hls_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8",
    "metadata": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json",
    "stems_manifest": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json",
    "transcript": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json",
    "waveform_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json",
    "waveform_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"
  }
}
```

**Full response: Successful response**

```json
{
  "object": "project_share",
  "id": "Hq7cTnWm3RkZpY2vB",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "file_name": "interview.mp3",
  "content_type": "audio/mpeg",
  "created_at": "2026-11-13T00:34:06.463210Z",
  "has_video": false,
  "duration_seconds": 31.9,
  "preview_seconds": null,
  "base_url": "https://media.diffio.io/s/v1.REDACTED/",
  "files": {
    "audio": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/restored.mp3",
    "audio_mixed": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/mixed.mp3",
    "hls_master": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/master.m3u8",
    "hls_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/noisy/index.m3u8",
    "hls_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/hls/clean/index.m3u8",
    "metadata": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/metadata.json",
    "stems_manifest": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/stems/4014a8c299444bbb866971bbb7b657ca/manifest.v2.json",
    "transcript": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/word_timestamps.json",
    "waveform_original": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_noisy.json",
    "waveform_restored": "https://media.diffio.io/s/v1.REDACTED/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/visualizations/hls_waveform_clean.json"
  }
}
```

## Return codes

- `200` Share published or updated and returned with playback URLs.
- `400`
  - Malformed JSON: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json)
  - Invalid `generation_id` or `preview_seconds` outside `4` to `3600`: [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field)
  - Oversized header: [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `projects:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or pinned `generation_id` not found on this project. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- `409`
  - Pinned `generation_id` is still running
  - Pinned generation failed or project is being deleted
  - A concurrent publish or revoke won (code conflict)
  Codes: [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready), [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- A share never exposes the uploaded `original` recording or the project's other generations; with `preview_seconds` set, full-length `audio`, `audio_mixed`, `video`, `transcript`, and `metadata` are omitted too.
- Republishing with identical `generation_id` and `preview_seconds` keeps existing URLs working; changing either (or republishing after a revoke) invalidates old URLs within about 60 seconds while keeping the same share `id`.
- Publishing and serving shares is free.

## Related pages

- Previous: [Send assistant feedback](https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/): Send the Diffio team a bug report or an idea about the edit assistant, with the conversation if wanted.
- Next: [Get a project's share](https://diffio.ai/docs/api-reference/get-project-share/): Read a project's currently published share and its playback URLs using your API key.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [API reference](https://diffio.ai/docs/api-reference/introduction/): Base URL, authentication, errors and every endpoint.
