# Share a render

`POST https://api.vidmoat.com/v1/renders/{id}/share`

- Scope: `render.write`
- Cost: Free

Make a finished export's watch link (vidmoat.com/watch/...), or take it away. The link is unlisted: only people who have it can watch. It plays the choices when the export is interactive.

> **Note.** Never a side effect: call it only when the person asked for a link. Taking a link away is immediate; making it again gives back the same link, so one already posted keeps working.

### Path parameters

- `id` (string, required): The render job id.

### Body

- `share` (boolean, optional, default `true`): `false` takes the link away.
- `title` (string, optional): Shown on the watch page and in link previews. Longer than 120 characters is cut to 120. Default: the title it was last shared with, else the project name.

## Response

Returns `200`.

### Response fields

- `shared` (boolean): Whether the export has a link now.
- `token` (string): The link's id, when shared.
- `url` (string): The watch link, when shared.
- `title` (string): The title on the watch page, when shared.

> **Tip: With a test key.** Test keys share for real.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | The render has not finished, or `share` is not a boolean or `title` not a string. |
| 402 | [`plan_required`](https://developer.vidmoat.com/developer/docs/errors#plan_required) | The render belongs to a project you cannot edit ("Not your render"). |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | No such render. |
| 429 | [`rate_limited`](https://developer.vidmoat.com/developer/docs/errors#rate_limited) | More than 20 share changes in 10 minutes on the account. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/renders/$JOB_ID/share \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"share":true,"title":"Which way?"}'
```

```js Node
const JOB_ID = 'YOUR_JOB_ID';

const res = await fetch(`https://api.vidmoat.com/v1/renders/${JOB_ID}/share`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    share: true,
    title: 'Which way?',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

JOB_ID = "YOUR_JOB_ID"

res = requests.post(
    f"https://api.vidmoat.com/v1/renders/{JOB_ID}/share",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "share": True,
      "title": "Which way?",
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "shared": true,
  "token": "gbPwcFc6AJuI",
  "url": "https://www.vidmoat.com/watch/gbPwcFc6AJuI",
  "title": "Which way?"
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/renders/share-render
Previous: [Get a render](https://developer.vidmoat.com/developer/docs/api/renders/get-render.md)
Next: [List exports for choices](https://developer.vidmoat.com/developer/docs/api/renders/list-interactive-exports.md)
All documentation: https://developer.vidmoat.com/llms-full.txt
