Schemas

A schema is a JSON Schema document describing exactly the object you want back. Our AI engine reads your selected inputs and returns one JSON object that conforms to it: no free-form text, no surprises in shape. Use one of our ready-made schemas, or send your own.

Ready-made schemas

We maintain 32 predefined schemas for common video types. Pass a schemaId instead of an inline schema and we'll fill it, with no schema authoring on your side:

POST /v1/extractions
{
  "url": "https://youtube.com/watch?v=...",
  "schemaId": "postreef.predefined.recipe.v1"
}

Each links to its full field reference and raw JSON Schema. Browse them all at /schemas:

• Recipe: Ingredients, steps, times, and yields from any cooking video. postreef.predefined.recipe.v1
• Workout: Exercises, sets, reps, and timed holds from any fitness clip. postreef.predefined.workout.v1
• Product Review: Verdict, specs, pros and cons from a review or unboxing. postreef.predefined.product_review.v1
• Travel Guide: Mappable stops, tips, and costs from a travel vlog. postreef.predefined.travel_itinerary.v1
• How-To: Ordered steps, tools, and gotchas from any tutorial. postreef.predefined.howto.v1
• Property Tour: Price, rooms, and features from a real-estate walkthrough. postreef.predefined.property_tour.v1
• Music Video: Song, artist, mood, and visual style from any music video. postreef.predefined.music_video.v1
• Sports Highlight: Teams, score, and key moments from a match recap. postreef.predefined.sports_highlight.v1
• Gaming Clip: Game, players, and standout plays from a gaming or esports clip. postreef.predefined.gaming_clip.v1
• Outfit: Every piece, brand, and the styling from a fashion clip. postreef.predefined.fashion_outfit.v1
• Podcast Episode: Hosts, guests, topic-by-topic breakdown, takeaways, and quotes from any podcast. postreef.predefined.podcast.v1
• Book Summary: Core thesis, key lessons, named concepts, and the verdict from a book summary. postreef.predefined.book_summary.v1
• News Report: Headline, the five Ws, key facts, people, organizations, and cited sources. postreef.predefined.news.v1
• Educational Explainer: Key terms, ordered main points, examples, and takeaways from any explainer. postreef.predefined.explainer.v1
• Interview: Interviewer and guests, Q&A exchanges, revelations, and quotes. postreef.predefined.interview.v1
• Q&A / FAQ: Every question paired with a clear self-contained answer, plus takeaways. postreef.predefined.qanda.v1
• Car Review: The vehicle, its specs, how it drives, and the verdict from a car review. postreef.predefined.car_review.v1
• Coding Tutorial: What's built, the stack, ordered steps with code, concepts, and gotchas. postreef.predefined.coding.v1
• Beauty Tutorial: Products, ordered steps, techniques, and warnings from a beauty tutorial. postreef.predefined.beauty.v1
• Art Tutorial: Subject, medium, materials, ordered steps, and techniques from an art tutorial. postreef.predefined.art_tutorial.v1
• Music Lesson: Instrument, chords and scales taught, ordered steps, and practice guidance. postreef.predefined.music_lesson.v1
• Language Lesson: Vocabulary and phrases with translations, grammar points, and study tips. postreef.predefined.language.v1
• Gardening Guide: Plant-care steps, growing conditions, pests, and pro tips from a gardening video. postreef.predefined.gardening.v1
• Pet Training Guide: Target behavior, method, ordered steps, and troubleshooting from a training video. postreef.predefined.pet_training.v1
• Science Experiment: Procedure, concepts, observation, explanation, and safety from a science demo. postreef.predefined.science.v1
• History Explainer: Timeline of key events, figures, causes, and consequences from a history video. postreef.predefined.history.v1
• Conference Talk: Thesis, key points, takeaways, quotes, and predictions from any keynote or talk. postreef.predefined.talk.v1
• Personal Finance: Actionable money and investing advice: tips, action steps, and rules of thumb. postreef.predefined.finance.v1
• Cocktail Recipe: Ingredients, build steps, technique, glassware, and garnish from a drink video. postreef.predefined.cocktail.v1
• Restaurant Review: Per-dish verdicts and sentiment, ratings, highlights, and criticisms. postreef.predefined.restaurant.v1
• Guided Meditation: Ordered phases, breathing patterns, affirmations, and visualizations. postreef.predefined.meditation.v1
• Motivational Speech: Key points, memorable quotes, stories, call to action, and takeaways. postreef.predefined.motivation.v1

Auto-detect: no schema at all

Don't know the shape ahead of time? Pass "schemaId": "auto" and skip picking a schema entirely — the AI extracts whatever structured information is actually in the content (a title, a summary, and a flat list of concrete fields it found) into one object. It's priced and billed exactly like any other AI run with the same inputs.

{ "url": "https://www.youtube.com/watch?v=...", "schemaId": "auto" }

Once the run finishes, we compile its actual output into a JSON Schema and save it to your library automatically, named after the video and marked as auto-generated. Reuse or edit that schema on your next run instead of guessing at the shape up front.

Custom schemas

Need a different shape? Send any JSON Schema inline as schema and the model fills it.

Describe it and we'll write it

On the extract form, pick Custom schema and describe what you want in plain English — "the ingredients with quantities, the steps in order, and how long it takes". We draft a JSON Schema from that description and drop it in the editor, where it stays yours to edit before you run anything. It's free, and it's a starting point, not a black box: read the field descriptions, cut what you don't need, and mark as required only what a post must have.

The drafting endpoint is web-only for now — the API takes schema or schemaId.

Save it and reuse it

Pasting the same JSON Schema into every request gets old. Sign in and save it once at /schemas: the same page that lists the ready-made schemas also holds your own, with search and filters across both. Saving is free — you can keep up to 100 schemas — and you can author them three ways on the same screen: a visual field builder, the plain-English AI draft, or raw JSON. All three edit the same schema, so you can start from a description and finish in the builder.

A saved schema gets an id, and that id works as a schemaId on the API exactly like a predefined one:

{ "url": "https://www.youtube.com/watch?v=…", "schemaId": "<your saved schema id>" }

Only you can read or use your own schemas. Editing one changes what future runs return — and because the cache key is computed over the resolved schema, an edit invalidates its own cached results rather than serving you stale ones.

Manage them over HTTP with your session (these are web endpoints, not part of the versioned /v1 API):

Every schema is checked against the rules below before it's stored, so a schema that saved successfully is a schema that will run.

The basics

Your schema must be a top-level object: a "type": "object" with a properties map. Each property gets a type (string, number, integer, boolean, array, object) and ideally a description. Descriptions are instructions to the AI, and they're the single biggest lever on extraction quality. List the fields that must always be present in required; arrays declare their element shape in items; fixed sets of values use enum.

Rules for a well-behaved schema

• Optional fields: leave them out of required. Don't use type unions like "type": ["string", "null"], which aren't supported. A field that isn't required is simply omitted when the video has nothing for it.
• Enums are strings only. Every value in an enum must be a string, paired with a single "type": "string". No numbers, no null inside the enum list.
• Keep it flat-ish. One or two levels of nesting is fine; deeply nested structures degrade extraction quality. Prefer descriptive field names (price_mentioned, not p), because the AI reads them.
• Advanced keywords don't steer, and aren't enforced. pattern, minItems, uniqueItems and friends are stripped before the model sees them and are not checked afterwards, so treat them as documentation, not guarantees. This is deliberate: enforcing a minimum count would just pressure the model to invent data to hit it. A clear description is the real lever, and if the video genuinely has nothing to extract you'll get outcome: "no_match" on the result (more) rather than a padded object.
• Want a specific output language? Say so in the field descriptions ("in English"). The AI understands the video's original language either way.

Worked example: a product-review schema

Say you're extracting structured reviews from tech videos. A schema like this:

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": "string",
      "description": "Exact name of the product being reviewed"
    },
    "brand": {
      "type": "string",
      "description": "Brand or manufacturer, if mentioned"
    },
    "verdict": {
      "type": "string",
      "enum": ["recommended", "mixed", "not_recommended"],
      "description": "The reviewer's overall verdict"
    },
    "rating_out_of_10": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10,
      "description": "Score implied or stated by the reviewer"
    },
    "pros": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Things the reviewer liked, one short phrase each"
    },
    "cons": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Things the reviewer disliked"
    },
    "price_mentioned": {
      "type": "string",
      "description": "Price as stated in the video, with currency"
    }
  },
  "required": ["product_name", "verdict", "pros", "cons"]
}

What comes back

Running it against a review video returns one object in exactly that shape. Optional fields (brand, rating_out_of_10, price_mentioned) appear only when the video actually contains them:

{
  "product_name": "AeroPress Clear",
  "brand": "AeroPress",
  "verdict": "recommended",
  "rating_out_of_10": 8,
  "pros": [
    "Brews in under two minutes",
    "Easy to clean",
    "Durable Tritan plastic"
  ],
  "cons": [
    "More expensive than the original",
    "Stains over time"
  ],
  "price_mentioned": "$49.95"
}

Tip: start with transcript + comments as inputs. It's the cheapest combination and covers most schemas. Add audio or full video analysis when the answer is only on screen or in the delivery.

Pairing a prompt with your schema

A schema and its prompt work as a pair: the schema fixes the output shape, and an optional prompt tells the model how to read the video into that shape: source priority (on-screen text vs. spoken vs. description), what to omit rather than guess, and the pitfalls specific to your content. Field descriptions remain the biggest quality lever, but a prompt captures the cross-field judgment calls a per-field description can't.

Every ready-made schema ships with a tuned prompt; pass your own prompt to override it, or to pair one with an inline schema:

POST /v1/extractions
{
  "url": "https://youtube.com/watch?v=...",
  "schema": { "type": "object", "properties": { "dish": { "type": "string" } }, "required": ["dish"] },
  "prompt": "Read the recipe from what the creator actually adds, not alternatives they only mention. Prefer on-screen ingredient cards over spoken asides. Never invent quantities."
}

The prompt is capped at 20KB and is part of the cache key, so editing it triggers a fresh run instead of reusing a cached result. It's ignored on download-only runs (no schema).