Constaia

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 URLhttps://api.constaia.com/v1
AuthenticationAuthorization: Bearer ck_live_… or ck_test_…. See Authentication.
FormatJSON with snake_case names. Files are uploaded with multipart/form-data or as file_url/file_base64 in JSON.
IdsPrefix + ULID: an_ (analysis), bat_ (batch), we_ (webhook endpoint), exp_ (export), req_ (request), msg_ (webhook delivery).
DatesISO 8601 in UTC.
Errors{ "error": { "type", "code", "message", "param", "request_id" } }. See Errors.
IdempotencyIdempotency-Key header on the analysis, classification and batch POSTs. See Idempotency.
PaginationCursor based with limit and starting_after; response with has_more. See Pagination.
LimitsPer API key: 10 requests per second by default, can be raised per account. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; on a 429, Retry-After. See Rate limits.
TracingX-Request-Id header on every response. Include it if you contact us about a problem.
CORSOpen on /v1, but keys must never be used from a browser.
VersioningVersion 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=constaia

Keep in mind when using a generated client:

  • In multipart/form-data, the options field is a JSON string, not an object. Serialise it yourself.
  • 202 responses return the same object as 200, with status queued or processing.
  • It does not include webhook verification: use the algorithm in Webhooks.
  • Add retries on 429 and 5xx yourself, honouring Retry-After, and send Idempotency-Key on POSTs.
  • Regenerate the client when the changelog announces new fields. Ignore unknown fields in your code.

Importing into Postman, Insomnia or Bruno

  1. Import the specification from the URL https://api.constaia.com/openapi.json (or download it and import the file).
  2. 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.
  3. In POST /v1/analyze, choose a form-data body: a file field of type file and an options text field with the JSON, for example {"expect":"es_dni"}.
  4. 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/analyzeAnaliza un documento y devuelve veredicto, campos y checks
post/v1/classifySolo clasifica el documento (0,2 créditos)
get/v1/analysesLista 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}/exportDescarga directa de una exportación
post/v1/batchesCrea un lote de hasta 100 documentos (siempre async)
get/v1/batches/{id}Estado de un lote
get/v1/document-typesCatálogo de tipos con campos y checks
get/v1/document-types/{type}Detalle de un tipo
get/v1/webhook-endpointsLista endpoints
post/v1/webhook-endpointsAlta de un endpoint de webhook (devuelve el secret whsec_ una vez)
delete/v1/webhook-endpoints/{id}Borra un endpoint
get/v1/balanceCréditos disponibles, reservados y plan gratis
get/v1/usageUso agregado por día y tipo

OpenAPI 3.1 · /openapi.json · 1.0.0

Next steps

POST /v1/analyze

The detailed reference of the main endpoint.

Errors

Every error code and how to handle it.

Rate limits

Requests per second, RateLimit headers and retries.

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.

On this page

ConventionsOfficial SDKsGenerating a clientImporting into Postman, Insomnia or BrunoEndpoint summaryNext steps