# Answers, briefs and extraction

Each of these runs on the free LLM chain, so they work with no key, and each checks the model's citations against the transcript.

## Ask a question

**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.)
## Stream the answer

**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].
```
## A cited brief

**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.)
## Structured data from a 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.)
## Structured data from your own schema

**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.)
[Cited answers and briefs](https://vid2context.com/docs/tutorials/cited-answers.md) explains each response.
