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,
    context="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",
  "organization_id": "org_abc123",
  "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,
  "context": "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"
}
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,
    context="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",
  "organization_id": "org_abc123",
  "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,
  "context": "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.
context
string
Additional context (e.g. iteration context from a workflow loop).
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

Query Parameters

access_token
string | null

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.

context
string | null

Additional context for classification (e.g., iteration context from a loop)

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

organization_id
string
required

Organization ID of the user or application

id
string

Unique identifier of the classification

n_consensus
integer
default:1

Number of consensus votes used

context
string | null

Additional context supplied with the classification request

consensus
ClassificationConsensus · object

Consensus metadata for multi-vote classification runs

usage
RetabUsage · object

Usage information for the classification

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