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

client = Retab()

classification = client.classifications.create(
    document="invoice.pdf",
    model="retab-small",
    categories=[
        {"name": "invoice", "description": "Invoice documents with billing information"},
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    first_n_pages=3,
    instructions="Processing batch from Q4 2024 vendor submissions",
    n_consensus=1,
)

print(f"Classification ID: {classification.id}")
print(f"Category: {classification.output.category}")
print(f"Reasoning: {classification.output.reasoning}")

{
  "id": "cls_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "categories": [
    {"name": "invoice", "description": "Invoice documents with billing information"},
    {"name": "receipt", "description": "Receipt documents for payments"},
    {"name": "contract", "description": "Legal contract documents"}
  ],
  "n_consensus": 1,
  "instructions": "Processing batch from Q4 2024 vendor submissions",
  "output": {
    "reasoning": "The document contains billing details including line items, unit prices, quantities, and a total amount due.",
    "category": "invoice"
  },
  "consensus": {
    "choices": [],
    "likelihood": null
  },
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 40,
    "total_tokens": 1540
  },
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

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.

Classify a document into one of the provided categories and persist the result as a Classification resource that can later be retrieved via GET /v1/classifications/{classification_id} or listed via GET /v1/classifications. 
from retab import Retab

client = Retab()

classification = client.classifications.create(
    document="invoice.pdf",
    model="retab-small",
    categories=[
        {"name": "invoice", "description": "Invoice documents with billing information"},
        {"name": "receipt", "description": "Receipt documents for payments"},
        {"name": "contract", "description": "Legal contract documents"},
    ],
    first_n_pages=3,
    instructions="Processing batch from Q4 2024 vendor submissions",
    n_consensus=1,
)

print(f"Classification ID: {classification.id}")
print(f"Category: {classification.output.category}")
print(f"Reasoning: {classification.output.reasoning}")

{
  "id": "cls_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "categories": [
    {"name": "invoice", "description": "Invoice documents with billing information"},
    {"name": "receipt", "description": "Receipt documents for payments"},
    {"name": "contract", "description": "Legal contract documents"}
  ],
  "n_consensus": 1,
  "instructions": "Processing batch from Q4 2024 vendor submissions",
  "output": {
    "reasoning": "The document contains billing details including line items, unit prices, quantities, and a total amount due.",
    "category": "invoice"
  },
  "consensus": {
    "choices": [],
    "likelihood": null
  },
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 40,
    "total_tokens": 1540
  },
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

​
Request Body

​
document
MIMEData
required
The document to classify.
​
categories
array[Category]
required
The candidate categories. Each Category has a name and optional description.
​
model
string
default:"retab-small"
The model used for classification.
​
first_n_pages
integer
Only use the first N pages of the document for classification. Useful for long documents where the classification signal sits on the first page.
​
instructions
string
Free-form instructions appended to the system prompt to steer the classification.
​
n_consensus
integer
default:"1"
Number of classification runs to use for consensus voting. Max: 16.
​
bust_cache
boolean
default:"false"
When true, bypass the cache and re-run the classification.

​
Response Fields

​
id
string
Unique classification identifier.
​
file
object
File metadata: id, filename, mime_type.
​
model
string
Model used for classification.
​
categories
array[Category]
Categories the document was classified against.
​
output
object
The classification decision.
​
consensus
object
Consensus metadata (choices, likelihood).
​
usage
RetabUsage | null
Token and credit usage information.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 last update timestamp.

Authorizations

​
Api-Key
string
header
required

Body

application/json
​
document
MIMEData · object
required

The document to classify

​
categories
Category · object[]
required

The categories to classify the document into

​
model
string
default:retab-small

The model to use for classification

​
first_n_pages
integer | null

Only use the first N pages of the document for classification. Useful for large documents where classification can be determined from early pages.

​
instructions
string | null

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

​
n_consensus
integer
default:1

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

Required range: 1 <= x <= 16
​
bust_cache
boolean
default:false

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

Response

Successful Response

Backend-internal classification with organization scoping.

​
file
FileRef · object
required

Information about the classified file

​
model
string
required

Model used for classification

​
categories
Category · object[]
required

Categories the document was classified against

​
output
ClassificationDecision · object
required

The classification result with reasoning

​
id
string

Unique identifier of the classification

​
n_consensus
integer
default:1

Number of consensus votes used

​
instructions
string | null

Free-form instructions supplied with the classification request.

​
consensus
ClassificationConsensus · object

Consensus metadata for multi-vote classification runs

​
origin
ProcessingRequestOrigin · object

Origin of the classification request

​
usage
RetabUsage · object

Usage information for the classification

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