API reference
Interactive reference and OpenAPI 3.1 specification of the Constaia API, /v1 conventions, client generation and import into Postman, Insomnia or Bruno.
The Constaia API is described with OpenAPI 3.1. The specification is generated from the API code, so it always matches what runs in production.
Interactive reference
Every endpoint, parameter and response. You can try calls with your ck_test_ key.
openapi.json
The specification as JSON to generate clients, import into Postman, Insomnia or Bruno, or validate responses in your tests.
Conventions
| Base URL | https://api.constaia.com/v1 |
| Authentication | Authorization: Bearer ck_live_… or ck_test_…. Publishable keys (pk_live_…/pk_test_…) only upload documents to a session from the browser. See Authentication. |
| Format | JSON with snake_case names. Files are uploaded with multipart/form-data or as file_url/file_base64 in JSON. |
| Ids | Prefix + ULID: an_ (analysis), bat_ (batch), we_ (webhook endpoint), exp_ (export), key_ (API key), req_ (request), msg_ (webhook delivery), tpl_ (template), vl_ (verification link), dos_ (dossier), sess_ (session). |
| Dates | ISO 8601 in UTC. |
| Errors | { "error": { "type", "code", "message", "param", "request_id" } }. See Errors. |
| Idempotency | Idempotency-Key header on the analysis, classification, batch and webhook endpoint POSTs. See Idempotency. |
| Pagination | Cursor based with limit and starting_after; response with has_more. See Pagination. |
| Limits | Per plan: 2 requests per second per key, 2 concurrent analyses and 60 pages/min on free; 10, 10 and 600 on paid; can be raised per account. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; on a 429, Retry-After. See Rate limits. |
| Tracing | X-Request-Id header on every response. Include it if you contact us about a problem. |
| CORS | Open on /v1, but secret keys must never be used from a browser (403 secret_key_in_browser). From the browser, only publishable keys with a session. |
| Versioning | Version in the path (/v1). See Versioning and the changelog. |
Official SDKs
Before generating a client, check whether there is an SDK for your language: JavaScript/TypeScript, PHP and Python. They include retries honouring Retry-After, automatic Idempotency-Key, a concurrency limit, pagination and webhook verification, which a generated client does not have.
Coming soon
Official SDKs for Go, Java, Ruby and .NET. Meanwhile, generate a client from the specification or call the API with your HTTP client (see the Go, Spring Boot, Rails and .NET guides).
Generating a client
With OpenAPI Generator (version 7 or later, which supports OpenAPI 3.1):
npx @openapitools/openapi-generator-cli generate \
-i https://api.constaia.com/openapi.json \
-g go \
-o ./constaia-go \
--additional-properties=packageName=constaiaKeep in mind when using a generated client:
- In
multipart/form-data, theoptionsfield is a JSON string, not an object. Serialise it yourself. 202responses return the same object as200, withstatusqueuedorprocessing.- It does not include webhook verification: use the algorithm in Webhooks.
- Add retries on
429and5xxyourself, honouringRetry-After, and sendIdempotency-Keyon POSTs. - Regenerate the client when the changelog announces new fields. Ignore unknown fields in your code.
Importing into Postman, Insomnia or Bruno
- Import the specification from the URL
https://api.constaia.com/openapi.json(or download it and import the file). - Create an environment variable with your key, for example
constaia_api_key = ck_test_..., and set the collection's authentication to Bearer Token with that variable. - In
POST /v1/analyze, choose aform-databody: afilefield of type file and anoptionstext field with the JSON, for example{"expect":"es_dni"}. - Use files named as in test mode (
dni_valid.jpg,dni_expired.jpg…) to see each kind of response at no cost.
Endpoint summary
The summary below is generated from a sample OpenAPI file bundled with this site, so you can see the endpoints at a glance. The source of truth is always api.constaia.com/openapi.json.
| post | /v1/analyze | Analiza un documento y devuelve veredicto, campos y checks |
| post | /v1/classify | Solo clasifica el documento (0,2 créditos) |
| get | /v1/analyses | Lista análisis (paginada) |
| get | /v1/analyses/{id} | Recupera un análisis (si keep_results) |
| delete | /v1/analyses/{id} | Borra fichero y resultados |
| get | /v1/analyses/{id}/export | Descarga directa de una exportación |
| post | /v1/batches | Crea un lote de hasta 100 documentos (siempre async) |
| get | /v1/batches/{id} | Estado de un lote |
| get | /v1/document-types | Catálogo de tipos con campos y checks |
| get | /v1/document-types/{type} | Detalle de un tipo |
| get | /v1/verification-links | Lista enlaces de verificación (filtros status, reference, metadata) |
| post | /v1/verification-links | Crea un enlace de verificación (página alojada + expediente) |
| get | /v1/verification-links/{id} | Recupera un enlace de verificación |
| delete | /v1/verification-links/{id} | Cancela un enlace de verificación |
| get | /v1/webhook-endpoints | Lista endpoints |
| post | /v1/webhook-endpoints | Alta de un endpoint de webhook (devuelve el secret whsec_ una vez) |
| delete | /v1/webhook-endpoints/{id} | Borra un endpoint |
| get | /v1/balance | Créditos disponibles, reservados y plan gratis |
| get | /v1/usage | Uso agregado por día y tipo |
| post | /v1/face-verifications/sessions | Abrir una sesión de captura (retos aleatorios) |
| post | /v1/face-verifications | Comparar una selfie con la foto de un documento |
| get | /v1/face-verifications/{id} | Consultar una verificación facial |
OpenAPI 3.1 · /openapi.json · 1.2.0
Next steps
Document types
Constaia's document type catalogue by category, with fields and validators; how to use expect with several types and generic with your own schema.
JavaScript and TypeScript SDK
Reference for @constaia/sdk on Node.js, Bun, Deno and edge runtimes. Installation, options, methods, errors, retries and webhook verification.