Constaia
Concepts

Storage and privacy

What Constaia keeps from your documents and for how long, with the review, none, temporary and persistent modes, review retention windows, keep_results, deletion, encryption and profiles.

Cette page n'est pas encore traduite dans votre langue. Voici la version anglaise.

By default we only store, encrypted, the documents that need human review, and delete them once a decision is made. Everything else is processed and discarded. You can choose never to store the file or, the other way round, to keep it longer, per request or as an account default.

Storage modes

Set them with the storage option of POST /v1/analyze (and of classifications and batches):

storageWhat happens to the file
review (default)Stored encrypted only if the analysis needs human review. Deleted once the review is decided (after a configurable margin) or, if nobody decides, after a maximum period. If no review is needed, it is deleted when the analysis finishes, just like none.
noneNever stored. Synchronous analysis: the file is processed in memory and never written to storage. Async or batch: it is stored encrypted only until the analysis finishes, then deleted. Human review will only see the extracted data, not the document.
temporaryStored encrypted and deleted automatically after ttl_hours hours (1 to 720; 24 by default).
persistentStored encrypted until you delete it with DELETE /v1/analyses/{id}.

If you don't send storage, your account default is used, which is review unless you changed it. Same with ttl_hours: the account's value or, if none, 24. Defaults are changed in the dashboard (Account settings).

Accounts created before this change

Accounts whose default was none move to review, unless the owner had changed the default storage by hand: in that case their choice is kept. If you want a flow to never store the document, send storage: "none" explicitly in those requests.

storage applies to the file. The results (type, verdict, fields) are kept so you can read them with GET /v1/analyses/{id}, unless you use keep_results: false.

When the document is kept in review mode

The original is kept, encrypted, when the analysis is pending human review:

  • The verdict is review (Constaia could not decide with confidence).
  • The verdict is invalid and your template asks for invalid documents to be reviewed by a person too.
  • The verdict is valid and your template asks for valid documents to be reviewed too (it doesn't approve them on its own).
  • There is no verdict (an unrecognized document without expect, or verdict_without_expect: false), but there are quality warnings that call for a look at the document: low_quality, blurry, cropped, glare, screen_photo_suspected, photocopy_suspected, edited_suspected, multiple_documents or side_missing.

A verdict computed without expect against the detected type (verdict.basis: "detected") follows the same rules as any other verdict. In any other case the file is deleted when the analysis finishes.

Retention windows

Two settings control how long a document pending review is kept:

SettingValuesDefaultWhat it does
review_retention_hours_after_decision0–720 hours24After the review is decided, the original is kept for these hours (so the decision can be checked) and then deleted. With 0 it is deleted as soon as it is decided.
review_max_days1–90 days30If nobody decides, the original is deleted N days after the analysis finished.

They are set for the whole account in the dashboard (Account settings) and, if you need to, in each template; the template's value takes precedence over the account's.

While the original is kept, your team can see it when reviewing in the dashboard and your backend can download it through the API: see Human review from your backend.

keep_results: false

With keep_results: false the extracted data is not kept either:

  • You get the full result once, in the response (or in the webhook if async).
  • Afterwards, GET /v1/analyses/{id} returns 404 resource_missing and the analysis does not appear in lists.
  • Constaia only keeps billing metadata: pages, credits and document type.
The bare minimum
{
  "file_url": "https://example.com/dni.jpg",
  "expect": "es_dni",
  "storage": "none",
  "keep_results": false
}

Hands-on guide: analyse without storing.

The storage object in the response

Every analysis tells you what happened to the file:

storage: review, pending review
"storage": { "mode": "review", "kept": true, "reason": "pending_review", "expires_at": "2026-10-29T10:00:02Z", "file_deleted_at": null }
storage: review, no review needed
"storage": { "mode": "review", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }
storage: none, synchronous analysis
"storage": { "mode": "none", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }
storage: temporary, ttl_hours: 72
"storage": { "mode": "temporary", "kept": true, "reason": null, "expires_at": "2026-10-02T10:00:02Z", "file_deleted_at": null }
FieldDescription
modeThe mode applied (none, review, temporary or persistent): the one you asked for, the template's or the account default.
kepttrue if the original is still stored right now.
reasonpending_review if it is kept because it awaits human review (review mode, not yet decided). null otherwise.
expires_atWhen the original will be deleted. null if it is not kept or with persistent. When a review is decided it becomes the decision time plus review_retention_hours_after_decision.
file_deleted_atWhen the file was deleted, or null if it is still stored. In none mode it matches the end of the analysis.

While kept is true, the analysis file_url field holds a signed URL to the original that expires after 15 minutes. Fetch the analysis again with GET /v1/analyses/{id} to get a fresh one, or download it with GET /v1/analyses/{id}/file.

Deleting an analysis

Terminal
curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"
Response
{ "id": "an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2", "object": "analysis", "deleted": true }

It deletes the file, the results and the exports of the analysis. It cannot be undone: afterwards GET returns 404. Use it, for example, when a user exercises their right to erasure.

Exports and downloads

  • The exports URLs are signed links that expire after 24 hours. After that they return 404. See exports.
  • Every download goes through https://api.constaia.com/v1/files/…. You never get a direct object storage URL.

Encryption and where data is stored

  • Application-level encryption before anything is written: AES-256-GCM with a separate key per account, derived from a master key. The storage provider only sees encrypted data.
  • Object storage in the EU: in production, Cloudflare R2 with EU jurisdiction (data is stored in EU data centres), which also encrypts at rest. Only the API server accesses it: none of your or your users' traffic goes to storage URLs; files and exports are always served through the API.
  • API keys: stored as a hash (SHA-256) and shown only once when created.
  • Webhook secrets: stored encrypted.
  • In transit: the whole API is served over HTTPS.

Where documents are processed (regions and AI providers) is covered in data residency.

Processing profiles: sovereign and standard

With the processing option you choose which AI providers may touch a document, per request. If you don't send it, your account's default profile is used (sovereign when a sovereign provider is available). The account default cannot be changed from the dashboard yet: send processing on each request or write to support@constaia.com.

ProfileAI providers it may use
sovereignOnly providers headquartered and operated in the EU: a European model (IONOS, Scaleway, OVHcloud) or a Constaia-hosted one, Mistral OCR (Paris) and the local MRZ and PDF417 readers.
standardThe above plus Claude on AWS Bedrock (Frankfurt, eu-central-1) or Gemini on Google Vertex AI (EU region).

About the standard profile

AWS and Google process the data in EU regions, but they are US-headquartered companies and therefore subject to US law such as the CLOUD Act. If that is a problem for your use case, use sovereign.

If the requested profile is not available, the API answers 422 processing_unavailable. The response includes which profile was applied and which providers processed the document:

Response
"processing": {
  "profile": "sovereign",
  "region": "eu",
  "mode": "vlm",
  "providers": [
    { "name": "tesseract", "region": "local", "role": "local", "model": "mrz" },
    { "name": "openai_compat", "region": "de-fra", "role": "llm", "model": "mistral-small-3.2" }
  ]
}

Each field is described in POST /v1/analyze.

The full list of sub-processors per profile is in the DPA.

Audit log and DPA

  • Constaia keeps an audit log of sensitive account actions (who, from which IP and what action).
  • The data processing agreement (DPA) is at /en/legal/dpa.

Next steps

Sur cette page