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

Query Parameters

​
access_token
string | null

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

​
output
PartitionChunk · object[]

The partitioned document chunks

​
consensus
PartitionConsensus · object

Consensus metadata for multi-vote partition runs

​
usage
RetabUsage · object

Usage information for the partition operation