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,
    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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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,
    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
  }
}

Request Body

document
MIMEData
required
The document to partition.
key
string
required
The field or concept used to group the document into chunks, such as invoice_number or claim_id.
instructions
string
required
Natural-language guidance describing how the document should be partitioned.
model
string
default:"retab-small"
The model used for partitioning.
n_consensus
integer
default:"1"
Number of partitioning runs to use for consensus voting. Max: 8.
bust_cache
boolean
default:"false"
When true, bypass the cache and force a fresh partition run.

Response Fields

output
array[PartitionChunk]
The partitioned document chunks.
consensus
PartitionConsensus
Consensus metadata for multi-vote runs.
usage
RetabUsage | null
Usage information for the partition operation.

Authorizations

Api-Key
string
header
required

Body

application/json
document
MIMEData · object
required

The document to partition

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.

Required range: 1 <= x <= 8
bust_cache
boolean
default:false

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

Response

Successful Response

Backend-internal stored partition record (organization-scoped).

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

id
string

Unique identifier of the partition

instructions
string
default:""

Instructions supplied with the partition request

n_consensus
integer
default:1

Number of consensus votes used

output
PartitionChunk · object[]

The list of partition chunks with their assigned pages

consensus
PartitionConsensus · object

Consensus metadata for multi-vote partition runs

origin
ProcessingRequestOrigin · object

Origin of the partition request

usage
RetabUsage · object

Usage information for the partition operation

created_at
string<date-time> | null
updated_at
string<date-time> | null