# Build a research collection

A collection is a named group of videos in the server's library: the G-Wagon buyer videos, one course's lectures, a channel you follow. Once videos are in a collection, one id stands for all of them, in a context pack, a zip, an export or a search. This tutorial builds one from two G-Wagon buyer videos.

The steps chain: run step 1 and its collection id fills in every block below it. Until you run it, each block shows the response recorded when this tutorial was written.

## 1. Create the collection

`POST /collections` needs only a `name`. `sources` is optional: playlists, channels or feeds the collection follows, so that a refresh adds their new videos. Change the name if you like; the id is the name as a slug plus a random suffix, so two collections never collide.

**Create a collection** (`POST /api/v1/collections`): The id is the name as a slug plus a random suffix. The blocks below use it once you run this one.

```bash
curl https://vid2context.com/api/v1/collections \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "G-Wagon research",
  "description": "Buyer videos to compare model years"
}'
```

Response recorded on 2026-11-15 (HTTP 201 Created):

```json
{
  "id": "g-wagon-research-2c2983f1",
  "name": "G-Wagon research",
  "description": "Buyer videos to compare model years",
  "sources": [],
  "videoIds": [],
  "createdAt": "2026-11-15T15:29:16.875Z",
  "updatedAt": "2026-11-15T15:29:16.875Z"
}
```
## 2. Add videos

`POST /collections/{id}/items` takes a list of inputs. Each video is read once (captions first, then speech-to-text) and saved in the library, so the steps below never contact YouTube again. A playlist in the list adds each of its videos.

With a jobs queue, the server answers `202` and a Job right away, and the block polls `GET /jobs/{id}` until it finishes. The finished job's `result.summary` lists the videos that were added and those that failed (with the reason), and counts the ones it skipped.

**Add videos to the collection** (`POST /api/v1/collections/{id}/items`): Each video is read once and saved in the library. With a jobs queue this answers 202 and a Job; the runner polls it.

```bash
curl https://vid2context.com/api/v1/collections/g-wagon-research-2c2983f1/items \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc",
    "https://www.youtube.com/watch?v=PzJL3aBRas8"
  ]
}'
```

Response recorded on 2026-11-15 (HTTP 202 Accepted):

```json
{
  "id": "job_cGwJKXxEL5ySzsETnHWCFg",
  "kind": "ingest",
  "status": "succeeded",
  "createdAt": "2026-11-15T15:29:16.882Z",
  "updatedAt": "2026-11-15T15:29:16.891Z",
  "progress": {
    "done": 2,
    "total": 2,
    "message": "Added Why I'm Selling My DREAM G-Wagon (Custom Build 2015 Mercedes G550)"
  },
  "result": {
    "collection": {
      "id": "g-wagon-research-2c2983f1",
      "name": "G-Wagon research",
      "description": "Buyer videos to compare model years",
      "sources": [],
      "videoIds": [
        "youtube:cCPsdFdlshc",
        "youtube:PzJL3aBRas8"
      ],
      "createdAt": "2026-11-15T15:29:16.875Z",
      "updatedAt": "2026-11-15T15:29:16.890Z"
    },
    "summary": {
      "collectionId": "g-wagon-research-2c2983f1",
      "added": [
        {
          "id": "youtube:cCPsdFdlshc",
          "ref": {
            "input": "https://www.youtube.com/watch?v=cCPsdFdlshc",
            "platform": "youtube",
            "kind": "video",
            "id": "youtube:cCPsdFdlshc",
            "nativeId": "cCPsdFdlshc",
            "url": "https://www.youtube.com/watch?v=cCPsdFdlshc"
          },
          "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
          "channel": "Alliance Motorworks",
          "durationSec": 1084,
```

(29 more lines; run the request to see them.)
Try adding the [playlist](https://www.youtube.com/playlist?list=PLHeawKfarQSPKIjpe86at3Ttc2sz7uD_b) itself: put its URL on a line of its own and run the block again. Videos already in the collection are skipped and counted, not read twice.

## 3. Read it back

`GET /collections/{id}` returns the collection with a summary of each video: title, channel, duration, language, and `origin`, which says how its transcript was made.

**Read the collection** (`GET /api/v1/collections/{id}`): Its videos (title, channel, duration, how the transcript was made), videos still pending, and the refresh schedule.

```bash
curl https://vid2context.com/api/v1/collections/g-wagon-research-2c2983f1
```

Response recorded on 2026-11-15 (HTTP 200 OK):

```json
{
  "id": "g-wagon-research-2c2983f1",
  "name": "G-Wagon research",
  "description": "Buyer videos to compare model years",
  "sources": [],
  "videoIds": [
    "youtube:cCPsdFdlshc",
    "youtube:PzJL3aBRas8"
  ],
  "createdAt": "2026-11-15T15:29:16.875Z",
  "updatedAt": "2026-11-15T15:29:16.890Z",
  "videos": [
    {
      "id": "youtube:cCPsdFdlshc",
      "ref": {
        "input": "https://www.youtube.com/watch?v=cCPsdFdlshc",
        "platform": "youtube",
        "kind": "video",
        "id": "youtube:cCPsdFdlshc",
        "nativeId": "cCPsdFdlshc",
        "url": "https://www.youtube.com/watch?v=cCPsdFdlshc"
      },
      "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
      "channel": "Alliance Motorworks",
      "durationSec": 1084,
      "origin": "stt",
      "language": "en",
      "savedAt": "2026-11-14T17:39:41.214Z"
    },
    {
      "id": "youtube:PzJL3aBRas8",
      "ref": {
        "input": "https://www.youtube.com/watch?v=PzJL3aBRas8",
        "platform": "youtube",
        "kind": "video",
        "id": "youtube:PzJL3aBRas8",
        "nativeId": "PzJL3aBRas8",
        "url": "https://www.youtube.com/watch?v=PzJL3aBRas8"
      },
      "title": "Why I'm Selling My DREAM G-Wagon (Custom Build 2015 Mercedes G550)",
```

(10 more lines; run the request to see them.)
## 4. One pack for the whole collection

`POST /pack` with `collectionId` instead of `inputs` builds one Markdown document from every video in the collection, sized by `maxTokens`. Paste it into any chat model, or have an agent read it: the citation rule at the top tells the model to cite each claim as a timestamp link.

**One context pack for the collection** (`POST /api/v1/pack`): The same pack as for a list of inputs, built from every video in the collection.

```bash
curl https://vid2context.com/api/v1/pack \
  -H 'Content-Type: application/json' \
  -d '{
  "collectionId": "g-wagon-research-2c2983f1",
  "maxTokens": 2500
}'
```

Response recorded on 2026-11-15 (HTTP 200 OK):

```text
# Video context pack

This document holds the transcripts and metadata of 2 videos (29:41 in total), prepared by vid2context for an AI model to read. Each transcript paragraph starts with the time it begins in the video, in brackets; linked times open the video at that moment.

Citation rule: when you use something from a video, cite it as [Title @ m:ss](https://github.com/nirholas/vid2context/blob/main/link), using the time and link of the paragraph you drew on (or [Title @ m:ss] when the video has no link).

Some content was left out to fit a budget of 2500 tokens. Each cut is marked where it happened.

## Contents

1. [Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!](#video-1-best--worst-g-wagon-years-reliability-interiors--engines-ranked) (18:04)
2. [Why I'm Selling My DREAM G-Wagon (Custom Build 2015 Mercedes G550)](#video-2-why-im-selling-my-dream-g-wagon-custom-build-2015-mercedes-g550) (11:37)

## Video 1: Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!

- Channel: [Alliance Motorworks](https://www.youtube.com/channel/UCdEjP_BjQ5audhxLKKzZl2A)
- Published: 2025-03-09
- Duration: 18:04
- Source: https://www.youtube.com/watch?v=cCPsdFdlshc
- Language: en
- Transcript: speech-to-text by stt/cloudflare/@cf/openai/whisper-large-v3-turbo

### Description

> Watch this side-by-side comparison of G-Wagons from 2000 - 2018 to rank the best and worst for interiors, engines, and reliability. This is part 1 of a multi-video series for buying and building your

_Description shortened to 199 of 799 characters._

### Chapters

- [0:00](https://www.youtube.com/watch?v=cCPsdFdlshc&t=0s) G wagon buying guide
- [1:05](https://www.youtube.com/watch?v=cCPsdFdlshc&t=65s) G500 m113 engine overview
- [2:04](https://www.youtube.com/watch?v=cCPsdFdlshc&t=124s) G500 interior and features
- [4:12](https://www.youtube.com/watch?v=cCPsdFdlshc&t=252s) G55 AMG specs and history
- [5:50](https://www.youtube.com/watch?v=cCPsdFdlshc&t=350s) G55 interior and technology
- [8:25](https://www.youtube.com/watch?v=cCPsdFdlshc&t=505s) Best G-Wagon for your budget
- [9:39](https://www.youtube.com/watch?v=cCPsdFdlshc&t=579s) G550 technological leap
- [12:27](https://www.youtube.com/watch?v=cCPsdFdlshc&t=747s) 2016-2018 G-Wagon updates
- [14:01](https://www.youtube.com/watch?v=cCPsdFdlshc&t=841s) Final recommendations

```

(54 more lines; run the request to see them.)
`POST /bundle` takes the same `collectionId` for a zip with every format, and `GET /search?collectionId=<id>` searches only this collection's transcripts.

## 5. Notes for Obsidian

`POST /exports/obsidian` turns videos into Markdown notes with frontmatter, chapter headings and timestamp links, plus an index note. The server writes nothing: the answer holds the files, for you or your agent to save into a vault. The MCP tool `export_obsidian` writes them into a vault path for you.

The block exports one video. Paste your collection id from step 1 into **Collection id** to export every video in the collection as well.

**Export notes for Obsidian** (`POST /api/v1/exports/obsidian`): One Markdown note per video with frontmatter, chapters and timestamp links, and an index note. The server writes nothing: you get the files.

```bash
curl https://vid2context.com/api/v1/exports/obsidian \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=PzJL3aBRas8"
  ]
}'
```

Response recorded on 2026-11-15 (HTTP 200 OK):

```json
{
  "files": [
    {
      "path": "vid2context/Why I'm Selling My DREAM G-Wagon (Custom Build 2015 Mercedes G550).md",
```

(5 more lines; run the request to see them.)
## 6. Share the definition

`GET /collections/{id}/export` returns a small, portable definition: the name, the sources, the video URLs and the refresh schedule. Send it to another vid2context server with `POST /collections/import` (add `?refresh=1` to read the videos right away) and that server rebuilds the same collection from the platforms.

**Export the collection definition** (`GET /api/v1/collections/{id}/export`): Name, sources, video ids and schedule: everything another server needs to rebuild the collection with POST /collections/import.

```bash
curl https://vid2context.com/api/v1/collections/g-wagon-research-2c2983f1/export
```

Response recorded on 2026-11-15 (HTTP 200 OK):

```json
{
  "format": "vid2context.collection",
  "version": 1,
  "name": "G-Wagon research",
  "description": "Buyer videos to compare model years",
  "sources": [],
  "videos": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc",
    "https://www.youtube.com/watch?v=PzJL3aBRas8"
  ]
}
```
## Keep it up to date

A collection with `sources` can refresh itself. `PATCH /collections/{id}` with a `watch` schedule (for example `{"every": "daily", "at": "06:00"}`, in UTC) checks the sources on that schedule and adds new videos, and a webhook can tell you when it did. The [collections guide](https://vid2context.com/docs/guides/collections.md) covers schedules, webhooks and limits.

## Next

- [Cited answers and briefs](https://vid2context.com/docs/tutorials/cited-answers.md): ask questions across the videos you just collected.
- [Collections and library examples](https://vid2context.com/docs/examples/collections.md): every request on one page, plus the library itself.
