Quickstart

Create an accountCopy Anchor Link

Sign up at app.constaia.com/signup with your email or your Google or GitHub account (then your email is verified straight away). The free plan includes 150 credits per month and no card is required. Credits renew on the 1st (UTC). More in Pricing.

Just want to see what it returns? The website demo analyses a document with no account or key (5 a day, without storing the file).

Copy your test keyCopy Anchor Link

In the dashboard, go to API keys and copy the key that starts with ck_test_. Keys are shown only once: store it in your secrets manager.

Test keys never spend credits and return deterministic results based on the file name. Everything about this mode in Test mode.

Export the key as an environment variableCopy Anchor Link

export CONSTAIA_API_KEY="ck_test_..."

The official SDKs read CONSTAIA_API_KEY automatically. The key always stays on your server: never put it in browser code or a mobile app.

Prepare a test fileCopy Anchor Link

In test mode the result is chosen by the file name, but the content must be a real JPEG, PNG, WEBP, HEIC or PDF (the type is detected from the first bytes). Copy any photo and any PDF you have at hand with these names:

cp ~/Pictures/any-photo.jpg dni_valid.jpg
cp dni_valid.jpg dni_expired.jpg
cp dni_valid.jpg blurry.jpg
cp dni_valid.jpg nie.jpg
cp dni_valid.jpg passport.jpg
cp ~/Documents/any-document.pdf medical_certificate.pdf

A PDF's signature and metadata are analysed for real even in test mode: if your PDF was produced by Word, Canva or another editor, you'll see the edited_suspected warning and a review verdict. If that happens, use cp dni_valid.jpg medical_certificate.jpg. See Test mode.

Analyse an ID cardCopy 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"}'

Response (fields trimmed; size_bytes and timestamps depend on your file and the moment):

{
  "id": "an_01J...",
  "object": "analysis",
  "status": "completed",
  "livemode": false,
  "created_at": "2026-09-29T10:00:00Z",
  "completed_at": "2026-09-29T10:00:02Z",
  "file": { "name": "dni_valid.jpg", "mime_type": "image/jpeg", "pages": 1, "size_bytes": 482133 },
  "document": { "type": "es_dni", "label": "DNI (España)", "confidence": 0.97, "side": "both", "country": "ESP" },
  "verdict": {
    "expected": ["es_dni"],
    "match": true,
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "El documento es DNI (España)." },
      { "code": "not_expired", "severity": "info", "message": "Vigente hasta el 12/03/2031." }
    ]
  },
  "fields": {
    "document_number": {
      "value": "12345678Z",
      "confidence": 0.99,
      "validated": true,
      "source": { "page": 1, "bbox": [0.61, 0.12, 0.83, 0.16] }
    }
  },
  "checks": [
    { "code": "nif_check_digit", "passed": true, "message": "La letra del documento 12345678Z es correcta." },
    { "code": "mrz_checksums", "passed": true, "message": "Los dígitos de control de la MRZ son correctos." },
    { "code": "mrz_matches_visual", "passed": true, "message": "La MRZ coincide con los datos impresos." }
  ],
  "warnings": [],
  "signature": null,
  "exports": {},
  "storage": { "mode": "none", "file_deleted_at": "2026-09-29T10:00:02Z", "expires_at": null },
  "processing": {
    "profile": "sovereign",
    "region": "eu",
    "mode": "vlm",
    "providers": [{ "name": "mock", "region": "local", "role": "llm", "model": "mock-llm-1" }]
  },
  "usage": { "credits": 0, "pages": 1 },
  "metadata": {}
}

Messages default to Spanish. Add "language":"en" to the options to get "The document is Spanish ID card (DNI)." and "Valid until 12/03/2031.". Besides document_number, fields includes first_name (MARÍA), last_name_1 (GARCÍA), last_name_2 (LÓPEZ), sex, nationality, birth_date (1990-05-14), issue_date, expiry_date (2031-03-12), support_number, address, birth_place, parents and mrz, all with the same structure.

Note usage.credits: 0 (test mode) and storage.mode: "none": the file was not stored. signature is null because it is not a PDF, and processing tells you which providers handled it (in test mode, the simulated mock).

Verify your emailCopy Anchor Link

ck_live_ keys can only be created with a verified email, and free credits in live mode require it too (otherwise 402 email_not_verified). If you signed up with Google or GitHub, it already is.

Create a ck_live_ keyCopy Anchor Link

In the dashboard → API keys, create a production key. It is shown only once. Live analyses consume credits: first the month's 150 free credits and then those from the packs you buy. See Credits and billing.

Mind the free plan limits: 2 requests per second, 2 concurrent synchronous analyses and 60 pages per minute (10, 10 and 600 once you buy a pack). If you exceed them you get 429 with Retry-After; the SDKs already retry. See Rate limits.

Swap the environment variableCopy Anchor Link

No code changes needed: replace the value of CONSTAIA_API_KEY in your production environment with the ck_live_ key. Each mode's analyses are separate: listing with a live key only shows live analyses.

Set up production webhooksCopy Anchor Link

Webhook endpoints belong to the mode of the key you create them with. Create your endpoints again with the live key; see Webhooks.