> ## Documentation Index
> Fetch the complete documentation index at: https://docs.demomatic.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Series

> Organize multiple demo videos into a playlist and embed it anywhere with a single iframe.

A video series is an ordered playlist of demo videos. Use series to group related demos — for example, an onboarding walkthrough across multiple features — and share or embed them as a single experience.

## Create a series

Send a `POST` request to `/video_series` with a title and the domain the series belongs to:

```bash theme={null}
curl -X POST https://api.demomatic.tech/video_series \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Acme",
    "description": "A walkthrough of the core features for new users.",
    "domain_id": 42,
    "is_public": true
  }'
```

The response includes the new series with its `id`. Use this `id` for all subsequent operations.

## Add videos to a series

Replace the full video list for a series using `PUT /video_series/:id/videos`. Pass an ordered array of video IDs — the array order determines the playlist order:

```bash theme={null}
curl -X PUT https://api.demomatic.tech/video_series/7/videos \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": [101, 205, 310]
  }'
```

This call replaces the existing video list entirely. To remove all videos, pass an empty array.

## Reorder a single video

Move one video to a new position without replacing the entire list:

```bash theme={null}
curl -X PATCH https://api.demomatic.tech/video_series/7/videos/205/position \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "position": 0 }'
```

Positions are zero-indexed. Demomatic shifts the other videos automatically.

## Update series details

Update the title, description, cover image URL, or visibility with `PUT /video_series/:id`:

```bash theme={null}
curl -X PUT https://api.demomatic.tech/video_series/7 \
  -H "Authorization: Bearer dm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Onboarding Walkthrough",
    "is_public": false
  }'
```

### Upload a cover image

Upload a cover image (PNG, JPG, or WebP, up to 2 MB) using multipart form data:

```bash theme={null}
curl -X POST https://api.demomatic.tech/video_series/7/cover \
  -H "Authorization: Bearer dm_your_key_here" \
  -F "cover=@/path/to/cover.png"
```

## Public vs. private series

The `is_public` field controls who can access a series:

| Value   | Behaviour                                                          |
| ------- | ------------------------------------------------------------------ |
| `true`  | The series is accessible via public endpoints and can be embedded. |
| `false` | The series requires authentication to view. It cannot be embedded. |

<Note>
  Only public series (`is_public: true`) can be embedded. Attempting to embed a private series returns a `404`.
</Note>

## List series for a domain

Retrieve all series for a domain — optionally filtered by visibility:

```bash theme={null}
# All series
curl https://api.demomatic.tech/video_series/42 \
  -H "Authorization: Bearer dm_your_key_here"

# Public series only
curl "https://api.demomatic.tech/video_series/42?is_public=true" \
  -H "Authorization: Bearer dm_your_key_here"
```

## Delete a series

```bash theme={null}
curl -X DELETE https://api.demomatic.tech/video_series/7 \
  -H "Authorization: Bearer dm_your_key_here"
```

Deleting a series removes it and all its video memberships. The underlying videos are not deleted.

## Embed a series

Any public series can be embedded in an external site using an iframe. The embed page is a full-page player that hides navigation automatically.

### Get the embed snippet

```bash theme={null}
curl https://api.demomatic.tech/video_series/embed/public/42/7/snippet
```

Response:

```json theme={null}
{
  "data": {
    "embed_url": "https://api.demomatic.tech/video_series/embed/public/42/7",
    "snippet": "<iframe src=\"https://api.demomatic.tech/video_series/embed/public/42/7\" width=\"100%\" height=\"100%\" frameborder=\"0\" allowfullscreen style=\"border: none;\"></iframe>"
  }
}
```

### Add the iframe to your page

Paste the embed URL into an `<iframe>` on any page:

```html theme={null}
<iframe
  src="https://api.demomatic.tech/video_series/embed/public/{domain_id}/{series_id}"
  title="Demo Series"
  width="100%"
  height="500"
  style="border: none;"
></iframe>
```

Replace `{domain_id}` and `{series_id}` with your values.

<Tip>
  Set a fixed height (e.g. `500px`) or use a CSS aspect ratio wrapper to ensure the player renders correctly at all viewport sizes.
</Tip>

## View a public series without embedding

You can also link viewers directly to the public series page or fetch the series data for use in a custom player:

```bash theme={null}
# Get a public series with its videos (no auth required)
curl https://api.demomatic.tech/video_series/public/42/7
```

The response includes the series metadata, domain CTA settings, and an ordered list of videos with presigned playback URLs.