> ## 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.

# JSON, product and menu

> Get named fields from a page with a JSON Schema, a prompt, CSS rules or attribute selectors, or read a product page or a menu in a fixed shape.

Use `json` when your code reads fields rather than text. A `schema` fixes the names and types. A `prompt` lets the model choose names, so they can differ between calls. `schema` and `prompt` need an API key.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bun.com/docs/runtime/bunfig",
    "formats": [{
      "type": "json",
      "schema": {
        "type": "object",
        "properties": {
          "configFile": { "type": "string" },
          "globalPaths": { "type": "array", "items": { "type": "string" } },
          "hasTelemetryOption": { "type": "boolean" }
        }
      }
    }]
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "json": {
      "configFile": "bunfig.toml",
      "globalPaths": ["$HOME/.bunfig.toml", "$XDG_CONFIG_HOME/.bunfig.toml"],
      "hasTelemetryOption": true
    }
  }
}
```

A field the page does not state comes back `null`, and each value is checked against the page text.

## Fields of the json format

| Field | Effect |
| - | - |
| `type` | `"json"`. Required. |
| `schema` | A JSON Schema (draft-07 or 2020-12) with `properties`. Up to 100 top-level fields and 32 KB. Pydantic's `model_json_schema()` and zod's `toJSONSchema()` output work as they are. `enum`, `const`, `anyOf`, `oneOf`, nullable types, `$ref` with `$defs`, `required` and `description` are read. |
| `prompt` | What to pull, in plain words, 1 to 10,000 characters. The model returns up to 20 fields. |
| `rules` | CSS rules, no model. Each field is a selector such as `"h1"` or `"a@href"`. Up to 100 fields, 5 levels deep. Not with `schema`, `prompt` or `parser`. |
| `parser`, `options` | A site's own data, and extra inputs such as `{ "page": 2 }`. See [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers). |

* The model reads the first 50,000 characters of the Markdown.
* A `json` format with none of `schema`, `prompt`, `rules` or `parser` returns `400 invalidRequest`. So does `rules` with `schema`, `prompt` or `parser`.
* When the page states none of your fields, the model fee is not charged.

## Rules and attributes

`"formats": [{ "type": "json", "rules": { "title": "h1", "links": { "selector": "a", "type": "list", "output": "@href" } } }]` reads the page with CSS and no model. A missing item is `null`, an unmatched list is `[]`, and relative links become absolute. It works without a key.

`{ "type": "attributes", "selectors": [{ "selector": "a", "attribute": "href" }] }` reads attribute values. Send 1 to 50 entries. `data.attributes` has one entry per selector with its `selector`, `attribute` and the `values` it found.

## Product and menu

`"formats": ["product"]` reads a product page. `data.product` has `title`, `brand`, `category`, `url`, `description` and `variants`. Price, sale, stock and images belong to a variant, and a product with no options has one.

| `variants[]` field | Holds |
| - | - |
| `id`, `sku`, `title`, `values` | Identifiers, the name, and option values such as `color: Black`. |
| `price` | `amount`, `currency` (ISO 4217) and `formatted`. |
| `sale` | `originalPrice`, only when discounted. |
| `availability` | `inStock` and `text`. |
| `images` | Each with `url` and `alt` when the page has it. |

`"formats": ["menu"]` reads a restaurant menu. `data.menu` has `isMenu`, `confidence` (0 to 1), `merchant` (`name`, `type`), `currency` and `sections`. Each section has `name`, `description` and `items`. An item has `name`, `description`, `price`, `availability`, `dietary`, `calories`, `images`, `url` and `optionGroups`, each group a `name` with `options` that have a `name` and a `price`.

A field the page does not state is left out. When the page is not a product page, `product` is left out and `data.warning` says why. The same holds for `menu`. The model reads the first 50,000 characters of the Markdown.

`schema`, `prompt`, `product` and `menu` add a fee when they return something. `rules`, `parser` and `attributes` add none. See [Pricing](https://docs.stophy.dev/account/pricing.md).


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