Classification
Identify what a document is before deciding what to do with it.
Classification answers a narrower question than extraction: not what does this document say but what kind of document is this. It is what you reach for when a file arrives without a reliable label — an emailed attachment, a scanned packet, a customer upload — and you need to route it before you can extract from it.
The shape mirrors Extraction exactly. /classify/sync returns the answer in the response, /classify returns a job ID, and /classify/bulk handles a set. Feed the result into documentType on an extraction call and you have the routing pattern most integrations end up building.
Generated endpoint reference
The generated reference is the source of truth for schemas and responses.
Use the generated reference navigation for asynchronous and bulk classification. This guide keeps routing behavior and ZIP-specific details.
A ZIP upload is classified per member document, and those results carry classificationGroupId, classificationGroupIndex and classificationGroupTotal so you can reassemble the set. Plain PDF and Excel classifications do not carry those fields.
For the categories, confidence behaviour, and how classification is reviewed in the product, see Document Classification.
Get classification details
GET /classifications/{classification_id}
Requires the X-Api-Key header. See Authentication.
Path and query parameters
classification_id
path
string
Yes
Responses
200
OK
SingleClassificationResponse
400
Bad Request
ValidationError
401
Authentication required — the X-Api-Key header is missing or invalid.
404
No classification exists with that ID.
Example
Classify document type (Async)
POST /classify
Requires the X-Api-Key header. See Authentication.
Request body — application/json, required: ClassifyRequest
content
string | null
Base64-encoded file content
context
string | null
Additional context to guide the classification
custom_document_types
array<string> | null
Custom document types to classify against. If provided, classification is restricted to these types.
custom_document_types_url
string | null
URL to a JSON file containing custom document types. Merged with custom_document_types if both provided.
entities
object | null
Entity ID-to-name mapping for Excel workbook classification: {entityId: entityName, ...}
file_url
string | null
Public URL to file
metadata
object | null
Custom metadata
model
string | null
"gemini-3"
LLM model for classification. Must be one of the supported models. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
use_custom_types_only
boolean | null
false
If true, only custom_document_types are valid classification results. Requires custom_document_types or custom_document_types_url to be provided.
Responses
200
OK
ClassifyResponse
400
Bad Request
ValidationError
401
Authentication required — the X-Api-Key header is missing or invalid.
500
Returned instead of 400 when the request body is missing or invalid. Known defect.
Example
Bulk document classification
POST /classify/bulk
Requires the X-Api-Key header. See Authentication.
Request body — application/json, required: ClassifyBulkRequest
context
array<string> | null
Per-file classification context strings. Length must match files array.
custom_document_types
array<string> | null
Custom document types applied to all files. If provided, classification is restricted to these types.
custom_document_types_url
string | null
URL to custom document types JSON file. Merged with custom_document_types for all files.
entities
object | null
Entity ID-to-name mapping for Excel workbook classification across all files: {entityId: entityName, ...}
files
array<ClassifyBulkRequestFile>
Yes
List of files to classify
metadata
array<object> | null
Per-file metadata dicts. Length must match files array.
model
string | null
LLM model for classification (applies to all files). Defaults to gemini-3 if not specified. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
use_custom_types_only
boolean | null
false
If true, only custom_document_types are valid. Applied to all files.
Nested objects
ClassifyBulkRequestFile
content
string | null
Base64-encoded file content
file_url
string | null
Public URL to file
Responses
200
OK
ClassifyBulkResponse
400
Bad Request
ValidationError
401
Authentication required — the X-Api-Key header is missing or invalid.
Example
Synchronous document classification
POST /classify/sync
Requires the X-Api-Key header. See Authentication.
Request body — application/json, required: ClassifySyncRequest
content
string | null
Base64-encoded file content
context
string | null
Additional context to guide the classification
custom_document_types
array<string> | null
Custom document types to classify against. If provided, classification is restricted to these types.
custom_document_types_url
string | null
URL to a JSON file containing custom document types. Merged with custom_document_types if both provided.
entities
object | null
Entity ID-to-name mapping for Excel workbook classification: {entityId: entityName, ...}
file_url
string | null
Public URL to file
metadata
object | null
Custom metadata
model
string | null
"gemini-3"
LLM model for classification. Must be one of the supported models. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
use_custom_types_only
boolean | null
false
If true, only custom_document_types are valid classification results. Requires custom_document_types or custom_document_types_url to be provided.
Responses
200
OK
ClassifySyncResponse
400
Bad Request
ValidationError
401
Authentication required — the X-Api-Key header is missing or invalid.
500
Returned instead of 400 when the request body is missing or invalid. Known defect.
Example
Related pages
Document Classification — the same capability through the UI.
Document Types — the registry the classifier draws from.
Classify, then extract — the routing recipe.
Extraction API — where a classification result usually goes next.
Last updated