> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema

> Describe the fields you want as a JSON Schema, or send a Pydantic or zod model as it is. Each value is checked against the page and left out if it is not there.

`schema` is a JSON Schema that names the fields you want. The output of Pydantic's `model_json_schema()` and zod's `toJSONSchema()` works as it is, so one model can describe the request and read the answer.

## Send a model

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request fills the fields of a model from one page. The cURL tab shows the JSON Schema that zod writes for the model in the TypeScript tab, and Pydantic writes an equivalent one. `showSources` asks for the page behind each value. See [Results](https://docs.stophy.dev/extract/results.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/extract \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://bun.com/docs/runtime/sqlite"],
    "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "module": { "type": "string" },
        "queryMethods": { "type": "array", "items": { "type": "string" } },
        "transactionModes": {
          "type": "array",
          "items": { "type": "string", "enum": ["deferred", "immediate", "exclusive"] }
        },
        "pricePerMonth": { "type": ["number", "null"] }
      },
      "required": ["module", "queryMethods", "transactionModes", "pricePerMonth"],
      "additionalProperties": false
    },
    "showSources": true
  }'
```

```typescript TypeScript theme={null}
import { z } from "zod";

const Sqlite = z.object({
  module: z.string(),
  queryMethods: z.array(z.string()),
  transactionModes: z.array(z.enum(["deferred", "immediate", "exclusive"])),
  pricePerMonth: z.number().nullable(),
});

const headers = {
  Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  "Content-Type": "application/json",
};
const started = await fetch("https://api.stophy.dev/v1/extract", {
  method: "POST",
  headers,
  body: JSON.stringify({
    urls: ["https://bun.com/docs/runtime/sqlite"],
    schema: z.toJSONSchema(Sqlite),
    showSources: true,
  }),
}).then((response) => response.json());
const result = await fetch(`https://api.stophy.dev/v1/extract/${started.id}`, { headers }).then(
  (response) => response.json(),
);
console.log(Sqlite.partial().parse(result.data));
```

```python Python theme={null}
import os
from typing import Literal

import requests
from pydantic import BaseModel


class Sqlite(BaseModel):
    module: str | None = None
    queryMethods: list[str] | None = None
    transactionModes: list[Literal["deferred", "immediate", "exclusive"]] | None = None
    pricePerMonth: float | None = None


headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}
started = requests.post(
    "https://api.stophy.dev/v1/extract",
    headers=headers,
    json={
        "urls": ["https://bun.com/docs/runtime/sqlite"],
        "schema": Sqlite.model_json_schema(),
        "showSources": True,
    },
).json()
result = requests.get(f"https://api.stophy.dev/v1/extract/{started['id']}", headers=headers).json()
print(Sqlite.model_validate(result["data"]))
```

A field the page does not state is left out of `data`. That is why the TypeScript tab reads the answer with `partial()` and the Python model gives every field a default.

## Read the response

`GET /v1/extract/{id}` returns the fields you asked for, a `confidence` for each, and `sources` because the request sent `showSources`.

```json theme={null}
{
  "success": true,
  "status": "completed",
  "data": {
    "module": "bun:sqlite",
    "queryMethods": ["all", "get", "run", "values", "iterate"],
    "transactionModes": ["deferred", "immediate", "exclusive"]
  },
  "confidence": {
    "module": 0.9299,
    "queryMethods": 0.7584,
    "transactionModes": 0.939
  },
  "urls": ["https://bun.com/docs/runtime/sqlite"],
  "sources": {
    "module": ["https://bun.com/docs/runtime/sqlite"],
    "queryMethods": ["https://bun.com/docs/runtime/sqlite"],
    "transactionModes": ["https://bun.com/docs/runtime/sqlite"]
  },
  "costUsd": 0.005,
  "expiresAt": "2026-11-18T18:09:44.373Z"
}
```

`pricePerMonth` is not in `data`, `confidence` or `sources`: the page does not state it. Each value that is returned is checked against the page text. A value that is not found there is dropped, and so is a value that does not fit its schema, such as a word that is not in an `enum`.

## What a schema can say

| Keyword | Use |
| - | - |
| `properties` | The fields to fill. Each top-level property is one field, and its key can be any name. |
| `type`, `items` | Strings, numbers, booleans, objects and lists. Nested objects and lists are filled and checked value by value. |
| `enum`, `const` | Only these values are kept. |
| `anyOf`, `oneOf` | A value that fits one of several shapes. |
| `["number", "null"]` | A nullable type. |
| `$ref` with `$defs` | A shared shape. The schema itself can be a `$ref` that points at an object. |
| `description` | Tells the model what the field means. Write one for a field whose name alone is unclear. |
| `required` | Read, but a field the page does not state is still left out. |

Both drafts work: draft-07 and 2020-12.

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `schema` | `object` | none | The fields to fill, as a JSON Schema with `properties`. Up to 100 top-level fields, 32 KB and 32 levels of nesting. |
| `prompt` | `string` | none | What to pull, in plain words. With a `schema` it adds to the schema. |
| `systemPrompt` | `string` | none | Standing instructions, such as units or how to write dates. |

Send a `schema`, a `prompt`, or both. With a `prompt` and no `schema`, the model names up to 20 fields in camelCase.

## Limits and errors

* A call with neither a `schema` nor a `prompt` returns `400 invalidRequest` with `Send a schema, a prompt, or both`.
* A schema with no `properties`, and no `$ref` to an object that has them, returns `400 invalidRequest` with `Send a JSON Schema object with properties, or one whose $ref points at such an object`.
* More than 100 top-level fields returns `400 invalidRequest` with `Ask for at most 100 fields`. A schema over 32 KB returns `Keep the schema under 32 KB`, and one more than 32 levels deep returns `Nest the schema at most 32 levels deep`.
* A schema that is not valid JSON Schema returns `400 invalidRequest` with `The schema is not valid JSON Schema` and the reason.
* A call that finds none of your fields costs nothing.

## Related

* [Extract overview](https://docs.stophy.dev/extract/overview) lists every request field.
* [Results](https://docs.stophy.dev/extract/results.md) reads the answer back, with sources, timeouts and a webhook.
* [JSON](https://docs.stophy.dev/scrape/json.md) fills the same kind of schema from one page inside a scrape.
* [Agent](https://docs.stophy.dev/agent/overview) fills a schema from pages it finds itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.