API overview

PostReef is a JSON API for turning social video into structured data: submit a public video URL, get back metadata, transcript, comments, downloadable media, plus an optional structured JSON extraction conforming to a schema you provide. The web app runs the same pipeline for hands-on testing; everything it does is one of the calls below.

Base URL

https://postreef.com

All endpoints live under /v1. Requests and responses are JSON (except file downloads, which stream the raw artifact).

Authentication

Create an API key in the dashboard, then send it on every request. Either header works:

x-api-key: vidx_...
# or
Authorization: Bearer vidx_...

Keys act on behalf of your account: extractions they create also show up in the web app for inspection, and credits are drawn from the same balance.

The loop

1. Quote (optional). POST /v1/probe inspects the URL and returns the exact credit price for your chosen inputs. Probing is free.
2. Submit. POST /v1/extractions with the URL, your inputs and (optionally) a JSON Schema. Credits are debited up-front and refunded in full if the extraction fails.
3. Wait. Poll GET /v1/extractions/:id/result (202 while running, 200 when done) or register a webhook and skip polling entirely.
4. Collect. The result carries the structured extraction object plus a summary.files list; download any artifact via GET /v1/extractions/:id/files/:name. Check outcome first: ok means extraction holds your data, while no_match/uncertain mean the video didn't match your schema (extraction is null, verdictReason explains).

OpenAPI spec

The full machine-readable spec lives at /v1/openapi.json (OpenAPI 3.1, no auth required). Import it straight into Postman, Insomnia, or your client generator. The endpoint reference on this site is generated from the same document.

Where to next

Jump into the API quickstart for copy-paste examples, check errors & limits before going to production, or try every endpoint live in the interactive reference.