API reference

Submit an extraction

Starts an extraction for a public video URL. Credits are debited up-front (a flat base fee plus download rates for the requested artifacts, plus per-second AI rates when a schema is set; use `POST /v1/probe` for the exact quote first) and refunded in full if the extraction fails. When the duration can't be determined up-front, a worst-case duration of 300s is debited and the difference is refunded on completion. If an identical extraction (same URL, schema and inputs) completed recently, the result is reused: the response has `cached: true` semantics on subsequent reads and `creditsDebited: 0`. Pass `force: true` to skip the cache and re-run. Rate limit: 6 requests per minute. At most 2 extractions run per account at once. Submissions past that limit are accepted with status `queued` (credits debited up-front) and dispatched automatically when a slot frees.

Parameters

Request body

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "inputs": [
    "transcript",
    "comments"
  ],
  "schemaId": "Recipe",
  "webhookUrl": "https://example.com/hooks/postreef"
}

Response fields

Responses

{
  "id": "run_8f3a2b1c",
  "status": "pending",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "creditsDebited": 127,
  "createdAt": "2026-06-11T10:15:00.000Z"
}

List extractions

Lists your extractions, newest first, with cursor pagination. Pass `next_cursor` from a previous page as `cursor` to fetch the next page.

Parameters

Response fields

Responses

{
  "data": [
    {
      "id": "run_8f3a2b1c",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "status": "complete",
      "createdAt": "2026-06-11T10:15:00.000Z",
      "completedAt": "2026-06-11T10:16:42.000Z",
      "creditsDebited": 127,
      "cached": false,
      "outcome": "ok"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Submit an extraction (alias)

Exact alias of `POST /v1/extractions`, with the same request, responses, rate limit and Idempotency-Key support.

Request body

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "inputs": [
    "transcript",
    "comments"
  ],
  "schemaId": "Recipe",
  "webhookUrl": "https://example.com/hooks/postreef"
}

Response fields

Responses

Get an extraction

Returns the current state of one extraction, including a coarse `phase` (`queued`, `processing`, `done`, `failed`). Poll this (or `/result`) until the status is terminal, or skip polling entirely with a webhook.

Parameters

Response fields

Responses

{
  "id": "run_8f3a2b1c",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "status": "complete",
  "createdAt": "2026-06-11T10:15:00.000Z",
  "completedAt": "2026-06-11T10:16:42.000Z",
  "creditsDebited": 127,
  "cached": false,
  "outcome": "ok",
  "phase": "done"
}

Get an extraction's result

Returns the final result. While the extraction is still queued or processing, responds **202** with `{ "status": "queued" | "processing" }` and keep polling. Once complete, responds 200 with the summary (metadata + available file names) and, when an AI schema was supplied, the structured `extraction` object conforming to it. A failed extraction responds 200 with `status: "failed"` and a human-readable `error`.

Parameters

Responses

{
  "id": "run_8f3a2b1c",
  "status": "complete",
  "summary": {
    "title": "Weeknight pasta in 15 minutes",
    "uploader": "@kitchen",
    "durationSeconds": 212,
    "files": [
      "video.mp4",
      "transcript.txt",
      "comments.json"
    ]
  },
  "extraction": {
    "name": "Weeknight pasta",
    "servings": 2
  }
}

{
  "status": "processing"
}

Download an extraction artifact

Streams one artifact produced by a completed extraction: `video.mp4`, `audio.m4a`, `transcript.txt`, `comments.json`, `thumbnail.jpg`, `description.txt` or subtitle files. The available names are listed in the result's `summary.files`.

Parameters

Responses

Probe a URL and quote the price

Inspects a video URL without starting an extraction: returns the title, duration, whether subtitles/comments exist, and the exact credit price for the inputs you intend to request. This is the canonical quote: submitting the same URL with the same inputs debits exactly this amount (or the worst-case ceiling when duration is unknown). Rate limit: 10 requests per minute. Probing is free.

Request body

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "inputs": [
    "transcript",
    "comments"
  ]
}

Response fields

Responses

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "durationSec": 212,
  "title": "Weeknight pasta in 15 minutes",
  "hasSubtitles": true,
  "hasComments": true,
  "price": {
    "credits": 636,
    "usd": 0.0636,
    "breakdown": {
      "text": 0.0636,
      "audio": 0,
      "video": 0
    }
  }
}

This document

Returns this OpenAPI 3.1 document. Public, no authentication required. Import it into Postman, Insomnia, or your codegen of choice.

Responses