# Videos

URL: https://docs.boldvideo.com/sdk/videos



The `videos` namespace reads video content from your library. Only **public** videos are returned by list endpoints; unlisted videos resolve by direct ID.

## `videos.list(options?)`

```typescript
// Latest videos (default: 12)
const { data: videos } = await bold.videos.list();

// With a limit
const { data: videos } = await bold.videos.list(20);

// Filtered
const { data: videos } = await bold.videos.list({
  limit: 20,
  tag: 'sales',
  collectionId: 'col_123',
  viewerId: 'viewer_123'  // include this viewer's watch progress
});

// Paginated browsing
const { data: videos } = await bold.videos.list({
  page: 2,
  tag: 'sales'
});
```

| Option         | Type     | Description                                                      |
| -------------- | -------- | ---------------------------------------------------------------- |
| `limit`        | `number` | Max videos (latest-style queries)                                |
| `page`         | `number` | Page number (paginated queries, mutually exclusive with `limit`) |
| `tag`          | `string` | Filter by tag                                                    |
| `collectionId` | `string` | Filter by collection                                             |
| `viewerId`     | `string` | Attach the viewer's progress to each video                       |

## `videos.get(idOrSlug)`

```typescript
const { data: video } = await bold.videos.get('video-id');
const { data: video } = await bold.videos.get('my-video-slug');

console.log(video.title);
console.log(video.playbackId);   // for your player
console.log(video.chapters);     // [{ title, start }, …]
console.log(video.transcript);   // full transcript with segments
```

Works with either the video's UUID or its slug.

## `videos.search(term)`

```typescript
const { data: results } = await bold.videos.search('pricing strategies');
```

Keyword + semantic search over public videos. For search with an AI-synthesized answer, use [`ai.search`](/sdk/ai-methods#aisearchoptions).

## The Video object

The fields you'll actually use:

| Field                                          | Description                                       |
| ---------------------------------------------- | ------------------------------------------------- |
| `id`, `slug`, `title`, `teaser`, `description` | Identity and metadata                             |
| `playbackId`, `streamUrl`                      | Playback: works with Mux Player or any HLS player |
| `duration`                                     | Seconds                                           |
| `thumbnail`                                    | Thumbnail URL                                     |
| `chapters`                                     | Timestamped chapters                              |
| `transcript`                                   | Full transcript (text + segments)                 |
| `captions`                                     | Caption tracks                                    |
| `attachments`                                  | Files attached to the video                       |
| `downloadUrls`                                 | MP4 / audio downloads                             |
| `cta`                                          | The video's call-to-action, if set                |
| `tags`, `type`, `publishedAt`                  | Organization                                      |

Full definitions in [Types](/sdk/types).