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.
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):
storage | What 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. |
none | Never 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. |
temporary | Stored encrypted and deleted automatically after ttl_hours hours (1 to 720; 24 by default). |
persistent | Stored 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
invalidand your template asks for invalid documents to be reviewed by a person too. - The verdict is
validand 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, orverdict_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_documentsorside_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:
| Setting | Values | Default | What it does |
|---|---|---|---|
review_retention_hours_after_decision | 0–720 hours | 24 | After 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_days | 1–90 days | 30 | If 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}returns404 resource_missingand the analysis does not appear in lists. - Constaia only keeps billing metadata: pages, credits and document type.
{
"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": { "mode": "review", "kept": true, "reason": "pending_review", "expires_at": "2026-10-29T10:00:02Z", "file_deleted_at": null }"storage": { "mode": "review", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }"storage": { "mode": "none", "kept": false, "reason": null, "expires_at": null, "file_deleted_at": "2026-09-29T10:00:02Z" }"storage": { "mode": "temporary", "kept": true, "reason": null, "expires_at": "2026-10-02T10:00:02Z", "file_deleted_at": null }| Field | Description |
|---|---|
mode | The mode applied (none, review, temporary or persistent): the one you asked for, the template's or the account default. |
kept | true if the original is still stored right now. |
reason | pending_review if it is kept because it awaits human review (review mode, not yet decided). null otherwise. |
expires_at | When 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_at | When 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
curl -X DELETE https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
-H "Authorization: Bearer $CONSTAIA_API_KEY"{ "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
exportsURLs are signed links that expire after 24 hours. After that they return404. 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.
| Profile | AI providers it may use |
|---|---|
sovereign | Only 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. |
standard | The 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:
"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
Advanced privacy
Pixelated copy, masked fields, deletion by metadata and retention.
Data residency
Where documents are processed and stored.
Analyse without storing
storage none and keep_results false in practice.
Human review from your backend
List pending reviews, download the original and decide through the API.
Security
Keys, webhooks and good practices.
Exports
Signed links that expire after 24 h.
Pagination
How to walk Constaia API lists with cursor pagination (limit and starting_after) and filters by status, type and metadata, with code examples.
Advanced privacy
Pixelated copy of the document with redact, masked fields with mask_fields, deletion and export by metadata (rights to erasure and access) and result retention per template or account.