from retab import MIMEData, Retab
client = Retab()
document = MIMEData(
filename="Invoice.pdf",
url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
}
extraction = client.extractions.create(
document=document,
json_schema=schema,
model="retab-small",
n_consensus=1,
metadata={"source": "docs"},
)
print(f"Extraction ID: {extraction.id}")
print(f"Filename: {extraction.file.filename}")
print(extraction.output)
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const document = {
filename: "Invoice.pdf",
url: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
};
const extraction = await client.extractions.create(
document,
{ type: "object", properties: {} },
"retab-small",
undefined,
1,
{ source: "docs" }
);
console.log(`Extraction ID: ${extraction.id}`);
console.log(extraction.output);
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 := retab.MIMEData{
Filename: "Invoice.pdf",
URL: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
}
extraction, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: document,
JSONSchema: map[string]any{
"type": "object",
"properties": map[string]any{
"invoice_number": map[string]any{"type": "string"},
"total": map[string]any{"type": "number"},
},
"required": []string{"invoice_number", "total"},
},
Model: ptr("retab-small"),
NConsensus: ptr(1),
Metadata: &map[string]string{"source": "docs"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Extraction ID: %s\n", extraction.ID)
fmt.Println(extraction.Output)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
document = {
filename: 'Invoice.pdf',
url: 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
}
schema = {
type: 'object',
properties: {
invoice_number: { type: 'string' },
total: { type: 'number' },
},
required: ['invoice_number', 'total'],
}
extraction = client.extractions.create(
document: document,
json_schema: schema,
model: 'retab-small',
n_consensus: 1,
metadata: { 'source' => 'docs' },
)
puts "Extraction ID: #{extraction.id}"
puts "Filename: #{extraction.file.filename}"
puts extraction.output
use retab::resources::extractions::CreateParams;
use retab::{MimeData, Retab};
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let schema = json!({
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
});
let schema_map = schema.as_object().unwrap().clone().into_iter().collect();
let document = MimeData::new(
"Invoice.pdf",
"https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
);
let mut params = CreateParams::new(document, schema_map);
params.body.model = Some("retab-small".into());
params.body.n_consensus = Some(1);
params.body.metadata = Some([("source".to_string(), "docs".to_string())].into_iter().collect());
let extraction = client.extractions().create(params).await?;
println!("Extraction ID: {}", extraction.id);
println!("Filename: {}", extraction.file.filename);
println!("{:?}", extraction.output);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->extractions()->create(
document: [
'filename' => 'Invoice.pdf',
'url' => 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
],
jsonSchema: ['type' => 'object', 'properties' => []],
);
print_r($result);
using Retab;
using System;
using System.Collections.Generic;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var document = MimeData.FromUrl(
new Uri("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
var result = await client.Extractions.CreateAsync(new ExtractionsCreateOptions
{
Document = document,
JsonSchema = new Dictionary<string, object>
{
["type"] = "object",
["properties"] = new Dictionary<string, object>
{
["invoice_number"] = new Dictionary<string, object> { ["type"] = "string" },
["total"] = new Dictionary<string, object> { ["type"] = "number" },
},
["required"] = new List<string> { "invoice_number", "total" },
},
Model = "retab-small",
NConsensus = 1,
Metadata = new Dictionary<string, string> { ["source"] = "docs" },
});
Console.WriteLine(result);
import com.retab.RetabClient;
import com.retab.models.MimeData;
import java.net.URI;
import java.util.List;
import java.util.Map;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
MimeData document =
MimeData.fromUrl(
URI.create("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
Map<String, Object> jsonSchema =
Map.of(
"type", "object",
"properties",
Map.of(
"invoice_number", Map.of("type", "string"),
"total", Map.of("type", "number")),
"required", List.of("invoice_number", "total"));
var result =
client
.extractions()
.create(
document,
jsonSchema,
"retab-small",
null,
1L,
Map.of("source", "docs"),
null,
null,
null,
null,
null);
System.out.println(result);
}
}
curl -X POST \
'https://api.retab.com/v1/extractions' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"document": {
"filename": "Invoice.pdf",
"url": "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"}
},
"required": ["invoice_number", "total"]
},
"n_consensus": 1,
"metadata": {"source": "docs"}
}'
{
"id": "extr_01G34H8J2K",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "Invoice.pdf",
"mime_type": "application/pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"total": { "type": "number" }
}
},
"n_consensus": 1,
"output": {
"invoice_number": "INV-2024-0042",
"total": 1234.56
},
"consensus": {
"choices": [],
"likelihoods": {
"invoice_number": 0.98,
"total": 0.97
}
},
"metadata": {
"source": "docs"
},
"usage": {
"prompt_tokens": 2760,
"completion_tokens": 20,
"total_tokens": 2780
},
"created_at": "2024-03-15T10:30:00Z"
}
Create Extraction
Run a structured extraction on a document.
Extracts structured data from the document according to the supplied
json_schema, using the requested model. Returns the extraction
with its output, consensus details, and usage on 201. When
stream is true, partial results are streamed back as they are produced.
from retab import MIMEData, Retab
client = Retab()
document = MIMEData(
filename="Invoice.pdf",
url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
}
extraction = client.extractions.create(
document=document,
json_schema=schema,
model="retab-small",
n_consensus=1,
metadata={"source": "docs"},
)
print(f"Extraction ID: {extraction.id}")
print(f"Filename: {extraction.file.filename}")
print(extraction.output)
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const document = {
filename: "Invoice.pdf",
url: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
};
const extraction = await client.extractions.create(
document,
{ type: "object", properties: {} },
"retab-small",
undefined,
1,
{ source: "docs" }
);
console.log(`Extraction ID: ${extraction.id}`);
console.log(extraction.output);
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 := retab.MIMEData{
Filename: "Invoice.pdf",
URL: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
}
extraction, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: document,
JSONSchema: map[string]any{
"type": "object",
"properties": map[string]any{
"invoice_number": map[string]any{"type": "string"},
"total": map[string]any{"type": "number"},
},
"required": []string{"invoice_number", "total"},
},
Model: ptr("retab-small"),
NConsensus: ptr(1),
Metadata: &map[string]string{"source": "docs"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Extraction ID: %s\n", extraction.ID)
fmt.Println(extraction.Output)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
document = {
filename: 'Invoice.pdf',
url: 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
}
schema = {
type: 'object',
properties: {
invoice_number: { type: 'string' },
total: { type: 'number' },
},
required: ['invoice_number', 'total'],
}
extraction = client.extractions.create(
document: document,
json_schema: schema,
model: 'retab-small',
n_consensus: 1,
metadata: { 'source' => 'docs' },
)
puts "Extraction ID: #{extraction.id}"
puts "Filename: #{extraction.file.filename}"
puts extraction.output
use retab::resources::extractions::CreateParams;
use retab::{MimeData, Retab};
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let schema = json!({
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
});
let schema_map = schema.as_object().unwrap().clone().into_iter().collect();
let document = MimeData::new(
"Invoice.pdf",
"https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
);
let mut params = CreateParams::new(document, schema_map);
params.body.model = Some("retab-small".into());
params.body.n_consensus = Some(1);
params.body.metadata = Some([("source".to_string(), "docs".to_string())].into_iter().collect());
let extraction = client.extractions().create(params).await?;
println!("Extraction ID: {}", extraction.id);
println!("Filename: {}", extraction.file.filename);
println!("{:?}", extraction.output);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->extractions()->create(
document: [
'filename' => 'Invoice.pdf',
'url' => 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
],
jsonSchema: ['type' => 'object', 'properties' => []],
);
print_r($result);
using Retab;
using System;
using System.Collections.Generic;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var document = MimeData.FromUrl(
new Uri("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
var result = await client.Extractions.CreateAsync(new ExtractionsCreateOptions
{
Document = document,
JsonSchema = new Dictionary<string, object>
{
["type"] = "object",
["properties"] = new Dictionary<string, object>
{
["invoice_number"] = new Dictionary<string, object> { ["type"] = "string" },
["total"] = new Dictionary<string, object> { ["type"] = "number" },
},
["required"] = new List<string> { "invoice_number", "total" },
},
Model = "retab-small",
NConsensus = 1,
Metadata = new Dictionary<string, string> { ["source"] = "docs" },
});
Console.WriteLine(result);
import com.retab.RetabClient;
import com.retab.models.MimeData;
import java.net.URI;
import java.util.List;
import java.util.Map;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
MimeData document =
MimeData.fromUrl(
URI.create("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
Map<String, Object> jsonSchema =
Map.of(
"type", "object",
"properties",
Map.of(
"invoice_number", Map.of("type", "string"),
"total", Map.of("type", "number")),
"required", List.of("invoice_number", "total"));
var result =
client
.extractions()
.create(
document,
jsonSchema,
"retab-small",
null,
1L,
Map.of("source", "docs"),
null,
null,
null,
null,
null);
System.out.println(result);
}
}
curl -X POST \
'https://api.retab.com/v1/extractions' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"document": {
"filename": "Invoice.pdf",
"url": "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"}
},
"required": ["invoice_number", "total"]
},
"n_consensus": 1,
"metadata": {"source": "docs"}
}'
{
"id": "extr_01G34H8J2K",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "Invoice.pdf",
"mime_type": "application/pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"total": { "type": "number" }
}
},
"n_consensus": 1,
"output": {
"invoice_number": "INV-2024-0042",
"total": 1234.56
},
"consensus": {
"choices": [],
"likelihoods": {
"invoice_number": 0.98,
"total": 0.97
}
},
"metadata": {
"source": "docs"
},
"usage": {
"prompt_tokens": 2760,
"completion_tokens": 20,
"total_tokens": 2780
},
"created_at": "2024-03-15T10:30:00Z"
}
Extraction resource that can later be retrieved via GET /v1/extractions/{extraction_id} or listed via GET /v1/extractions.
from retab import MIMEData, Retab
client = Retab()
document = MIMEData(
filename="Invoice.pdf",
url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
}
extraction = client.extractions.create(
document=document,
json_schema=schema,
model="retab-small",
n_consensus=1,
metadata={"source": "docs"},
)
print(f"Extraction ID: {extraction.id}")
print(f"Filename: {extraction.file.filename}")
print(extraction.output)
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const document = {
filename: "Invoice.pdf",
url: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
};
const extraction = await client.extractions.create(
document,
{ type: "object", properties: {} },
"retab-small",
undefined,
1,
{ source: "docs" }
);
console.log(`Extraction ID: ${extraction.id}`);
console.log(extraction.output);
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 := retab.MIMEData{
Filename: "Invoice.pdf",
URL: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
}
extraction, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: document,
JSONSchema: map[string]any{
"type": "object",
"properties": map[string]any{
"invoice_number": map[string]any{"type": "string"},
"total": map[string]any{"type": "number"},
},
"required": []string{"invoice_number", "total"},
},
Model: ptr("retab-small"),
NConsensus: ptr(1),
Metadata: &map[string]string{"source": "docs"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Extraction ID: %s\n", extraction.ID)
fmt.Println(extraction.Output)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
document = {
filename: 'Invoice.pdf',
url: 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
}
schema = {
type: 'object',
properties: {
invoice_number: { type: 'string' },
total: { type: 'number' },
},
required: ['invoice_number', 'total'],
}
extraction = client.extractions.create(
document: document,
json_schema: schema,
model: 'retab-small',
n_consensus: 1,
metadata: { 'source' => 'docs' },
)
puts "Extraction ID: #{extraction.id}"
puts "Filename: #{extraction.file.filename}"
puts extraction.output
use retab::resources::extractions::CreateParams;
use retab::{MimeData, Retab};
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let schema = json!({
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
});
let schema_map = schema.as_object().unwrap().clone().into_iter().collect();
let document = MimeData::new(
"Invoice.pdf",
"https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
);
let mut params = CreateParams::new(document, schema_map);
params.body.model = Some("retab-small".into());
params.body.n_consensus = Some(1);
params.body.metadata = Some([("source".to_string(), "docs".to_string())].into_iter().collect());
let extraction = client.extractions().create(params).await?;
println!("Extraction ID: {}", extraction.id);
println!("Filename: {}", extraction.file.filename);
println!("{:?}", extraction.output);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->extractions()->create(
document: [
'filename' => 'Invoice.pdf',
'url' => 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
],
jsonSchema: ['type' => 'object', 'properties' => []],
);
print_r($result);
using Retab;
using System;
using System.Collections.Generic;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var document = MimeData.FromUrl(
new Uri("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
var result = await client.Extractions.CreateAsync(new ExtractionsCreateOptions
{
Document = document,
JsonSchema = new Dictionary<string, object>
{
["type"] = "object",
["properties"] = new Dictionary<string, object>
{
["invoice_number"] = new Dictionary<string, object> { ["type"] = "string" },
["total"] = new Dictionary<string, object> { ["type"] = "number" },
},
["required"] = new List<string> { "invoice_number", "total" },
},
Model = "retab-small",
NConsensus = 1,
Metadata = new Dictionary<string, string> { ["source"] = "docs" },
});
Console.WriteLine(result);
import com.retab.RetabClient;
import com.retab.models.MimeData;
import java.net.URI;
import java.util.List;
import java.util.Map;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
MimeData document =
MimeData.fromUrl(
URI.create("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
Map<String, Object> jsonSchema =
Map.of(
"type", "object",
"properties",
Map.of(
"invoice_number", Map.of("type", "string"),
"total", Map.of("type", "number")),
"required", List.of("invoice_number", "total"));
var result =
client
.extractions()
.create(
document,
jsonSchema,
"retab-small",
null,
1L,
Map.of("source", "docs"),
null,
null,
null,
null,
null);
System.out.println(result);
}
}
curl -X POST \
'https://api.retab.com/v1/extractions' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"document": {
"filename": "Invoice.pdf",
"url": "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"}
},
"required": ["invoice_number", "total"]
},
"n_consensus": 1,
"metadata": {"source": "docs"}
}'
{
"id": "extr_01G34H8J2K",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "Invoice.pdf",
"mime_type": "application/pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"total": { "type": "number" }
}
},
"n_consensus": 1,
"output": {
"invoice_number": "INV-2024-0042",
"total": 1234.56
},
"consensus": {
"choices": [],
"likelihoods": {
"invoice_number": 0.98,
"total": 0.97
}
},
"metadata": {
"source": "docs"
},
"usage": {
"prompt_tokens": 2760,
"completion_tokens": 20,
"total_tokens": 2780
},
"created_at": "2024-03-15T10:30:00Z"
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request to run a structured extraction on a single document.
Extends the base extraction request with the document to process (either
inline content or a reference to a previously uploaded file) and a stream
flag that controls whether results are returned incrementally.
A file represented by its filename and a base64 data url.
Show child attributes
Show child attributes
JSON schema describing the structured output
The model to use for the extraction
Free-form instructions appended to the system prompt to steer the extraction.
Number of consensus extraction runs to perform. Uses deterministic single-pass when set to 1.
User-defined metadata to associate with this extraction
Show child attributes
Show child attributes
Additional chat messages forwarded to the extraction model.
If true, skip the LLM cache and force a fresh completion
If true, run asynchronously: returns immediately with status 'queued' and an empty output. Poll GET /v1//{id} until status is terminal. Mutually exclusive with stream.
Show child attributes
Show child attributes
Response
Streaming extraction chunks