What to use

Constaia offers several ways to process documents. They all use the same API and the same keys; what changes is the cost, the latency and who uploads the file.

SummaryCopy Anchor Link

How to decideCopy Anchor Link

You can combine them: for example, classify to decide the type and then analyze with the right expect, or the widget in the form and batches for bulk imports.

CostCopy Anchor Link

• analyze: ceil(pages / 2) credits, minimum 1. An ID card with both sides in one file or a 2-page PDF costs 1 credit; a 5-page PDF, 3.
• classify: 0.2 credits per document.
• Batches: each document is charged as an analyze. In live mode Constaia checks up front that you have at least 1 credit per document (otherwise 402).
• Exports are included. Test mode never charges.

See Credits and billing and Pricing.

LatencyCopy Anchor Link

• analyze and classify wait up to 30 seconds. If the analysis hasn't finished, they respond 202 with the analysis in queued or processing and the result arrives by webhook or by polling GET /v1/analyses/{id}.
• With async: true the response is always an immediate 202.
• Batches are always asynchronous: you get analysis.review_required and analysis.failed per document and a single batch.completed at the end.

LimitsCopy Anchor Link

ExamplesCopy Anchor Link

analyzeCopy Anchor Link

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_valid.jpg \
  -F 'options={"expect":"es_dni","checks":{"min_age_years":18}}'

Returns the full analysis: document, verdict, fields, checks, warnings. See Quickstart.

classifyCopy Anchor Link

curl https://api.constaia.com/v1/classify \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@dni_valid.jpg \
  -F 'options={"expect":"es_dni"}'

{
  "object": "classification",
  "status": "completed",
  "document": { "type": "es_dni", "label": "DNI (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "candidates": [{ "type": "es_dni", "confidence": 0.97 }],
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [{ "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." }]
  },
  "warnings": []
}

The classify verdict only evaluates the type (type_match or type_mismatch): it does not check expiry or extract fields.

BatchCopy Anchor Link

curl https://api.constaia.com/v1/batches \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "files[]=@invoice-001.pdf" \
  -F "files[]=@invoice-002.pdf" \
  -F 'options={"expect":"invoice","export":["xlsx"]}'

It responds 202 with a batch object (bat_...) in processing. When it finishes you get batch.completed with counts and the combined export in exports.xlsx, one row per document. See Bulk batches.

WidgetCopy Anchor Link

<script type="module" src="https://cdn.jsdelivr.net/npm/@constaia/widget@0.1"></script>

<constaia-upload endpoint="/api/constaia" document="es_dni" lang="en"></constaia-upload>

The widget never holds the key: it sends the file to your endpoint (/api/constaia), and your backend calls POST /v1/analyze with the expect and checks it decides. See Widget.

MCPCopy Anchor Link

claude mcp add constaia --env CONSTAIA_API_KEY=ck_test_... -- npx -y @constaia/mcp

It exposes the tools analyze_document, classify_document, list_document_types, get_analysis and get_balance. See MCP server.

No-codeCopy Anchor Link

In n8n, Make, Zapier or Power Automate you use the tool's HTTP module to call POST /v1/analyze. See the n8n, Make and Zapier guides.

Next stepsCopy Anchor Link