API reference

Submit an extraction

Starts an extraction for a public URL: a video, a photo post/carousel, or an ordinary article/webpage (webpage runs are priced flat and read the page text and images; photo posts/carousels are priced flat and per-slide — their reported "duration" is a background track, never billed). 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; the debit is never exceeded. Videos longer than 60 minutes are rejected before any debit. If an identical extraction (same URL, schema and inputs) completed within the last 30 days, 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": "postreef.predefined.recipe.v1",
  "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": "postreef.predefined.recipe.v1",
  "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), `artifacts` (the same files as ready-to-fetch URLs), 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"
    ]
  },
  "artifacts": {
    "video": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/video.mp4",
    "transcript": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/transcript.txt",
    "comments": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/comments.json",
    "images": [],
    "files": {
      "video.mp4": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/video.mp4",
      "transcript.txt": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/transcript.txt",
      "comments.json": "https://postreef.com/v1/extractions/run_8f3a2b1c/files/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` (the page text, for webpage runs), `comments.json`, `thumbnail.jpg`, `description.txt`, subtitle files, or the numbered `image.NN.jpg` slides of a photo post or carousel. The available names are listed in the result's `summary.files`, and the result's `artifacts` object gives you the full URL directly. Accepts either an API key or, if you're signed in to the web app, your browser session — so an `artifacts` URL also opens directly in a tab.

Parameters

Responses

Probe a URL and quote the price

Inspects a URL without starting an extraction: returns the title, duration, whether subtitles/comments exist, and the exact credit price for the run you intend to submit (a URL that resolves to an article/webpage is quoted at the flat webpage price, with `durationSec: null`). This is the canonical quote: send the same body you will submit (a schema when you want an AI extraction, `parts` when you want a download) and `POST /v1/extractions` 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",
  "schemaId": "postreef.predefined.recipe.v1",
  "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": {
    "mode": "ai",
    "credits": 186,
    "usd": 0.0186,
    "baseUsd": 0.005,
    "downloadUsd": 0.003,
    "downloadBreakdown": {
      "transcript": 0.001,
      "comments": 0.002
    },
    "breakdown": {
      "text": 0.0106,
      "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