Skip to main content
POST
/
v1
/
schemas
/
generate
from retab import Retab
client = Retab()

response = client.schemas.generate(
    documents=["passport.jpeg"],
    model="retab-small",      # or any model your plan supports
    image_resolution_dpi=96,
)

print("Generated JSON Schema:")
print(response)

{
  "title": "Invoice Document Schema",
  "description": "A schema for storing structured data extracted from invoice documents, including parties, line items, and payment details.",
  "type": "object",
  "X-SchemaType": "generic",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Unique identifier for the invoice."
    },
    "date_of_issue": {
      "type": "string",
      "description": "Date when the invoice was issued."
    },
    "date_due": {
      "type": "string",
      "description": "Date when the invoice payment is due."
    },
    "seller": {
      "$ref": "#/$defs/party"
    },
    "bill_to": {
      "$ref": "#/$defs/party"
    },
    "ship_to": {
      "$ref": "#/$defs/party"
    },
    "line_items": {
      "type": "array",
      "description": "List of items or services billed on the invoice.",
      "items": {
        "$ref": "#/$defs/line_item"
      }
    },
    "subtotal": {
      "type": "number",
      "description": "Subtotal amount before taxes or discounts."
    },
    "total": {
      "type": "number",
      "description": "Total amount due."
    },
    "amount_due": {
      "type": "number",
      "description": "Amount due for payment."
    },
    "currency": {
      "type": "string",
      "description": "Currency code (e.g., USD, EUR)."
    }
  },
  "required": [
    "invoice_number",
    "date_of_issue",
    "date_due",
    "seller",
    "bill_to",
    "ship_to",
    "line_items",
    "subtotal",
    "total",
    "amount_due",
    "currency"
  ],
  "additionalProperties": false,
  "$defs": {
    "party": {
      "type": "object",
      "description": "Information about a party involved in the invoice (seller, buyer, or recipient).",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the party."
        },
        "address": {
          "type": "string",
          "description": "Full address of the party."
        },
        "email": {
          "type": "string",
          "description": "Email address of the party."
        },
        "tax_id": {
          "type": "string",
          "description": "Tax identification number or EIN."
        }
      },
      "required": ["name", "address", "email", "tax_id"],
      "additionalProperties": false
    },
    "line_item": {
      "type": "object",
      "description": "A single item or service listed on the invoice.",
      "properties": {
        "description": {
          "type": "string",
          "description": "Description of the item or service."
        },
        "service_period": {
          "type": "string",
          "description": "Service period or date range for the item."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity of the item or service."
        },
        "unit_price": {
          "type": "number",
          "description": "Unit price of the item or service."
        },
        "amount": {
          "type": "number",
          "description": "Total amount for this line item."
        }
      },
      "required": [
        "description",
        "service_period",
        "quantity",
        "unit_price",
        "amount"
      ],
      "additionalProperties": false
    }
  }
}

from retab import Retab
client = Retab()

response = client.schemas.generate(
    documents=["passport.jpeg"],
    model="retab-small",      # or any model your plan supports
    image_resolution_dpi=96,
)

print("Generated JSON Schema:")
print(response)

{
  "title": "Invoice Document Schema",
  "description": "A schema for storing structured data extracted from invoice documents, including parties, line items, and payment details.",
  "type": "object",
  "X-SchemaType": "generic",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Unique identifier for the invoice."
    },
    "date_of_issue": {
      "type": "string",
      "description": "Date when the invoice was issued."
    },
    "date_due": {
      "type": "string",
      "description": "Date when the invoice payment is due."
    },
    "seller": {
      "$ref": "#/$defs/party"
    },
    "bill_to": {
      "$ref": "#/$defs/party"
    },
    "ship_to": {
      "$ref": "#/$defs/party"
    },
    "line_items": {
      "type": "array",
      "description": "List of items or services billed on the invoice.",
      "items": {
        "$ref": "#/$defs/line_item"
      }
    },
    "subtotal": {
      "type": "number",
      "description": "Subtotal amount before taxes or discounts."
    },
    "total": {
      "type": "number",
      "description": "Total amount due."
    },
    "amount_due": {
      "type": "number",
      "description": "Amount due for payment."
    },
    "currency": {
      "type": "string",
      "description": "Currency code (e.g., USD, EUR)."
    }
  },
  "required": [
    "invoice_number",
    "date_of_issue",
    "date_due",
    "seller",
    "bill_to",
    "ship_to",
    "line_items",
    "subtotal",
    "total",
    "amount_due",
    "currency"
  ],
  "additionalProperties": false,
  "$defs": {
    "party": {
      "type": "object",
      "description": "Information about a party involved in the invoice (seller, buyer, or recipient).",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the party."
        },
        "address": {
          "type": "string",
          "description": "Full address of the party."
        },
        "email": {
          "type": "string",
          "description": "Email address of the party."
        },
        "tax_id": {
          "type": "string",
          "description": "Tax identification number or EIN."
        }
      },
      "required": ["name", "address", "email", "tax_id"],
      "additionalProperties": false
    },
    "line_item": {
      "type": "object",
      "description": "A single item or service listed on the invoice.",
      "properties": {
        "description": {
          "type": "string",
          "description": "Description of the item or service."
        },
        "service_period": {
          "type": "string",
          "description": "Service period or date range for the item."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity of the item or service."
        },
        "unit_price": {
          "type": "number",
          "description": "Unit price of the item or service."
        },
        "amount": {
          "type": "number",
          "description": "Total amount for this line item."
        }
      },
      "required": [
        "description",
        "service_period",
        "quantity",
        "unit_price",
        "amount"
      ],
      "additionalProperties": false
    }
  }
}

Authorizations

​
Api-Key
string
header
required

Headers

​
Idempotency-Key
string | null

Body

application/json

Body to generate a JSON schema from example documents, optionally steered by instructions.

​
documents
MIMEData · object[]
required
​
model
string
default:retab-small
​
instructions
string | null
​
image_resolution_dpi
integer
default:192

Resolution of the image sent to the LLM

Required range: 96 <= x <= 300
​
background
boolean
default:false

If true, run asynchronously: returns immediately with status 'queued'. Poll GET /v1/schemas/generate/{schema_generation_id} until status is terminal.

Response

Successful Response

Public generated schema response.

​
id
string
required

Unique identifier of the schema generation.

​
object
string
default:schema
​
created_at
string<date-time> | null
​
json_schema
Json Schema · object
​
strict
boolean
default:true
​
status
enum<string>
default:pending

Lifecycle status. The synchronous path returns 'completed'. Background runs progress pending -> queued -> in_progress -> completed | failed | cancelled.

Available options:
pending,
queued,
in_progress,
completed,
failed,
cancelled
​
error
PrimitiveError · object

Error details when a background run fails; null otherwise. Always present so consumers can read it without an existence check.