# Share a collection

Create a public share link for a collection. Returns `201 Created` with the share record, including the raw token shown **once**. Only the collection's owner may share it.

The raw `token` and its `url` are returned only on creation — only a hash is stored, so the token cannot be retrieved later. A non-owner receives `404`. The request body is optional; defaults apply when omitted. A shared collection is read-only for recipients.

## Path parameters

**`organization_id`** string required

The organization the collection is scoped to. The caller must belong to it.

**`collection_id`** string required

The collection id to share (`mcoll_`-prefixed).

## Request Body

**`visibility`** string optional · Defaults to `link_only`

Share visibility. One of `link_only` (only people with the link can open it) or `public`.

**`expires_in_days`** integer optional

Number of days until the link expires (minimum `1`). Values above `90` are clamped to `90`. Omit for a link that never expires.

## Returns

A share link object.

**`id`** string · Share link id (`mslink_`-prefixed).

**`token`** string · The raw share token. Shown only once — only its hash is stored.

**`url`** string · Public URL that opens the share without signing in.

**`target_type`** string · `collection`.

**`visibility`** string · `link_only` or `public`.

**`expires_at`** string · When the link expires (UTC), or `null` for never.

**`created_at`** string · When the link was created (UTC).

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_5e8a1d3f9c27/share" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

share = client.post(
    "/v1/music/org_abc123/collections/mcoll_5e8a1d3f9c27/share",
    json={"visibility": "public"},
)
print(share["url"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_5e8a1d3f9c27/share",
    headers={"X-API-Key": api_key},
    json={"visibility": "public"},
)
print(response.json()["url"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  'https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_5e8a1d3f9c27/share',
  {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ visibility: 'public' }),
  }
);

const share = await response.json();
console.log(share.url);
```

**Response:**


```json 201 Created
{
  "id": "mslink_8c4e2a9f1b73",
  "token": "shr_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "url": "https://api.aitronos.com/v1/music/shared/shr_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "target_type": "collection",
  "visibility": "public",
  "expires_at": null,
  "created_at": "2026-06-28T10:30:00Z"
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "system_message": "Collection not found or not owned by caller",
    "type": "client_error",
    "status": 404,
    "details": { "collection_id": "mcoll_5e8a1d3f9c27" },
    "trace_id": "req_jkl012mno",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Share a track](/docs/api-reference/music/share-track)
- [Open a shared link](/docs/api-reference/music/resolve-share)
- [Revoke a share link](/docs/api-reference/music/revoke-share)