# Get a shareable Magicast link

`POST /magicast.shareLink`

## Description

Returns a shareable player URL for a Magicast. Pass the `id` obtained from
[`/magicast.list`](/docs/api/magicast-list) or
[`/magicast.info`](/docs/api/magicast-info).

This endpoint is **get-or-create**: it returns the Magicast's existing
share link, or mints one the first time it is called. Repeat calls for the
same Magicast return the same URL.

Creating a share link is a deliberate action, which is why it has its own
endpoint rather than being returned as a field that is always present on
`magicast.list` / `magicast.info`. Fetching a Magicast never mints a
shareable link as a side effect. `magicast.info` includes `shareUrl` only
when a link already exists.

The URL is `https://ro.am/share/{key}`. There is no
`https://ro.am/magicast/{id}` route.

You can only create a share link for a Magicast you can access; the same
access check as `magicast.info` applies.

**Access:** Organization and Personal. Personal access tokens restrict to
Magicasts owned by the authenticated user.

**Required scope:** `magicast:read`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The Magicast ID. |

## Responses

### 200 - The Magicast's shareable link.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The Magicast ID. |
| `url` | string | Yes | The shareable player URL (`https://ro.am/share/{key}`). |


#### Example Response

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://ro.am/share/abcd1234-efgh5678-ijkl9012-mnop3456"
}
```

### 400 - Bad request. Missing or invalid `id`.

### 401 - Presented invalid authentication credentials.

### 404 - Magicast not found or not accessible.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/magicast-share-link*