# Cited answers and briefs

The routes in this tutorial put a language model on top of the transcripts. They run on the free LLM chain (keyless rungs need no account), and they never trust the model's citations blindly: every quote is looked up in the transcript near the time it claims, and claims that fail the check are reported separately.

## 1. Ask a question

`POST /ask` takes a question and the videos to answer from. The answer cites sources by number; `citations` holds each one with its video, its time range, a timestamp link and the quote, and `unverified` lists the numbers whose quote was not found.

**Ask a question** (`POST /api/v1/ask`): A cited answer from the free LLM chain. Every citation is checked against the transcript.

```bash
curl https://vid2context.com/api/v1/ask \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "What does he say about the elephants?",
  "inputs": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ]
}'
```

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

```json
{
  "answer": "He says the cool thing about the elephants is that they have \"really... really really long trunks\" and adds \"that's pretty much all there is to say\" [1].",
  "citations": [
    {
      "n": 1,
      "videoId": "youtube:jNQXAC9IVRw",
      "title": "Me at the zoo",
      "startSec": 5.318,
      "endSec": 12.616,
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&t=5s",
      "quote": "the cool thing about these guys is that they have really... really really long trunks"
    }
  ],
  "unverified": [],
  "sources": [
    {
      "n": 1,
      "videoId": "youtube:jNQXAC9IVRw",
      "title": "Me at the zoo",
      "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&t=1s",
      "startSec": 1.2,
      "endSec": 18.881,
      "text": "All right, so here we are, in front of the elephants the cool thing about these guys is that they have really... really really long trunks and that's cool (baaaaaaaaaaahhh!!) and that's pretty much all there is to say"
    }
  ],
  "rung": "llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free",
  "model": "nvidia/nemotron-3-ultra-550b-a55b:free",
  "usage": {
    "inputTokens": 426,
    "outputTokens": 38
  },
  "attempts": [
    {
      "id": "llm/cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "stage": "llm",
      "outcome": "skipped",
      "reason": "cooldown"
    },
    {
      "id": "llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free",
```

(6 more lines; run the request to see them.)
`rung` and `model` say which model answered. With no keys set that is a keyless rung; add a key to the server and its free-tier rungs are tried first.

## 2. Stream it

The same request with `"stream": true` answers with server-sent events, so a chat interface can show the answer as it is written:

- `meta` once at the start: the rung, the sources and the prompt size;
- `delta` with each piece of the answer;
- `done` with the full text and the verified citations, or `error`.

**Stream the answer** (`POST /api/v1/ask`): Server-sent events: meta (rung, sources), delta (answer text), then done with the citations.

```bash
curl -N https://vid2context.com/api/v1/ask \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "What does he say about the elephants?",
  "inputs": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "stream": true
}'
```

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

```text
3 events
meta: llm/kilo/nvidia/nemotron-3-ultra-550b-a55b:free (1 source, about 429 prompt tokens)
done: 1 citation verified

He says the cool thing about the elephants is that they have "really... really really long trunks" and adds "that's pretty much all there is to say" [1].
```
The JavaScript and Python snippets show how to read the stream without a library.

## 3. A cited brief

`POST /briefs` writes a whole document: findings grouped by theme, where the videos agree and disagree, and the sources, as Markdown and as structured `claims`. Every claim in the body carries a citation that passed the check; the ones that did not go to an appendix, uncited.

A brief takes longer than an HTTP request should wait, so a server with a jobs queue (the Node server has one) answers `202` with a Job right away. The block polls `GET /api/v1/jobs/{id}` every second and a half and shows the result when the job succeeds. A server without a queue answers `200` with the brief itself; the snippets handle both.

**A cited brief** (`POST /api/v1/briefs`): With a jobs queue the server answers 202 and a Job; the runner polls it until it finishes.

```bash
curl https://vid2context.com/api/v1/briefs \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc"
  ],
  "question": "Which G-Wagon years are the most reliable, and which should be avoided?",
  "template": "brief"
}'
```

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

```json
{
  "id": "job_lYMaq0xawP63Qy0oxwdG_w",
  "kind": "brief",
  "status": "succeeded",
  "createdAt": "2026-11-14T18:44:47.551Z",
  "updatedAt": "2026-11-14T18:46:06.261Z",
  "progress": {
    "done": 0,
    "total": 1,
    "message": "Reading 1 video(s) in one pass"
  },
  "result": {
    "question": "Which G-Wagon years are the most reliable, and which should be avoided?",
    "template": "brief",
    "strategy": "single",
```

(585 more lines; run the request to see them.)
Pick another **Template** for a different shape: `summary`, `buyer-guide`, `comparison` or `tutorial-steps`.

## 4. Structured data

`POST /extract` returns JSON instead of prose. Use a built-in template:

**Structured data from a template** (`POST /api/v1/extract`): JSON that matches the template, with citations verified against the transcript.

```bash
curl https://vid2context.com/api/v1/extract \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc"
  ],
  "template": "buyer-guide"
}'
```

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

```json
{
  "id": "job_au2MqiPGOLjoJNGg4_Mlyw",
  "kind": "extract",
  "status": "succeeded",
  "createdAt": "2026-11-14T18:46:07.203Z",
  "updatedAt": "2026-11-14T18:48:07.205Z",
  "progress": {
    "done": 0,
    "total": 1,
    "message": "Extracting"
  },
  "result": {
    "template": "buyer-guide",
    "data": {
      "product": "Mercedes-Benz G-Wagon",
      "summary": "The videos provide a year-by-year breakdown of the W463 platform, highlighting that early MBUSA G500s (2002-2010) offer the best value for first-time buyers, the G55 AMG (2003-2012) provides supercharged power at higher maintenance cost, and the 2013-2018 G550/G63 generations represent the best daily driver and off-road platforms with modern interiors and reliable engines, though the 2016-2018 bi-turbo models add complexity with extra coolers limiting bumper options. Ultimately, the best choice depends on whether the buyer prioritizes economy, power, or daily usability.",
      "models": [
        {
          "name": "G500 (M113 V8)",
          "years": "2000-2012",
          "verdict": "Reliable, entry-level value; the M113 engine is legendary and as reliable as it gets.",
          "sources": [
            {
              "videoId": "youtube:cCPsdFdlshc",
              "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
              "startSec": 0,
              "endSec": 39.08,
              "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=0s",
              "quote": "So you're going to buy a G-Wagon. Which year is best for you? Well, in this video, we're going to do a year-by-year breakdown of the legendary W463 platform, so you can check out the model year ranges, the engine options, and the interior, because if you buy the wrong one, I don't want you getting buyer's remorse or ending up with a bad specimen."
            }
          ]
        },
        {
          "name": "G55 AMG (supercharged M113)",
          "years": "2003-2012",
          "verdict": "Robust and reliable but drinks oil; 490 horsepower supercharged motor is a blast but higher maintenance-intensive.",
          "sources": [
            {
              "videoId": "youtube:cCPsdFdlshc",
              "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
```

(435 more lines; run the request to see them.)
Or send your own JSON Schema. The data comes back matching the schema, and each value that came from a video has a citation with its JSON path.

**Structured data from your own schema** (`POST /api/v1/extract`)

```bash
curl https://vid2context.com/api/v1/extract \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    "https://www.youtube.com/watch?v=cCPsdFdlshc"
  ],
  "schema": {
    "type": "object",
    "properties": {
      "bestYears": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Model years the video recommends"
      },
      "worstYears": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Model years the video warns against"
      }
    },
    "required": [
      "bestYears",
      "worstYears"
    ]
  }
}'
```

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

```json
{
  "id": "job_X6ow8Guh6nUBFiQzoCk23w",
  "kind": "extract",
  "status": "succeeded",
  "createdAt": "2026-11-14T18:48:07.408Z",
  "updatedAt": "2026-11-14T18:48:12.516Z",
  "progress": {
    "done": 0,
    "total": 1,
    "message": "Extracting"
  },
  "result": {
    "data": {
      "bestYears": [
        "2000-2001",
        "2002-2010",
        "2013-2015"
      ],
      "worstYears": []
    },
    "citations": [
      {
        "videoId": "youtube:cCPsdFdlshc",
        "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
        "startSec": 1037.88,
        "endSec": 1050.66,
        "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=1037s",
        "quote": "If you're looking for something that will absolutely appreciate and gain in value, grab yourself a pre-MBUSA truck, i.e. a 2001 and older G500.",
        "path": "/bestYears/0"
      },
      {
        "videoId": "youtube:cCPsdFdlshc",
        "title": "Best & Worst G-Wagon Years: Reliability, Interiors & Engines Ranked!",
        "startSec": 497.46,
        "endSec": 519.38,
        "url": "https://www.youtube.com/watch?v=cCPsdFdlshc&t=497s",
        "quote": "This model, the G500 2002 through 2010, it's going to be your first-time G-Buyer. Those of you that are on a little bit of a budget and need an entry-level vehicle to get in, this represents the best value on the market, period.",
        "path": "/bestYears/1"
      },
      {
```

(57 more lines; run the request to see them.)
## Next

- [Your own audio and video files](https://vid2context.com/docs/tutorials/your-own-files.md).
- [Answer and brief examples](https://vid2context.com/docs/examples/answers.md), with key moments and generated chapters.
- The [Cited briefs guide](https://vid2context.com/docs/guides/briefs.md) explains the citation check and the map-reduce strategy for many videos.
