# Collections and library

Every video a request reads is saved in the server's library. Collections are named groups of saved videos that one id stands for. The blocks on this page chain: run **Create a collection** and its id fills in the blocks after it. The CLI equivalents are `npx -y vid2context collection ...` and `npx -y vid2context library ...`, and agents use the MCP tools `create_collection`, `add_to_collection` and `get_collection`.

## Create a collection

**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"
}
```
## Add videos

**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.)
## Read a collection

**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.)
## Pack a collection

**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.)
## Export Obsidian notes

**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.)
## Export the definition

**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"
  ]
}
```
## List the library

**List the library** (`GET /api/v1/library`): Every saved video, newest first. A page with more after it has a cursor to pass back.

```bash
curl -G https://vid2context.com/api/v1/library \
  --data-urlencode limit=5
```

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

```json
{
  "items": [
    {
      "id": "youtube:MBRqu0YOH14",
      "ref": {
        "input": "https://www.youtube.com/watch?v=MBRqu0YOH14",
        "platform": "youtube",
        "kind": "video",
        "id": "youtube:MBRqu0YOH14",
        "nativeId": "MBRqu0YOH14",
        "url": "https://www.youtube.com/watch?v=MBRqu0YOH14"
      },
      "title": "Optimistic Nihilism",
      "channel": "Kurzgesagt – In a Nutshell",
      "durationSec": 446,
      "origin": "creator-captions",
      "language": "en",
      "savedAt": "2026-11-14T18:44:32.282Z"
    },
    {
      "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.222Z"
    },
    {
      "id": "youtube:PzJL3aBRas8",
      "ref": {
        "input": "https://www.youtube.com/watch?v=PzJL3aBRas8",
```

(15 more lines; run the request to see them.)
## Read one saved video

**One saved video** (`GET /api/v1/library/{id}`): The saved VideoContext, read from storage without contacting the platform.

```bash
curl https://vid2context.com/api/v1/library/youtube%3AMBRqu0YOH14
```

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

```json
{
  "metadata": {
    "ref": {
      "input": "https://www.youtube.com/watch?v=MBRqu0YOH14",
      "platform": "youtube",
      "kind": "video",
      "id": "youtube:MBRqu0YOH14",
      "nativeId": "MBRqu0YOH14",
      "url": "https://www.youtube.com/watch?v=MBRqu0YOH14"
    },
    "title": "Optimistic Nihilism",
    "description": "The philosophy of Kurzgesagt.\n\n\nOUR CHANNELS\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nGerman Channel: https://kgs.link/youtubeDE \nSpanish Channel: https://kgs.link/youtubeES \n\n\nHOW CAN YOU SUPPORT US?\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nThis is how we make our living and it would be a pleasure if you support us!\n\nGet Merch designed with ❤ from https://kgs.link/shop  \nJoin the Patreon Bird Army 🐧 https://kgs.link/patreon  \n\n\nDISCUSSIONS & SOCIAL MEDIA\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nReddit:            https://kgs.link/reddit\nInstagram:     https://kgs.link/instagram\nTwitter:           https://kgs.link/twitter\nFacebook:      https://kgs.link/facebook\nDiscord:          https://kgs.link/discord\nNewsletter:    https://kgs.link/newsletter\n\n\nOUR VOICE\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\nThe Kurzgesagt voice is from \nSteve Taylor:  https://kgs.link/youtube-voice\n\n\nOUR MUSIC ♬♪\n▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀\n700+ minutes of Kurzgesagt Soundtracks by Epic Mountain:\n\nSpotify:            https://kgs.link/music-spotify\nSoundcloud:   https://kgs.link/music-soundcloud\nBandcamp:     https://kgs.link/music-bandcamp\nYoutube:          https://kgs.link/music-youtube\nFacebook:       https://kgs.link/music-facebook\n\nThe Soundtrack of this video:\nSoundcloud: http://bit.ly/2vZRSnI\nBandcamp: http://bit.ly/2tYuKUY\nFacebook: http://bit.ly/2qW6bY4\n\n\nHelp us caption & translate this video!\n\nhttp://www.youtube.com/timedtext_cs_panel?c=UCsXVk37bltHxD1rDPwtNM8Q&tab=2\n\nOptimistic Nihilism",
    "durationSec": 446,
    "publishedAt": "2017-07-26",
    "thumbnailUrl": "https://i.ytimg.com/vi/MBRqu0YOH14/maxresdefault.jpg",
    "language": "en",
    "tags": [
      "optimism",
      "existence",
      "existential",
      "meaning of life",
      "purpose",
      "existentialism",
      "atheism",
      "philosophy",
      "nihilism"
    ],
    "chapters": [],
    "isLive": false,
    "extra": {
      "viewCount": 18903134,
      "likeCount": 982145,
      "dateText": "Jul 26, 2017",
      "channelHandle": "@kurzgesagt",
      "channelHandleUrl": "https://www.youtube.com/@kurzgesagt",
      "subscriberCountText": "25.8M subscribers",
      "isShort": false,
      "isLive": false,
      "isUpcoming": false,
      "isLiveContent": false,
```

(530 more lines; run the request to see them.)
Saved videos answer without contacting the platform. `GET /context?url=...&refresh=1` reads a video again and replaces the saved copy. [Build a research collection](https://vid2context.com/docs/tutorials/collections.md) walks through these requests in order.
