An invoice that passes today can fail tomorrow

Two data contracts — this is the one place we ever store a document

Every other endpoint on this service (/api/v1/validate, /api/v1/repair, /api/v1/validate/batch, the MCP tools) processes your upload in memory and discards it — see the privacy page. Monitoring is different, and deliberately so: an automatic recheck later needs something to recheck against, so POST /api/v1/watch requires you to say explicitly whether this one sample may be kept.

• "store_document": true — the sample's bytes are stored. When the ruleset changes, it is automatically re-validated and its status updates on its own.
• "store_document": false — only a fingerprint is stored (hash, verdict, fired rule codes), never the bytes. When the ruleset changes, this entry is marked needs_resubmit instead — you send the document again when you're ready.

Neither option is silent, and there is no default: omit store_document entirely and the request is rejected with a 400 explaining the choice.

Registering a sample

curl -X POST "https://api.facturecheck.eu/api/v1/watch?label=acme-template&store_document=true" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-binary @invoice.xml

Returns the new entry's id, its verdict at registration, and the rule codes that fired then — the baseline every future recheck is compared against.

Rechecking a sample

A stored sample can be rechecked on demand, with no body — it revalidates against its own saved bytes:

curl -X POST "https://api.facturecheck.eu/api/v1/watch/42/recheck" \
  -H "X-Api-Key: YOUR_API_KEY"

A fingerprint-only entry (store_document: false) has no saved bytes, so its recheck call takes the document in the body instead — the same shape as registration. Either way the response reports regressions (rule codes firing now that didn't at registration), resolved (rule codes that no longer fire), and whether the overall verdict changed.

Every stored sample under your key can be rechecked in one call with POST /api/v1/watch/recheck-all.

What happens automatically

At boot, the service compares the ruleset it is about to run against the last version it recorded. If they differ, every stored sample registered under the old version is automatically revalidated, and every fingerprint-only entry is marked needs_resubmit. This automatic sweep never spends any of your monthly quota — only a manual recheck/recheck-all call, or registering a new sample, does that (1 call each). GET /api/v1/ruleset-status is public and unauthenticated: it reports the current ruleset versions and when they last changed, with no API key required.

Limits

A stored sample is deleted immediately when you DELETE /api/v1/watch/{id}, and automatically after 12 months of no activity either way.