Create Split - Retab Docs

from retab import Retab

client = Retab()

split = client.splits.create(
    document="invoice_batch.pdf",
    model="retab-small",
    subdocuments=[
        {
            "name": "invoice",
            "description": "Invoice documents with billing information",
            "allow_multiple_instances": True,
        },
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    instructions="Processing Q4 2024 vendor document batch",
    n_consensus=3,
    bust_cache=False,
)

for sub in split.output:
    print(f"{sub.name}: pages {sub.pages}")

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

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

const split = await client.splits.create("invoice_batch.pdf", [
    {
      name: "invoice",
      description: "Invoice documents with billing information",
      allowMultipleInstances: true,
    },
    { name: "receipt", description: "Receipt documents for payments" },
    { name: "contract", description: "Legal contract documents" },
  ], "retab-small", "Processing Q4 2024 vendor document batch", 3, false);

split.output.forEach((sub) => {
  console.log(`${sub.name}: pages ${sub.pages}`);
});

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("invoice_batch.pdf")
	if err != nil {
		log.Fatal(err)
	}

	split, err := client.Splits.Create(ctx, &retab.SplitsCreateParams{
		Document: document,
		Model:    ptr("retab-small"),
		Subdocuments: []*retab.Subdocument{
			{Name: "invoice", Description: ptr("Invoice documents with billing information"), AllowMultipleInstances: ptr(true)},
			{Name: "receipt", Description: ptr("Receipt documents for payments")},
			{Name: "contract", Description: ptr("Legal contract documents")},
		},
		Instructions: ptr("Processing Q4 2024 vendor document batch"),
		NConsensus:   ptr(3),
		BustCache:    ptr(false),
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, sub := range split.Output {
		fmt.Printf("%s: pages %v\n", sub.Name, sub.Pages)
	}
}

require 'retab'

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

split = client.splits.create(
  document: 'invoice_batch.pdf',
  model: 'retab-small',
  subdocuments: [
    {
      'name' => 'invoice',
      'description' => 'Invoice documents with billing information',
      'allow_multiple_instances' => true,
    },
    { 'name' => 'receipt', 'description' => 'Receipt documents for payments' },
    { 'name' => 'contract', 'description' => 'Legal contract documents' },
  ],
  instructions: 'Processing Q4 2024 vendor document batch',
  n_consensus: 3,
  bust_cache: false,
)

split.output.each do |sub|
  puts "#{sub.name}: pages #{sub.pages}"
end

use retab::models::Subdocument;
use retab::resources::splits::CreateParams;
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 subdocuments = vec![
        Subdocument {
            name: "invoice".into(),
            description: Some("Invoice documents with billing information".into()),
            allow_multiple_instances: Some(true),
        },
        Subdocument {
            name: "receipt".into(),
            description: Some("Receipt documents for payments".into()),
            allow_multiple_instances: None,
        },
        Subdocument {
            name: "contract".into(),
            description: Some("Legal contract documents".into()),
            allow_multiple_instances: None,
        },
    ];

    let mut params = CreateParams::new(PathBuf::from("invoice_batch.pdf"), subdocuments);
    params.body.model = Some("retab-small".into());
    params.body.instructions = Some("Processing Q4 2024 vendor document batch".into());
    params.body.n_consensus = Some(3);
    params.body.bust_cache = Some(false);

    let split = client.splits().create(params).await?;

    for sub in split.output.as_ref().unwrap() {
        println!("{}: pages {:?}", sub.name, sub.pages);
    }
    Ok(())
}

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

use Retab\Client;

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

$result = $client->splits()->create(
    document: 'invoice.pdf',
    subdocuments: '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.Splits.CreateAsync(new SplitsCreateOptions());
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.splits().create(null, null, "retab-1.5", "Extract the invoice fields", 10L, null, null);
    System.out.println(result);
  }
}

curl -X POST \
  'https://api.retab.com/v1/splits' \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "document": {
    "filename": "invoice_batch.pdf",
    "url": "data:application/pdf;base64,JVBERi0xLjQK..."
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments"
    },
    {
      "name": "contract",
      "description": "Legal contract documents"
    }
  ],
  "instructions": "Processing Q4 2024 vendor document batch",
  "n_consensus": 3,
  "bust_cache": false
}'

{
  "id": "split_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice_batch.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments",
      "allow_multiple_instances": false
    }
  ],
  "n_consensus": 3,
  "instructions": "Processing Q4 2024 vendor document batch",
  "output": [
    { "name": "invoice", "pages": [1, 2, 3] },
    { "name": "invoice", "pages": [4, 5] },
    { "name": "receipt", "pages": [6] }
  ],
  "consensus": {
    "likelihoods": [
      { "name": 0.98, "pages": [0.99, 0.97, 0.96] },
      { "name": 0.95, "pages": [0.95, 0.93] },
      { "name": 0.99, "pages": [0.99] }
    ],
    "choices": [
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2] },
        { "name": "invoice", "pages": [3, 4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  },
  "created_at": "2024-03-15T10:30:00Z"
}

POST

splits

from retab import Retab

client = Retab()

split = client.splits.create(
    document="invoice_batch.pdf",
    model="retab-small",
    subdocuments=[
        {
            "name": "invoice",
            "description": "Invoice documents with billing information",
            "allow_multiple_instances": True,
        },
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    instructions="Processing Q4 2024 vendor document batch",
    n_consensus=3,
    bust_cache=False,
)

for sub in split.output:
    print(f"{sub.name}: pages {sub.pages}")

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

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

const split = await client.splits.create("invoice_batch.pdf", [
    {
      name: "invoice",
      description: "Invoice documents with billing information",
      allowMultipleInstances: true,
    },
    { name: "receipt", description: "Receipt documents for payments" },
    { name: "contract", description: "Legal contract documents" },
  ], "retab-small", "Processing Q4 2024 vendor document batch", 3, false);

split.output.forEach((sub) => {
  console.log(`${sub.name}: pages ${sub.pages}`);
});

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("invoice_batch.pdf")
	if err != nil {
		log.Fatal(err)
	}

	split, err := client.Splits.Create(ctx, &retab.SplitsCreateParams{
		Document: document,
		Model:    ptr("retab-small"),
		Subdocuments: []*retab.Subdocument{
			{Name: "invoice", Description: ptr("Invoice documents with billing information"), AllowMultipleInstances: ptr(true)},
			{Name: "receipt", Description: ptr("Receipt documents for payments")},
			{Name: "contract", Description: ptr("Legal contract documents")},
		},
		Instructions: ptr("Processing Q4 2024 vendor document batch"),
		NConsensus:   ptr(3),
		BustCache:    ptr(false),
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, sub := range split.Output {
		fmt.Printf("%s: pages %v\n", sub.Name, sub.Pages)
	}
}

require 'retab'

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

split = client.splits.create(
  document: 'invoice_batch.pdf',
  model: 'retab-small',
  subdocuments: [
    {
      'name' => 'invoice',
      'description' => 'Invoice documents with billing information',
      'allow_multiple_instances' => true,
    },
    { 'name' => 'receipt', 'description' => 'Receipt documents for payments' },
    { 'name' => 'contract', 'description' => 'Legal contract documents' },
  ],
  instructions: 'Processing Q4 2024 vendor document batch',
  n_consensus: 3,
  bust_cache: false,
)

split.output.each do |sub|
  puts "#{sub.name}: pages #{sub.pages}"
end

use retab::models::Subdocument;
use retab::resources::splits::CreateParams;
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 subdocuments = vec![
        Subdocument {
            name: "invoice".into(),
            description: Some("Invoice documents with billing information".into()),
            allow_multiple_instances: Some(true),
        },
        Subdocument {
            name: "receipt".into(),
            description: Some("Receipt documents for payments".into()),
            allow_multiple_instances: None,
        },
        Subdocument {
            name: "contract".into(),
            description: Some("Legal contract documents".into()),
            allow_multiple_instances: None,
        },
    ];

    let mut params = CreateParams::new(PathBuf::from("invoice_batch.pdf"), subdocuments);
    params.body.model = Some("retab-small".into());
    params.body.instructions = Some("Processing Q4 2024 vendor document batch".into());
    params.body.n_consensus = Some(3);
    params.body.bust_cache = Some(false);

    let split = client.splits().create(params).await?;

    for sub in split.output.as_ref().unwrap() {
        println!("{}: pages {:?}", sub.name, sub.pages);
    }
    Ok(())
}

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

use Retab\Client;

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

$result = $client->splits()->create(
    document: 'invoice.pdf',
    subdocuments: '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.Splits.CreateAsync(new SplitsCreateOptions());
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.splits().create(null, null, "retab-1.5", "Extract the invoice fields", 10L, null, null);
    System.out.println(result);
  }
}

curl -X POST \
  'https://api.retab.com/v1/splits' \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "document": {
    "filename": "invoice_batch.pdf",
    "url": "data:application/pdf;base64,JVBERi0xLjQK..."
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments"
    },
    {
      "name": "contract",
      "description": "Legal contract documents"
    }
  ],
  "instructions": "Processing Q4 2024 vendor document batch",
  "n_consensus": 3,
  "bust_cache": false
}'

{
  "id": "split_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice_batch.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments",
      "allow_multiple_instances": false
    }
  ],
  "n_consensus": 3,
  "instructions": "Processing Q4 2024 vendor document batch",
  "output": [
    { "name": "invoice", "pages": [1, 2, 3] },
    { "name": "invoice", "pages": [4, 5] },
    { "name": "receipt", "pages": [6] }
  ],
  "consensus": {
    "likelihoods": [
      { "name": 0.98, "pages": [0.99, 0.97, 0.96] },
      { "name": 0.95, "pages": [0.95, 0.93] },
      { "name": 0.99, "pages": [0.99] }
    ],
    "choices": [
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2] },
        { "name": "invoice", "pages": [3, 4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Split a multi-page document into labeled subdocuments and return the canonical split resource. This endpoint is split-only: key-based grouping belongs to /v1/partitions.

from retab import Retab

client = Retab()

split = client.splits.create(
    document="invoice_batch.pdf",
    model="retab-small",
    subdocuments=[
        {
            "name": "invoice",
            "description": "Invoice documents with billing information",
            "allow_multiple_instances": True,
        },
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    instructions="Processing Q4 2024 vendor document batch",
    n_consensus=3,
    bust_cache=False,
)

for sub in split.output:
    print(f"{sub.name}: pages {sub.pages}")

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

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

const split = await client.splits.create("invoice_batch.pdf", [
    {
      name: "invoice",
      description: "Invoice documents with billing information",
      allowMultipleInstances: true,
    },
    { name: "receipt", description: "Receipt documents for payments" },
    { name: "contract", description: "Legal contract documents" },
  ], "retab-small", "Processing Q4 2024 vendor document batch", 3, false);

split.output.forEach((sub) => {
  console.log(`${sub.name}: pages ${sub.pages}`);
});

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("invoice_batch.pdf")
	if err != nil {
		log.Fatal(err)
	}

	split, err := client.Splits.Create(ctx, &retab.SplitsCreateParams{
		Document: document,
		Model:    ptr("retab-small"),
		Subdocuments: []*retab.Subdocument{
			{Name: "invoice", Description: ptr("Invoice documents with billing information"), AllowMultipleInstances: ptr(true)},
			{Name: "receipt", Description: ptr("Receipt documents for payments")},
			{Name: "contract", Description: ptr("Legal contract documents")},
		},
		Instructions: ptr("Processing Q4 2024 vendor document batch"),
		NConsensus:   ptr(3),
		BustCache:    ptr(false),
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, sub := range split.Output {
		fmt.Printf("%s: pages %v\n", sub.Name, sub.Pages)
	}
}

require 'retab'

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

split = client.splits.create(
  document: 'invoice_batch.pdf',
  model: 'retab-small',
  subdocuments: [
    {
      'name' => 'invoice',
      'description' => 'Invoice documents with billing information',
      'allow_multiple_instances' => true,
    },
    { 'name' => 'receipt', 'description' => 'Receipt documents for payments' },
    { 'name' => 'contract', 'description' => 'Legal contract documents' },
  ],
  instructions: 'Processing Q4 2024 vendor document batch',
  n_consensus: 3,
  bust_cache: false,
)

split.output.each do |sub|
  puts "#{sub.name}: pages #{sub.pages}"
end

use retab::models::Subdocument;
use retab::resources::splits::CreateParams;
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 subdocuments = vec![
        Subdocument {
            name: "invoice".into(),
            description: Some("Invoice documents with billing information".into()),
            allow_multiple_instances: Some(true),
        },
        Subdocument {
            name: "receipt".into(),
            description: Some("Receipt documents for payments".into()),
            allow_multiple_instances: None,
        },
        Subdocument {
            name: "contract".into(),
            description: Some("Legal contract documents".into()),
            allow_multiple_instances: None,
        },
    ];

    let mut params = CreateParams::new(PathBuf::from("invoice_batch.pdf"), subdocuments);
    params.body.model = Some("retab-small".into());
    params.body.instructions = Some("Processing Q4 2024 vendor document batch".into());
    params.body.n_consensus = Some(3);
    params.body.bust_cache = Some(false);

    let split = client.splits().create(params).await?;

    for sub in split.output.as_ref().unwrap() {
        println!("{}: pages {:?}", sub.name, sub.pages);
    }
    Ok(())
}

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

use Retab\Client;

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

$result = $client->splits()->create(
    document: 'invoice.pdf',
    subdocuments: '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.Splits.CreateAsync(new SplitsCreateOptions());
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.splits().create(null, null, "retab-1.5", "Extract the invoice fields", 10L, null, null);
    System.out.println(result);
  }
}

curl -X POST \
  'https://api.retab.com/v1/splits' \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "document": {
    "filename": "invoice_batch.pdf",
    "url": "data:application/pdf;base64,JVBERi0xLjQK..."
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments"
    },
    {
      "name": "contract",
      "description": "Legal contract documents"
    }
  ],
  "instructions": "Processing Q4 2024 vendor document batch",
  "n_consensus": 3,
  "bust_cache": false
}'

{
  "id": "split_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice_batch.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "subdocuments": [
    {
      "name": "invoice",
      "description": "Invoice documents with billing information",
      "allow_multiple_instances": true
    },
    {
      "name": "receipt",
      "description": "Receipt documents for payments",
      "allow_multiple_instances": false
    }
  ],
  "n_consensus": 3,
  "instructions": "Processing Q4 2024 vendor document batch",
  "output": [
    { "name": "invoice", "pages": [1, 2, 3] },
    { "name": "invoice", "pages": [4, 5] },
    { "name": "receipt", "pages": [6] }
  ],
  "consensus": {
    "likelihoods": [
      { "name": 0.98, "pages": [0.99, 0.97, 0.96] },
      { "name": 0.95, "pages": [0.95, 0.93] },
      { "name": 0.99, "pages": [0.99] }
    ],
    "choices": [
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2] },
        { "name": "invoice", "pages": [3, 4, 5] },
        { "name": "receipt", "pages": [6] }
      ],
      [
        { "name": "invoice", "pages": [1, 2, 3] },
        { "name": "invoice", "pages": [4, 5] },
        { "name": "receipt", "pages": [6] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Request body to create a split.

document

MIMEData · object

required

A file represented by its filename and a base64 data url.

MIMEData
FileRef

Show child attributes

subdocuments

Subdocument · object[]

required

The subdocuments to split the document into

Show child attributes

model

string

default:retab-small

The model to use to split the document

instructions

string | null

Free-form instructions appended to the system prompt to steer the split.

n_consensus

integer

default:1

Number of consensus split runs to perform. Uses deterministic single-pass when set to 1.

bust_cache

boolean

default:false

If true, skip the LLM cache and force a fresh completion

background

boolean

default:false

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.

Response

Successful Response

A split result: a document divided into its constituent subdocuments.

string

required

Unique identifier of the split result

file

FileRef · object

required

Information about the split file

Show child attributes

model

string

required

Model used for the split operation

subdocuments

Subdocument · object[]

required

Subdocuments used for the split operation

Show child attributes

n_consensus

integer

default:1

Number of consensus votes used

instructions

string | null

Free-form instructions supplied with the split request.

output

SplitResult · object[]

The list of document splits with their assigned pages. Empty [] until status == 'completed'.

Show child attributes

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

consensus

SplitConsensus · object | null

Consensus metadata for multi-vote split runs

Show child attributes

usage

RetabUsage · object | null

Usage information for the split operation

Show child attributes

created_at

string<date-time> | null