Generate - Retab Docs

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)

import { Retab } from "@retab/node";
import { config } from "dotenv";

config();

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const result = await client.schemas.generate(["passport.jpeg"], "retab-small", undefined, 96);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	document, err := retab.InferMIMEData("passport.jpeg")
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Schemas.Generate(ctx, &retab.SchemasGenerateParams{
		Documents: []any{document},
		Model:     ptr("retab-small"),
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Generated JSON Schema:")
	fmt.Println(*result)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

response = client.schemas.generate(
  documents: ['passport.jpeg'],
  model: 'retab-small',
  image_resolution_dpi: 96,
)

puts 'Generated JSON Schema:'
puts response

use retab::resources::schemas::GenerateParams;
use retab::Retab;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let mut params = GenerateParams::new(vec![PathBuf::from("passport.jpeg")]);
    params.body.model = Some("retab-small".into());
    params.body.image_resolution_dpi = Some(96);

    let response = client.schemas().generate(params).await?;

    println!("Generated JSON Schema:");
    println!("{:?}", response);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->schemas()->generate(
    documents: 'invoice.pdf',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Schemas.GenerateAsync(new SchemasGenerateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.schemas().generate(null, "retab-1.5", "Extract the invoice fields", 10L, null);
    System.out.println(result);
  }
}

curl https://api.retab.com/v1/schemas/generate \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "filename": "passport.jpeg",
        "url": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..."
      }
    ],
    "model": "retab-small",
    "image_resolution_dpi": 96
  }'

{
  "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
    }
  }
}

POST

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)

import { Retab } from "@retab/node";
import { config } from "dotenv";

config();

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const result = await client.schemas.generate(["passport.jpeg"], "retab-small", undefined, 96);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	document, err := retab.InferMIMEData("passport.jpeg")
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Schemas.Generate(ctx, &retab.SchemasGenerateParams{
		Documents: []any{document},
		Model:     ptr("retab-small"),
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Generated JSON Schema:")
	fmt.Println(*result)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

response = client.schemas.generate(
  documents: ['passport.jpeg'],
  model: 'retab-small',
  image_resolution_dpi: 96,
)

puts 'Generated JSON Schema:'
puts response

use retab::resources::schemas::GenerateParams;
use retab::Retab;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let mut params = GenerateParams::new(vec![PathBuf::from("passport.jpeg")]);
    params.body.model = Some("retab-small".into());
    params.body.image_resolution_dpi = Some(96);

    let response = client.schemas().generate(params).await?;

    println!("Generated JSON Schema:");
    println!("{:?}", response);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->schemas()->generate(
    documents: 'invoice.pdf',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Schemas.GenerateAsync(new SchemasGenerateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.schemas().generate(null, "retab-1.5", "Extract the invoice fields", 10L, null);
    System.out.println(result);
  }
}

curl https://api.retab.com/v1/schemas/generate \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "filename": "passport.jpeg",
        "url": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..."
      }
    ],
    "model": "retab-small",
    "image_resolution_dpi": 96
  }'

{
  "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)

import { Retab } from "@retab/node";
import { config } from "dotenv";

config();

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const result = await client.schemas.generate(["passport.jpeg"], "retab-small", undefined, 96);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	document, err := retab.InferMIMEData("passport.jpeg")
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Schemas.Generate(ctx, &retab.SchemasGenerateParams{
		Documents: []any{document},
		Model:     ptr("retab-small"),
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Generated JSON Schema:")
	fmt.Println(*result)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

response = client.schemas.generate(
  documents: ['passport.jpeg'],
  model: 'retab-small',
  image_resolution_dpi: 96,
)

puts 'Generated JSON Schema:'
puts response

use retab::resources::schemas::GenerateParams;
use retab::Retab;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let mut params = GenerateParams::new(vec![PathBuf::from("passport.jpeg")]);
    params.body.model = Some("retab-small".into());
    params.body.image_resolution_dpi = Some(96);

    let response = client.schemas().generate(params).await?;

    println!("Generated JSON Schema:");
    println!("{:?}", response);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->schemas()->generate(
    documents: 'invoice.pdf',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Schemas.GenerateAsync(new SchemasGenerateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.schemas().generate(null, "retab-1.5", "Extract the invoice fields", 10L, null);
    System.out.println(result);
  }
}

curl https://api.retab.com/v1/schemas/generate \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "filename": "passport.jpeg",
        "url": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..."
      }
    ],
    "model": "retab-small",
    "image_resolution_dpi": 96
  }'

{
  "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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

Show child attributes

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.

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 | null

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

Show child attributes