For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/publish-project-share.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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.
PUT https:/
- 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 | Required: Yes | Unique identifier of the project. |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: 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 | Required: No | Optional finished generation ID to pin the share to; omit to follow the project's newest finished generation automatically. |
#preview_seconds | integer | Required: No | Optional playback limit in seconds, from 4 to 3600 (rounded up to whole 4-second segments); omits full-length download files from files. |
Request
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",
)Response
Returns the published project_share with its public id and playback files.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "project_share".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 fields7 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. |
Response 200OK.
{
"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"
}
}Return codes
200OK.Share published or updated and returned with playback URLs.400Bad request.Malformed JSON, or 2 more causes
- Malformed JSON
- Invalid
generation_idorpreview_secondsoutside4to3600 - Oversized header
invalid_jsoninvalid_fieldinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksprojects:write.permission_denied404Not found.Project not found, or pinnedgeneration_idnot found on this project.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Pinned
generation_idis still running, or 2 more causes- Pinned
generation_idis still running - Pinned generation failed or project is being deleted
- A concurrent publish or revoke won (code conflict)
not_readynot_available- Pinned
401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- A share never exposes the uploaded
originalrecording or the project's other generations; withpreview_secondsset, full-lengthaudio,audio_mixed,video,transcript, andmetadataare omitted too. - Republishing with identical
generation_idandpreview_secondskeeps existing URLs working; changing either (or republishing after a revoke) invalidates old URLs within about 60 seconds while keeping the same shareid. - Publishing and serving shares is free.