Skip to main content
Every API call takes a schema parameter that describes the fields you want. You can define schemas three ways: raw JSON, Pydantic models (Python), or Zod objects (TypeScript).

Typed JSON schema

Each field is an object with a type and description:

Supported types

Enums

Constrain a field to specific allowed values:

Required fields

Mark fields as required — the response will set success: false if any required field is missing:

Arrays

Extract lists of items with a defined shape:

Nested objects

Pydantic models (Python)

Pass a Pydantic BaseModel class directly as the schema. The SDK converts it automatically — including nested models, Optional fields, Literal enums, and Field(description=...).
This generates the equivalent typed JSON schema behind the scenes. Every Pydantic feature maps to a schema type:

Zod schemas (TypeScript)

Use fromZod() to convert a Zod object schema. Supports z.string(), z.number(), z.boolean(), z.array(), z.object(), z.enum(), and .describe().

Type guarantees

When you define a field as "type": "number", the API guarantees the returned value is a JSON number — not a string like "$1,234.56". The AI parses, cleans, and type-coerces values automatically. If a field can’t be found in the document, it returns null (not an empty string or zero).

Limits

  • Maximum 10 top-level fields per request (excluding _-prefixed meta keys)
  • No limit on nested properties within arrays or objects
  • Descriptions improve accuracy — always include them