Skip to main content
POST
/
v1
/
partitions
from retab import Retab

client = Retab()

response = client.partitions.create(
    document="invoice_batch.pdf",
    key="invoice_number",
    instructions="Return one chunk per invoice number and keep all pages for the same invoice together.",
    model="retab-small",
    n_consensus=3,
    allow_overlap=True,
    bust_cache=False,
)

for chunk in response.output:
    print(chunk.key, chunk.pages)
{
  "output": [
    {
      "key": "INV-001",
      "pages": [1, 2]
    },
    {
      "key": "INV-002",
      "pages": [3, 4]
    }
  ],
  "consensus": {
    "likelihoods": [
      {
        "key": 0.99,
        "pages": [0.99, 0.98]
      },
      {
        "key": 0.96,
        "pages": [0.95, 0.95]
      }
    ],
    "choices": [
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ],
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ],
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  }
}
Partition a document into repeated chunks keyed by a value such as invoice_number, policy_id, or claim_number.
from retab import Retab

client = Retab()

response = client.partitions.create(
    document="invoice_batch.pdf",
    key="invoice_number",
    instructions="Return one chunk per invoice number and keep all pages for the same invoice together.",
    model="retab-small",
    n_consensus=3,
    allow_overlap=True,
    bust_cache=False,
)

for chunk in response.output:
    print(chunk.key, chunk.pages)
{
  "output": [
    {
      "key": "INV-001",
      "pages": [1, 2]
    },
    {
      "key": "INV-002",
      "pages": [3, 4]
    }
  ],
  "consensus": {
    "likelihoods": [
      {
        "key": 0.99,
        "pages": [0.99, 0.98]
      },
      {
        "key": 0.96,
        "pages": [0.95, 0.95]
      }
    ],
    "choices": [
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ],
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ],
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  }
}

Authorizations

Api-Key
string
header
required

Body

application/json

Public create-partition request body.

document
MIMEData · object
required

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

key
string
required

The key to partition the document by

instructions
string
required

Instructions describing how the document should be partitioned

model
string
default:retab-small

The model to use for partitioning

n_consensus
integer
default:1

Number of partitioning runs to use for consensus voting. Uses deterministic single-pass when set to 1.

allow_overlap
boolean
default:true

If true, allow a page to appear in more than one partition chunk

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 partition result: a document segmented into chunks along the requested key.

id
string
required

Unique identifier of the partition

file
FileRef · object
required

Information about the partitioned file

model
string
required

Model used for the partition operation

key
string
required

Partition key used for the run

instructions
string | null

Free-form instructions supplied with the partition request

n_consensus
integer
default:1

Number of consensus votes used

allow_overlap
boolean
default:true

Whether pages were allowed to appear in more than one partition chunk

output
PartitionChunk · object[]

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

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.

consensus
PartitionConsensus · object

Consensus metadata for multi-vote partition runs

usage
RetabUsage · object

Usage information for the partition operation

created_at
string<date-time> | null