Schema-driven structured extraction

Fetches url and extracts structured JSON conforming to the supplied JSON Schema (draft 2020-12) using an LLM. Fast-path only — slow-path rendering options (wait_until=networkidle, delay_ms, wait_for_selector) cause a 400 unsupported_option.

Dual-axis billing: a fixed per-request credit charge plus the underlying page's bandwidth, billed at its upstream wire bytes with no endpoint factor (a 100 KiB estimate is pre-charged, then reconciled). The bandwidth is still billed when the scrape succeeds but extraction later fails; both axes are refunded only when the scrape itself never runs.

Authorization

AuthorizationRequiredBearer <token>

API key. Manage keys from the dashboard at app.bytekit.com.

In: header

Request Body

application/jsonRequired

urlRequiredstring

Target page URL (HTTP/HTTPS, SSRF-blocked, fast-path only).

Format: "uri"

schemaRequiredobject

JSON Schema (draft 2020-12) describing the desired output. Serialized size ≤ 50 KB, nesting depth ≤ 8, must compile under Ajv, and must be normalizable into Groq's strict-mode subset: root type: object, and only an allowlist of keywords at any depth — type, properties, required, additionalProperties, items, enum, $defs, $ref, description, title and default ($ref limited to #/$defs). Every other keyword, such as pattern, format, minimum, maxLength, const, oneOf, anyOf, allOf or if/then/else, returns 422 schema_incompatible.

promptstring

Optional natural-language extraction hint.

Maximum length: 2000

modelstring

Extraction model. An out-of-list value returns 400 unsupported_model (not a Zod 422).

Default: "openai/gpt-oss-20b"Value in: "openai/gpt-oss-20b" | "openai/gpt-oss-120b"

wait_for_selectorstring | null

Default: null

wait_untilstring

Default: "load"Value in: "load" | "domcontentloaded" | "networkidle"

delay_msinteger

Default: 0Minimum: 0Maximum: 10000

countrystring | null

Two-letter country code, upper-cased. null is coerced to US.

Default: "US"

languagestring | null

Accepted and forwarded to the extraction service, which does not read it: it currently has no effect.

Default: null

curl -X POST https://api.bytekit.com/v1/schema \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://stripe.com/pricing",
  "schema": {
    "type": "object",
    "properties": {
      "plan_name": {
        "type": "string"
      },
      "monthly_price_usd": {
        "type": "number"
      }
    }
  },
  "prompt": "Extract the cheapest paid plan.",
  "model": "openai/gpt-oss-20b"
}'

Extraction completed (success or graceful extract failure).

{
  "data": {},
  "model": "string",
  "validated": true,
  "metrics": {
    "scrape_ms": 0,
    "llm_total_ms": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "retries": 0,
    "total_ms": 0
  },
  "scrape": {
    "url": "http://example.com",
    "status_code": 0,
    "content_length": 0,
    "truncated": true
  },
  "warnings": [
    "string"
  ]
}

Schema-driven structured extraction

Authorization

Request Body

Response