# Publish choices

`POST https://api.vidmoat.com/v1/projects/{id}/interactive`

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

Put an interactive project's choices on one of its finished exports so its watch link plays them, update them after a change without rendering again, or take them off.

> **Note.** Publishing never makes a private video public: `share` is a separate, explicit field. See the Interactive video guide for the commands that build the choices.

### Path parameters

- `id` (string, required): The project id.

### Body

- `exportId` (string, required): The export (render job id) to publish on. It must still show the project's picture: `samePicture` in the list.
- `publish` (boolean, optional, default `true`): `false` takes the choices off; the video plays as an ordinary one.
- `share` (boolean, optional): `true` also makes the watch link and returns it as `shareUrl`; `false` takes the link away. Omit to leave the link as it is.

## Response

Returns `200`.

### Response fields

- `ok` (boolean): `true`.
- `published` (boolean): Whether the export carries choices now.
- `scenes` (integer): With `publish: true`: scenes published.
- `items` (integer): With `publish: true`: interactive parts published.
- `shareUrl` (string or null): With `publish: true`: the watch link, or `null` when the export has none.
- `note` (string): With `publish: true`, no link and no `share` sent: how to make one.
- `shared` (boolean): Only when `share` was sent: whether the export has a link now.
- `shareError` (string): Only when `share` was sent and changing the link failed. The publish itself still happened.

> **Tip: With a test key.** Test keys publish 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 |
| --- | --- | --- |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | No such project, or it is not yours. The two are indistinguishable on purpose. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `exportId` is missing, or `publish` or `share` is not a boolean. |
| 402 | [`plan_required`](https://developer.vidmoat.com/developer/docs/errors#plan_required) | The plan cannot publish an interactive link, or interactive video is not switched on for this account. |
| 409 | [`conflict`](https://developer.vidmoat.com/developer/docs/errors#conflict) | The export has not finished, was made before exports were fingerprinted, or the picture changed since (render again); the project has no choices; or the choices would leave a viewer stuck (`problems` lists them). |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/projects/$ID/interactive \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exportId":"clx9abc123","share":true}'
```

```js Node
const ID = 'YOUR_PROJECT_ID';

const res = await fetch(`https://api.vidmoat.com/v1/projects/${ID}/interactive`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    exportId: 'clx9abc123',
    share: true,
  }),
});
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

ID = "YOUR_PROJECT_ID"

res = requests.post(
    f"https://api.vidmoat.com/v1/projects/{ID}/interactive",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "exportId": "clx9abc123",
      "share": True,
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "ok": true,
  "published": true,
  "scenes": 3,
  "items": 2,
  "shareUrl": "https://www.vidmoat.com/watch/gbPwcFc6AJuI",
  "shared": true
}
```

---

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