---
title: "Create a shareable asset"
method: POST
path: "/share"
tags: ["Share"]
---

# Create a shareable asset

`POST /share`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/share`
- Auth: HTTP bearer

Create a shareable asset. Public assets (the default) are viewable by anyone with the link; private assets are restricted to members of the owning account and stream via a signed, token-gated playback url. A file (or file segment) can have at most one active share per visibility — one public and one private — each with its own stable URL; creating a second of the same visibility returns 409.

## Request body

- CreateShareableAssetRequest
  - `file_id` string, uuid, required: The ID of the file the shareable asset will be created for
  - `file_segment_id` string, uuid: The ID of the file segment the shareable asset will be created for. When provided, the shareable asset will be created for the file segment.
  - `title` string: The title of the shareable asset
  - `description` string: The description of the shareable asset
  - `metadata` object: The metadata of the shareable asset
  - `visibility` 'public' | 'private': Visibility of the shareable asset. Defaults to 'public'. 'private' restricts the share page to members of the owning account and serves a signed, token-gated stream. Cannot be changed after creation.
  - `link_preview` 'none' | 'full' | 'player': Rich link-preview metadata for unfurl bots. Only affects private shares: 'none' (default) keeps today's no-preview behavior; 'full' emits title, description, and thumbnail Open Graph tags; 'player' additionally lets the share play inline when unfurled by the Cloudglue Slack app — anyone who can see the Slack message can play it. Public shares always emit full metadata.

## Response `200`

Shareable asset created successfully

- ShareableAsset
  - `id` string, uuid, required: The unique identifier of the shareable asset
  - `file_id` string, uuid, required: The ID of the file the shareable asset belongs to
  - `file_segment_id` string, uuid: The ID of the file segment the shareable asset belongs to (optional)
  - `title` string: The title of the shareable asset
  - `description` string: The description of the shareable asset
  - `metadata` object: The metadata of the shareable asset
  - `visibility` 'public' | 'private': The visibility of the shareable asset. 'public' assets are viewable by anyone with the link; 'private' assets are restricted to members of the owning account and stream via a signed, token-gated playback url.
  - `link_preview` 'none' | 'full' | 'player', required: Controls rich link-preview (Open Graph) metadata for unfurl bots on private shares. 'none' (default) emits no preview metadata; 'full' emits title, description, and thumbnail; 'player' additionally lets the share play inline when its link is unfurled by the Cloudglue Slack app — anyone who can see the Slack message can play it. Public shares always emit full metadata (and unfurl playable where the Slack app is installed) regardless of this value.
  - `preview_url` string: The thumbnail url of the shareable asset
  - `media_download_url` string: The signed media download url of the shareable asset. For private assets this url is short-lived (a few minutes) and should be used promptly.
  - `media_download_expires_at` number, nullable: The timestamp of when the media download url will expire
  - `share_url` string: This is the url that can be used to share the shareable asset. For private assets the page requires sign-in and membership of the owning account.
  - `stream_url` string: The HLS stream url of the shareable asset. Available when the stream has finished processing. For private assets this is a signed, token-gated url that should be treated as short-lived. When the asset was fetched with a clip window (clip_start/clip_end on GET /share/{id}), the stream plays only that window.
  - `status` 'pending' | 'processing' | 'completed' | 'failed': The status of the shareable asset
  - `asset_type` 'file' | 'file_segment': The type of asset the shareable asset belongs to
  - `created_at` number, required: The timestamp of when the shareable asset was created
  - `object` 'share': Object type, always 'share'

## Other responses

- `400`: Invalid request parameters or configuration
- `403`: Usage limit reached (monthly shareable assets) — `code: usage_limit_reached`
- `404`: File or file segment not found
- `409`: Shareable asset already exists
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 5 info
  - added the non-success response with the status `403`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `409` status
  - …1 more
- **2026-08-12** `725b9736a231`: 1 warning, 1 info
  - added the new `player` enum value to the `link_preview` response property for the response status `200`
  - added the new `player` enum value to the request property `link_preview`
- **2026-07-19** `42caafb55f9f`: 2 info
  - added the new optional request property `link_preview`
  - added the required property `link_preview` to the response with the `200` status
- **2026-06-04** `a100e95d54ba`: 2 info
  - added the new optional request property `visibility`
  - added the optional property `visibility` to the response with the `200` status
- **2026-02-26** `8c51909240f6`: 1 info
  - added the optional property `stream_url` to the response with the `200` status

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/share/post.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)