API Reference

Status: This is the active and only public API surface. (The legacy versioned API has been retired.) Owner: Branko · Last reviewed: 2026-06-23 Source of truth: app/api/v2/** route handlers + this file. Taxonomy tables auto-generated from the database via tsx scripts/generate-taxonomy-docs.ts.

Machine-readable spec. An OpenAPI 3.1 description of every endpoint (incl. webhooks) is published as /openapi-v2.yaml and /docs/openapi.json. Import either into Postman or Insomnia, or feed it to an OpenAPI client generator (e.g. openapi-generator) to scaffold a typed client. The spec is hand-maintained, Redocly-linted in CI, and guarded against endpoint drift by a contract test (e2e/contracts/openapi-spec.spec.ts) that fails if a route and the spec disagree. This document remains the authoritative reference for semantics, vocabularies and examples.

Table of contents

1. Quick Start
2. API Scope
3. Authentication & Rate Limits
4. Classification Model
5. Documents — read
6. Documents — write
7. Documents — upload
8. Taxonomy
9. Usage
10. Search
11. Output Profiles
12. Webhooks
13. Feedback
14. Error codes
15. Troubleshooting
16. Changelog

Quick Start

Get from zero to a delivered webhook in five steps.

1. Get an API key

A platform SuperAdmin creates your organization in the iDMS dashboard and assigns you as Org Admin. Then go to Settings → API Keys and create a key. The plaintext is shown once — copy it immediately. Keys live in idms_… format and are scoped to your organization.

2. Authenticate

Send the key on every request as a Bearer token:

curl -H "Authorization: Bearer idms_…" \
     https://idms.mory.ai/api/v2/documents

3. Upload a document (with idempotency)

Use external_id as a stable client-side identifier so retries don't create duplicates:

curl -X POST https://idms.mory.ai/api/v2/documents/upload \
     -H "Authorization: Bearer idms_…" \
     -F "file=@invoice-001.pdf" \
     -F "external_id=client-system-2024-1041"

Second call with the same external_id returns the existing document with meta.idempotent_replay: true — no 409, no duplicate document.

4. Subscribe to a webhook

In Settings → Webhooks, register your endpoint and check the events you want. Webhooks are POSTed with Content-Type: application/json, an X-IDMS-Signature header (HMAC-SHA256, hex), and an X-IDMS-Event header.

// Express — verify over the RAW body, constant-time. See Webhooks → Verifying the signature.
import crypto from "node:crypto";
app.post("/idms-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.IDMS_WEBHOOK_SECRET)
    .update(req.body)                         // req.body is the raw Buffer, not parsed JSON
    .digest("hex");
  const sig = req.headers["x-idms-signature"];
  const ok = sig && crypto.timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body.toString());  // parse only AFTER verifying
  // ... handle event.event
  res.status(200).end();
});

5. Handle the document.processed event

When the AI pipeline finishes, your endpoint receives:

{
  "event": "document.processed",
  "timestamp": "2026-06-07T08:00:00.000Z",
  "document_id": "550e8400-…",
  "external_id": "client-system-2024-1041",
  "filename": "invoice-001.pdf",
  "doc_type": "invoice",
  "doc_subtype": "service_invoice",
  "tags": ["plumbing"],
  "extracted_metadata": { "betrag": "256.74", "currency": "CHF", "iban": "CH93 …" }
}

That's it. Pull the document state from GET /api/v2/documents/{document_id} if you need more than the webhook carries.

API Scope

This is a read + write + upload API with the current classification model: endpoints for reading documents with the full classification surface, PATCH endpoints for manual corrections, idempotent upload, per-client output profiles, and five webhook event types. All routes live under /api/v2/*.

Highlights:

• Richer taxonomy: 8 Bereiche, 31 document types, 121 subtypes, 13 intents, 10 tag groups, 54 tags — beside the flatter legacy 16-type vocabulary still surfaced in the top-level fields. (See Classification Model for the full reference.)
• Structured contact extraction: Person / Firma (company) entities automatically extracted, deduplicated across the org, linked to documents with a role (absender / empfaenger / cc).
• Write operations: PATCH for classification / metadata / contacts / tags + bulk PATCH + tag add/remove — every write goes into an append-only audit log.
• Idempotent upload: repeated external_id or repeated content hash returns the existing document; no 409 on duplicate filename (designed for high-volume bulk ingestion of 200 000+ files).
• Delta sync: GET /api/v2/documents?updated_since=<ts> plus the meta.server_time cursor lets you poll only what changed.
• Output profiles: per-client output renderers (configurable per-tenant routing rules; the profile key is provisioned by your account manager).
• Lock semantics: documents in abgeschlossen / finalized / deleted reject writes with 400 DOCUMENT_LOCKED. Reads always succeed.
• 6 webhook event types (4 opt-in events: document.failed, classification.changed, tag.suggested, usage.threshold.reached) with an HMAC-SHA256 envelope.

Authentication & Rate Limits

One key pool, one set of limits — the API key from Settings → API Keys works on every /api/v2/* endpoint with no extra setup.

• Auth header: Authorization: Bearer idms_<api_key>.
• Org-scoped: A key can only see and modify documents in its own organization. Cross-org lookups return 404, never 200 with foreign data.
• Rate limit: 100 requests/minute per key (rolling window, Supabase-backed since 2026-06-06 — survives deploys).
• Rate limit headers (on every response, including 429):
  • X-RateLimit-Limit: 100
  • X-RateLimit-Remaining: <int>
  • X-RateLimit-Reset: <unix seconds>

Classification Model

Field-name note. Some JSON field names carry a _v3 suffix — document_classification_v3, intent_v3, v1_projection. Treat that suffix purely as a stable contract identifier, not an API version: a field named with _v3 belongs to the current classification model, and v1_projection maps each value back to the legacy 16-type taxonomy that the API still surfaces unchanged. The suffix never changes, so you can hard-code these field names safely. The rest of this document just calls it "the classification model."

Opt-in per organization

The classification model is opt-in per organization. By default an org runs the legacy extractor — the legacy model is the safe default so existing integrations never get a surprise upgrade. Opting in flips the org to the current model and adds the richer fields to every new document.

What your integration sees depends on your org's flag:

If your client code only reads the top-level fields, you'll see the legacy vocabulary regardless of opt-in — that's the backward-compat surface. To consume the richer model, read from the nested document_classification_v3 object. The mapping back to the legacy vocabulary for every current-model value is the v1_projection column in the taxonomy tables further down.

How to opt in. Contact your account manager. We flip a config flag and run a one-off reclassifier over your existing documents so the nested document_classification_v3 rows appear retroactively. No code change on your side — the surface stays the same, the nested object just becomes non-null.

Already opted in. A number of production organizations are already running the current model; the rest stay on the legacy default until they opt in as described above.

The model defines four orthogonal dimensions every document is classified across, plus a top-level Bereich for human-readable grouping in dashboards and reports.

The four dimensions

Plus structured extracted fields common to every document: status_lifecycle, zahlungsstatus, betrag, currency, date_issued, booking_date, vat_rate, due_date, iban, signature, and linked entities (Bezüge) — property, unit, equipment.

Bereich grouping

A Bereich (area / domain) is purely a navigational grouping — the AI picks exactly one doc_type, and that type belongs to exactly one bereich. The 8 Bereiche cover the real-estate management domain (Finanzen / Finance, Beschaffung / Procurement, Verträge / Contracts, Immobilie / Property, Korrespondenz / Correspondence, Personal / HR, Vermarktung / Marketing, Auffang / Catch-all).

German enum glossary

Several enum values stay German on the wire because they originated from the Swiss property-management domain and are stable contract identifiers — renaming them would break every integrator. Labels and surrounding prose are translated; the values themselves are not. The table below is the canonical mapping between the German wire values and their English meaning.

These values are German because they reflect the Swiss real-estate domain vocabulary that originated this dataset; they are stable contract identifiers and will not be renamed even as labels and prose get English translations.

Auto-generated from the taxonomy reference tables — DO NOT EDIT BY HAND. Run tsx scripts/generate-taxonomy-docs.ts to refresh after a taxonomy migration. Current sizes: 8 bereiche, 31 doc_types, 121 doc_subtypes, 13 intents, 10 tag_groups, 54 tags.

Document types — grouped by Bereich

Bereich: Finanzen & Zahlungsverkehr / Finance & Payments (finanzen)

Bereich: Beschaffung & Verkauf / Procurement & Sales (beschaffung)

Bereich: Verträge & Recht / Contracts & Legal (vertraege)

Bereich: Immobilie & Bau / Property & Construction (immobilie)

Bereich: Korrespondenz & Organisation / Correspondence & Operations (korrespondenz)

Bereich: Personal & Firma / HR & Company (personal)

Bereich: Vermarktung / Marketing (vermarktung)

Bereich: Auffang / Catch-all / Fallback (auffang)

Intents

Tag groups and tags

Anlagen & Gebäudeteile / Installations & Building Components (anlagen_gebaeudeteile)

Hausdienste / Building Services (hausdienste)

Sicherheit / Safety (sicherheit)

Energie & Versorgung / Energy & Utilities (energie_versorgung)

Finanzen / Finance (finanzen)

Recht & Verwaltung / Legal & Administration (recht_verwaltung)

Mieter & Mietverhältnis / Tenancy & Lease (mieter_mietverhaeltnis)

Bau & Renovation / Construction & Renovation (bau_renovation)

Personal & Firma / HR & Company (personal_firma)

Verkauf & Einkauf / Sales & Procurement (verkauf_einkauf)

Status lifecycles

Two enum-valued fields ride alongside the classification axes. Both are writable through the PATCH endpoints and seeded by the AI pipeline.

status_lifecycle

zahlungsstatus (only meaningful for Finanzen Bereich docs)

Mapping the current model → the legacy vocabulary for backward compatibility

Every doc_type and intent row in the reference tables carries a v1_projection column so legacy-vocabulary receivers can interpret a classification from the current model. Read responses also surface the original legacy columns (doc_type, doc_subtype, doc_intent) alongside the current-model fields — see Documents — read.

Documents — read

All read endpoints share the standard envelope { data, meta, error } and the rate-limit headers above.

GET /api/v2/documents

List documents in the caller's organization, with the current classification fields nested alongside the legacy envelope.

Query parameters (all optional):

The amount and due-date filters are all optional and combinable with every other filter. Parsing is server-side; a document whose stored due date is calendar-invalid is treated as a non-match rather than causing an error.

Example:

curl -H "Authorization: Bearer idms_..." \
     "https://idms.mory.ai/api/v2/documents?doc_type=invoice&zahlungsstatus=offen&tag=plumbing"

Returns paginated data: [...] with meta: { page, per_page, total, total_pages, server_time }. server_time is the server's query time (ISO-8601 UTC) — for delta sync, save it and pass it as the next updated_since so no change is missed between polls. Each row has the legacy envelope fields plus document_classification_v3, document_tags, document_tags_v3.

GET /api/v2/documents/:id

Retrieve the full document with the legacy envelope, the full classification record, structured metadata, related contacts, and linked entities — property / unit / equipment (Bezüge).

Returns the same row shape as the list endpoint, plus a contacts: [...] array of normalized Person/Firma entities each with their role (absender / empfaenger / cc) — full field reference under GET /api/v2/documents/:id/contacts.

Extracted entity fields (top-level on every document row; each is null / [] when the document doesn't reference one):

sender / receiver / related_contacts are lightweight extraction snapshots embedded in the document row. The org-level deduplicated contact records (with emails, phones, registry numbers, …) live on the contacts array / endpoint below.

When called with ?profile=…, the response is rewritten per that profile — see Output Profiles.

GET /api/v2/documents/:id/contacts

Standalone contacts list for one document. Identical data to the embedded contacts array on the detail endpoint — separated so clients can refresh just the contacts without re-pulling the full body.

Contact object fields:

{
  "data": [
    {
      "id": "f7a34862-122b-4d45-b89c-836a9d715f28",
      "kind": "person",
      "role": "empfaenger",
      "name": "Christian Käppen",
      "first_name": "Christian",
      "last_name": "Käppen",
      "salutation": "Herr",
      "date_of_birth": "1981-08-16",
      "email": "c.kaeppen@example.ch",
      "emails": ["c.kaeppen@example.ch"],
      "phone": null,
      "phones": [],
      "address": "Ledergasse 11, 6004 Luzern",
      "website": null,
      "vat_number": null,
      "hr_number": null,
      "external_id": null
    }
  ]
}

Contact id stability: contacts are deduplicated org-wide; when duplicates are merged, the surviving contact keeps its id and the merged duplicates' ids disappear. Treat document_id as your stable key and re-fetch contacts rather than persisting contact_id long-term. Document ids never change.

GET /api/v2/documents/:id/download

Returns a short-lived signed URL that points at the document's original file bytes on Supabase Storage. The bytes never travel through this API — the client follows the URL directly to Storage (CDN-fronted, no extra auth).

Why a signed URL instead of streaming the bytes: avoids the serverless function duration ceiling on large downloads, keeps the function cheap, and lets the client hand the URL to any download tool unchanged.

Query params

Response (200)

{
  "data": {
    "url": "https://<project>.supabase.co/storage/v1/object/sign/documents/...",
    "expires_at": "2026-06-08T15:30:00.000Z",
    "filename": "rechnung-q3.pdf",
    "content_type": "application/pdf",
    "file_size": 1842
  },
  "meta": { "ttl_seconds": 3600 },
  "error": null
}

Client flow

url=$(curl -sS -H "Authorization: Bearer $IDMS_API_KEY" \
        "$IDMS_BASE_URL/api/v2/documents/$DOC_ID/download" | jq -r .data.url)
curl -o "$DOC_ID.pdf" "$url"

Errors

Cross-org isolation: the lookup is scoped by both id AND organization_id. A key from one org asking for a document that belongs to another org receives 404, not 403 — existence is never disclosed.

Sammel-PDF caveats (relevant only if the document went through A2 split):

• Container rows (is_container = true) point at the original multi-document PDF — caller receives the whole bundle.
• Child rows (source_document_id != null) share the parent's storage_path — caller receives the same bundle. The per-segment text lives in extracted_content on the child row and is already exposed through GET /api/v2/documents/:id; the original file is not re-encoded per child.

Documents — write

All PATCH endpoints:

• Require the same Bearer-token auth as reads.
• Are idempotent — re-sending the same payload yields the same end state.
• Reject with 400 DOCUMENT_LOCKED when the document's status_lifecycle is abgeschlossen / finalized / deleted. Reads still succeed.
• Capture an audit row in document_audit_log (actor, IP, prev/next snapshots, optional reason).
• Return the full updated detail in the same shape as the corresponding GET.

Only the top-level PATCH /api/v2/documents/:id fires classification.changed webhook events — one per touched axis (see Webhooks). The sub-resource (/classification, /metadata, /tags) and bulk endpoints update the record and write the audit row but do not emit the event.

PATCH /api/v2/documents/:id

Atomic top-level correction. Update classification axes and tags in one call.

{
  "doc_type": "rechnung",
  "doc_subtype": "service_invoice",
  "doc_bereich": "finanzen",
  "intent": "payment_required",
  "status_lifecycle": "in_bearbeitung",
  "zahlungsstatus": "bezahlt",
  "tags": ["plumbing", "heating"],
  "reason": "Manual correction after operator review"
}

All fields optional. Tags are replaced (final array = desired state). Unknown taxonomy keys return 422 — see Error codes.

PATCH /api/v2/documents/:id/classification

Fine-grained classification + tag UPSERT. Same body shape as the top-level PATCH but scoped to the classification axes. Useful when you want a separate audit row for classification-only edits.

PATCH /api/v2/documents/:id/metadata

MERGE update of document_classification_v3.extracted_metadata (JSONB). Specified keys overwrite, keys with null are deleted, unspecified keys remain. The legacy documents.extracted_metadata is not touched.

{
  "reference_number": "RG-2026-001-CORRECTED",
  "betrag": "215.50",
  "due_date": "2026-07-10",
  "qr_verified": null,
  "reason": "Corrected per supplier clarification"
}

PATCH /api/v2/documents/:id/contacts

REPLACE the document's contact link rows. Payload is the desired final state — links not in the payload are deleted, new links are inserted, identical links unchanged.

{
  "contacts": [
    { "contact_id": "contact-uuid-1", "role": "absender" },
    { "contact_id": "contact-uuid-2", "role": "absender" }
  ],
  "reason": "Added secondary sender contact"
}

Anti-spoof: every contact_id is verified to belong to the caller's organization — out-of-org → 400 (same shape as "unknown contact" so no RLS leak).

POST /api/v2/documents/:id/tags

Add one or more tags from the controlled taxonomy to the document. Body shape: { "tags": ["plumbing", "heating"] }. Idempotent UPSERT with confidence = 1 (manual sentinel). Unknown tag → 422. Optional X-Audit-Reason header attaches a reason to the audit row.

DELETE /api/v2/documents/:id/tags

Remove one or more tags. Body shape: { "tags": ["plumbing"] }. Silent no-op when the tag isn't present (idempotent).

PATCH /api/v2/documents (bulk)

Up to 100 items per request. Each item is processed independently — one bad item never aborts the rest.

{
  "items": [
    { "id": "<doc-1>", "doc_type": "rechnung", "tags": ["plumbing"], "reason": "..." },
    { "id": "<doc-2>", "zahlungsstatus": "bezahlt" }
  ]
}

Returns per-item result with status: "ok" | "error" and meta: { total, ok, error }.

Documents — upload

POST /api/v2/documents/upload

Upload a single file with content-hash + external_id idempotency. Designed for high-volume bulk ingestion (200 000+ files): repeated filenames are NOT a duplicate signal — only external_id and content hash are.

Multipart fields:

Size limit: 4 MB per file. Our serverless runtime caps multipart request bodies at 4.5 MB before they reach this handler — that limit is platform-level and not application-configurable. We pin the application-level limit to 4 MB so the descriptive 413 from this endpoint surfaces before the generic infrastructure 413. Pre-validate file size client-side before posting.

Files larger than 4 MB must use the presigned upload flow described below — that path streams directly to storage and lifts the per-file limit to 250 MB.

Idempotency / dedup decision:

upload request
     │
     ▼
external_id provided?
     │ yes              │ no
     ▼                  │
SELECT (org, ext_id)    │
     │                  │
   found?               │
     │ yes              │
     ▼                  │
return existing         │
meta.idempotent_replay  │
  = true,               │
dedup_by = "external_id"│
     │ no               │
     └────────┬─────────┘
              ▼
        compute sha256(content)
              │
              ▼
        SELECT (org, content_hash)
              │
            found?
              │ yes
              ▼
        return existing
        meta.idempotent_replay = true,
        dedup_by = "content_hash"
              │ no
              ▼
        ── CREATE PATH ──
        - upload to storage with 8-byte random suffix
        - INSERT document (content_hash, external_id, original filename)
        - audit log: action="upload_created"
        - trigger pipeline in background
        - return 200, meta.idempotent_replay = false

Response shape:

{
  "data": {
    "id": "550e8400-…",
    "filename": "invoice-001.pdf",
    "status": "pending",
    "file_type": "pdf",
    "file_size": 184320,
    "external_id": "client-system-2024-1041",
    "content_hash": "a1b2…",
    "created_at": "2026-06-07T10:30:00.000Z"
  },
  "meta": { "idempotent_replay": false },
  "error": null
}

On replay, data is the existing document and meta = { idempotent_replay: true, dedup_by: "external_id" | "content_hash" }.

Repeated filenames are accepted — deduplication is by external_id / content_hash, never by filename.

force=true (testing aid): bypasses the content-hash check and creates + processes a fresh document even for identical bytes. Two consequences, by design: (1) the forced row is stored without a content hash, so it never participates in future content dedup — the original document keeps winning; (2) force cannot reuse an existing external_id (400) — send a new one or omit it. The response carries meta: { idempotent_replay: false, forced: true }. Also accepted as a JSON field on /upload/finalize. Don't use it in production ingestion — it defeats the duplicate protection.

ZIP container upload

POST /api/v2/documents/upload also accepts a single .zip container through the same multipart file field (detected by .zip extension or a ZIP MIME type). Each entry inside the archive becomes its own document with its own idempotency.

Container rules:

• One nesting level only — entries that are themselves .zip files are rejected per-entry (nested_zip_not_supported), never unpacked.
• Max 50 entries per archive — larger archives are rejected wholesale.
• Each entry must satisfy the regular per-file size and type contract.
• The container itself also counts against the 4 MB multipart cap — use presigned upload + individual files for bigger loads.
• With external_id on the request, each entry gets "{external_id}:{entry_filename}" as its own idempotency key.

Per-entry response — the endpoint returns one item per archive entry instead of one document:

{
  "data": {
    "container_kind": "zip",
    "container_filename": "belege_2026_06.zip",
    "items": [
      { "kind": "accepted", "id": "…", "filename": "rechnung_01.pdf", "status": "pending", "rejected_reason": null },
      { "kind": "idempotent_replay", "id": "…", "filename": "rechnung_02.pdf", "status": "completed", "rejected_reason": null },
      { "kind": "rejected", "id": null, "filename": "~$rechnung_03.docx", "rejected_reason": "office_lock_file" }
    ]
  },
  "meta": { "container_kind": "zip", "total_entries": 3, "accepted": 1, "idempotent_replay": 1, "rejected": 1 }
}

Per-entry rejected_reason values:

Container-level failures (whole archive, persisted as ONE failed document row so a subscribed document.failed webhook fires once): container not readable (corrupt/not a ZIP) and too many entries.

Note: standalone (non-container) uploads of Office lock files are rejected up front with 400 on both multipart /upload and presigned /upload/init.

Presigned upload — up to 250 MB

For files larger than the multipart /upload cap of 4 MB, use the two-step presigned flow below — the file content streams directly to Supabase Storage and never touches our API function. (Multipart /upload is capped at 4 MB because our serverless runtime rejects request bodies over 4.5 MB before the handler runs — platform limit, not application-configurable.)

The presigned flow works for any file size up to 250 MB (matches the storage bucket's file_size_limit). Files over 250 MB are not supported — contact us if you have a use case.

POST /api/v2/documents/upload/init

Request a signed PUT URL for the upload. Accepts JSON; no file bytes here.

Request:

{
  "filename": "invoice-001.pdf",
  "file_size": 12345678,
  "mime_type": "application/pdf",
  "external_id": "client-system-2024-1041",
  "metadata": { "source": "scan-batch-12" }
}

Response (new):

{
  "data": {
    "upload_url": "https://<project>.supabase.co/storage/v1/object/upload/sign/documents/<path>?token=…",
    "upload_token": "eyJ…",
    "storage_path": "<org_id>/<safe>-<random>.pdf",
    "expires_at": "2026-06-10T09:30:00.000Z"
  },
  "meta": { "idempotent_replay": false },
  "error": null
}

Response (idempotent on external_id):

{
  "data": { "id": "550e8400-…", "filename": "invoice-001.pdf", "status": "completed", … },
  "meta": { "idempotent_replay": true, "dedup_by": "external_id" },
  "error": null
}

On idempotent hit there is no upload URL — the caller must not upload again. The existing document is returned verbatim.

Step 2 — PUT the file content

curl -X PUT "<upload_url>" \
     --data-binary "@invoice-001.pdf" \
     -H "Content-Type: application/pdf"

The signed URL is valid for 2 hours. If it expires, call /upload/init again with the same external_id and we'll issue a fresh URL (or return the existing doc if a parallel finalize already completed).

Alternatively, with the @supabase/supabase-js SDK:

await supabase.storage.from("documents").uploadToSignedUrl(storage_path, upload_token, file);

POST /api/v2/documents/upload/finalize

Once the PUT succeeds, register the document.

Request:

{
  "storage_path": "<from init response>",
  "filename": "invoice-001.pdf",
  "mime_type": "application/pdf",
  "file_size": 12345678,
  "external_id": "client-system-2024-1041",
  "content_hash": "a1b2…",
  "metadata": { "source": "scan-batch-12" }
}

Response: identical shape to /upload ({ data: documents_row, meta: { idempotent_replay, dedup_by? } }).

Errors:

Idempotency order: external_id → content_hash → insert. Either hit returns the existing document and does not touch the just-uploaded storage object. (Orphaned storage objects from never-finalized init calls are swept by a separate cleanup job; do not rely on this for correctness — finalize what you init.)

POST /api/v2/documents/upload/batch

Up to 50 files per request. Each item runs the same idempotency rules independently.

Multipart fields:

Response shape:

{
  "data": [
    { "index": 0, "status": "created", "doc": { … } },
    { "index": 1, "status": "idempotent_replay", "doc": { … }, "dedup_by": "external_id" },
    { "index": 2, "status": "failed", "error": "Unsupported file type: image/heic" }
  ],
  "meta": { "total": 3, "created": 1, "idempotent_replay": 1, "failed": 1 },
  "error": null
}

One bad item never aborts the rest. Each successful item (created or replay) writes one audit row.

Taxonomy

GET /api/v2/taxonomy

Returns the full taxonomy (bereiche, doc_types with v1_projection, doc_subtypes with parent type, intents with v1_projection, tag_groups, tags). German labels included. The taxonomy is global today; per-org overrides will fold in transparently when shipped.

Useful for rendering dropdowns and filter pickers without hardcoding values that may grow.

Usage

GET /api/v2/usage

Returns a usage snapshot for your organization (the org the API key belongs to). Read-only. Authenticated with your API key as a Bearer token, like every other endpoint — the org is always taken from the key, never from the request.

The period defaults to the current calendar month, month-to-date (UTC). Pass ?period=YYYY-MM to read a past month (e.g. ?period=2026-03); period_start is echoed back so the window is unambiguous. A malformed period returns 400.

api_calls.by_route for the current month comes from request telemetry that has 90-day retention. Past months are served from a durable monthly rollup, so per-route history for older months stays available beyond the 90-day window. The source field reports which: "live" (current month) or "rollup" (a past month).

# current month
curl -H "Authorization: Bearer idms_..." \
     https://idms.mory.ai/api/v2/usage

# a specific past month
curl -H "Authorization: Bearer idms_..." \
     "https://idms.mory.ai/api/v2/usage?period=2026-03"

Response:

{
  "data": {
    "period_start": "2026-06-01T00:00:00.000Z",
    "source": "live",
    "api_calls": {
      "this_period": 1432,
      "by_route": [
        { "route": "/api/v2/documents", "request_count": 980, "last_seen": "2026-06-19T17:42:11Z" },
        { "route": "/api/v2/documents/:id", "request_count": 452, "last_seen": "2026-06-19T17:40:02Z" }
      ]
    },
    "documents": { "total_stored": 21043, "ingested_this_period": 318 },
    "storage": { "bytes_used": 48210334720 },
    "remaining": { "rate_limit": 97, "rate_limit_reset": 1750352580 },
    "limits": { "documents_max": null, "api_calls_max": null }
  },
  "meta": null,
  "error": null
}

• source is "live" for the current month (raw telemetry, 90-day retention) or "rollup" for a past month (durable monthly aggregate that outlives the 90-day window).
• documents.total_stored and storage.bytes_used are point-in-time (current totals), not reconstructed for a historical period. documents.ingested_this_period and api_calls.* are scoped to the requested month.
• remaining.rate_limit / rate_limit_reset mirror the X-RateLimit-* response headers (requests left in the current minute window, and the reset time as a Unix timestamp).
• limits.* are null today, meaning unlimited — placeholders for future per-org quotas.
• Errors use the standard envelope ({ "data": null, "error": { … } }): 401 for a missing or invalid API key, 429 when the per-key rate limit is exceeded — see Error codes.

Search

POST /api/v2/search

Search your organization's documents by meaning and by keyword in a single call. The query is matched two ways — a semantic leg that understands paraphrase and synonyms (so "Mietzinserhöhung" also surfaces "Anpassung des Mietzinses"), and a keyword leg for exact strings like invoice numbers, names or references. The two result sets are fused (reciprocal-rank fusion) into one ranked list, and matched_via tells you which leg(s) surfaced each hit. Read-only; the org is always taken from your API key.

Availability is per organization. If search is not enabled for your org the endpoint returns 403 — contact us to enable it.

Request (JSON):

Response 200:

{
  "data": [
    {
      "document_id": "6e27ff62-790a-44e6-9ed5-7d689cbc7602",
      "filename": "Mietzinsanpassung_2024.pdf",
      "doc_type": "letter",
      "score": 0.032266,
      "snippet": "…Anpassung des Mietzinses per 1. April 2024 gemäss Referenzzinssatz…",
      "chunk_index": 2,
      "matched_via": ["semantic", "keyword"]
    }
  ],
  "meta": { "query_id": "…", "mode": "hybrid", "took_ms": 214, "total": 1 },
  "error": null
}

• score is the fused relevance score (higher is better); use it for ordering, not as an absolute threshold.
• snippet is the passage centered on the first query-term match (≤ 280 chars, … marks truncation), with matched query terms wrapped in <mark>…</mark>. The text is HTML-escaped, so the field is safe HTML; strip the tags if you want plain text.
• matched_via is an array containing "semantic", "keyword", or both.
• meta.mode reports the mode that actually ran — a hybrid request stays available even if the semantic component is briefly unavailable, in which case it transparently returns keyword-only results and meta.mode is "keyword".

Errors: 400 missing/invalid query; 401 invalid/missing API key; 403 search not enabled for your organization; 429 rate limit (100/min, shared with all API calls); 503 for an explicit mode:"semantic" request while the semantic component is temporarily unavailable (a hybrid request degrades to keyword instead).

Example:

# Hybrid (default) — meaning + keyword, fused:
curl -X POST https://idms.mory.ai/api/v2/search \
  -H "Authorization: Bearer idms_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "Mietzinserhöhung 2024", "limit": 5 }'

# Restrict to a type and a date window:
curl -X POST https://idms.mory.ai/api/v2/search \
  -H "Authorization: Bearer idms_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "Heizkostenabrechnung", "doc_type": "invoice", "created_after": "2024-01-01" }'

POST /api/v2/search/answer

Optional (search phase 3). Runs the same hybrid search as POST /api/v2/search, then asks an LLM to synthesize a natural-language answer over the top matching excerpts, with every factual claim cited inline ([1], [2], …). sources lists only the excerpts the model actually cited — a citation number the model invents never produces a fabricated entry, and excerpts it never cites are simply omitted. Read-only; the org is always taken from your API key.

Availability is per organization, and separate from plain search — enabling POST /api/v2/search does not enable this endpoint. If answer synthesis is not enabled for your org, it returns 403 — contact us to enable it.

The LLM call runs on the same EU/CH-compliant (Switzerland North) provider the rest of the AI pipeline uses — no document text leaves the same residency boundary as classification.

Request (JSON) — same filters as POST /api/v2/search (doc_type, bereich, intent, tags, created_after, created_before, sender, receiver, property), plus:

Response 200:

{
  "data": {
    "answer": "The rent is CHF 1800 [1] and additional costs are CHF 150 [2].",
    "sources": [
      { "marker": "[1]", "document_id": "6e27ff62-790a-44e6-9ed5-7d689cbc7602", "chunk_index": 0, "filename": "Mietvertrag.pdf" },
      { "marker": "[2]", "document_id": "8f31aa11-2222-4a9c-9c1e-1234567890ab", "chunk_index": 1, "filename": "Nebenkosten.pdf" }
    ]
  },
  "meta": { "query_id": "…", "mode": "hybrid", "took_ms": 640, "chunks_used": 2 },
  "error": null
}

• answer cites every claim inline; if the matching documents don't contain enough information, the answer says so instead of guessing.
• sources mirrors only the citation markers present in answer — never a fabricated reference.
• meta.chunks_used is 0 when no documents matched the query; in that case answer is a fixed "no information" message and no LLM call is made.

Errors: 400 missing/invalid query; 401 invalid/missing API key; 403 answer synthesis not enabled for your organization; 429 rate limit (100/min, shared with all API calls); 503 the LLM provider is temporarily unavailable (or an explicit mode:"semantic" request while the semantic component is down).

Example:

curl -X POST https://idms.mory.ai/api/v2/search/answer \
  -H "Authorization: Bearer idms_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "Wie hoch ist der Mietzins?", "limit": 3 }'

Output Profiles

A profile is a per-org renderer applied to read responses. Pass ?profile=<name> to GET /api/v2/documents or GET /api/v2/documents/:id and the server rewrites the response shape.

Two profile types ship today:

Generic profile — JSONB config in output_profiles.fields:

{
  "renamed": { "doc_type": "Belegart", "intent": "Absicht" },
  "excluded": ["storage_path"],
  "tag_groups_included": ["maintenance", "utility", "legal"],
  "required_fields": ["Belegart", "Daten"],
  "fallback_label": "Sonstiges"
}

Built-in 4-level routing profiles — for integrations whose target system uses a fixed taxonomy of folders + templates + sub-templates, the API ships routing engines that map our classification to verbatim names in the target system. Example response shape (profile keys like acme_v1 are provisioned per client by your account manager):

GET /api/v2/documents/<id>?profile=<profile_key>

{
  "data": {
    "id": "550e8400-…",
    "modul": "Belege",
    "ordner": "EK Einkauf",
    "template": "EK Rechnung",
    "belegart": "Default",
    "direction": "eingehend",
    "buchungsrelevant": false,
    "rule_id": "rechnung_eingehend",
    "used_fallback": false,
    "ou": { "short_name": "TENANT.001", "full_name": "Tenant 001 (Property Management)" },
    "status_set": "default_documents",
    "status": "neu",
    "required_fields": ["Subject", "Buchungsdatum", "Rechnungsdatum", "Periode"],
    "fields": { "betrag": "256.74", "iban": "CH93 …" },
    "contacts": [ … ]
  },
  "meta": {
    "profile": { "id": "<uuid>", "name": "<profile_key>" },
    "routing_rule": "rechnung_eingehend",
    "missing_required_fields": ["Buchungsdatum", "Periode"]
  },
  "error": null
}

Caller-supplied overrides on a routing profile: ?direction=eingehend|ausgehend|neutral and ?buchungsrelevant=true|false let you force the routing decision without changing the document content.

Profiles are configured server-side per org via the output_profiles table (is_default controls the default when ?profile= is omitted). Without a configured profile, the API returns the raw classification row shape. Ask your account manager for the profile key provisioned for your tenant.

Webhooks

Webhooks are POSTed to the URL you register in Settings → Webhooks, with:

• Content-Type: application/json
• X-IDMS-Event: <event-name> (e.g. document.processed)
• X-IDMS-Signature: <hex> — HMAC-SHA256 of the request body, hex-encoded, using the secret shown when you create the webhook
• 3-attempt retry on non-2xx with backoff [0, 60s, 300s]

Verifying the signature

Node.js

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader, "hex"),
    Buffer.from(expected, "hex")
  );
}

Python

import hmac
import hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    # constant-time compare — never use `==`
    return hmac.compare_digest(signature_header, expected)

# Flask: pass request.get_data() (the RAW bytes), not request.json —
#   verify(request.get_data(), request.headers.get("X-IDMS-Signature", ""), SECRET)

Important: hash the raw request body bytes. Re-serializing the parsed JSON changes whitespace / key order and breaks the comparison.

Event types

The API ships 6 event types, all in the clean root format — the delivered fields sit at the top level of the payload. (The two original events, document.processed and batch.completed, previously also carried a deprecated nested data mirror; it was removed on 2026-07-04.) New webhook subscriptions opt in to events — existing subscriptions don't auto-subscribe to the newer ones.

document.processed

{
  "event": "document.processed",
  "timestamp": "2026-06-07T08:00:00.000Z",
  "document_id": "550e8400-…",
  "external_id": "client-system-2024-1041",
  "filename": "invoice-001.pdf",
  "doc_type": "invoice",
  "doc_subtype": "service_invoice",
  "tags": ["plumbing"],
  "extracted_metadata": { "betrag": "256.74", "currency": "CHF" }
}

When the org has opted into the current classification model, the payload additionally carries classification_v3: { doc_type, doc_subtype, doc_bereich, intent_v3, status_lifecycle, zahlungsstatus, tags }.

For those same opted-in orgs the payload also carries a top-level extracted_contacts array (sibling of related_contacts; omitted when the document has no contacts) — the org-level deduplicated contact records for this document. The same array, same shape, same gating is returned by the document detail read (GET /api/v2/documents/{id}, with or without a profile), so polling integrators and webhook consumers see identical contact data. Each entry is the documented contact object plus three fields specific to this array:

external_id carries the caller-supplied id when the matched contact was created/updated through the API with one; contacts created purely by extraction have external_id: null.

batch.completed

{
  "event": "batch.completed",
  "timestamp": "2026-06-07T08:00:00.000Z",
  "batch_id": "b_001",
  "total_files": 10,
  "processed_files": 10,
  "status": "completed",
  "documents": [ { "id": "...", "status": "completed" }, … ]
}

document.failed (new — clean root)

Fires after the pipeline exhausts its retry budget and parks the document at status="failed".

{
  "event": "document.failed",
  "timestamp": "2026-06-07T08:00:00.000Z",
  "document_id": "550e8400-…",
  "filename": "broken.pdf",
  "external_id": "client-system-2024-1041",
  "error_stage": "ai",
  "error_message": "AI processing timed out after 60s"
}

error_stage ∈ download / extract / ai / persist / unknown. error_message is sanitized: filesystem paths → [path], URLs → [url], stack frames stripped, 500-char cap.

Stable error_message wordings (safe to match on exactly — they will not change without a changelog entry):

Note: a pure image / scan with no recognizable text does not fail — the document completes (document.processed) with extracted_metadata.empty_content = true; treat that flag as the "no text" signal.

classification.changed (new — clean root)

Fires when a PATCH endpoint changes a classification axis. One event per axis touched in a single PATCH (cleaner downstream parsing).

{
  "event": "classification.changed",
  "timestamp": "2026-06-07T08:01:00.000Z",
  "document_id": "550e8400-…",
  "field": "doc_type",
  "old": "invoice",
  "new": "rechnung",
  "actor": { "kind": "api_key", "id": "k_xyz" }
}

field ∈ doc_type / doc_subtype / doc_bereich / intent_v3 / status_lifecycle / zahlungsstatus / tags.

tag.suggested (new — clean root)

Fires when the AI proposes a tag that isn't in the controlled taxonomy.

{
  "event": "tag.suggested",
  "timestamp": "2026-06-07T08:02:00.000Z",
  "document_id": "550e8400-…",
  "suggested_tag": "solar_panel_maintenance",
  "confidence": 0.84
}

Dedup is per (document_id, suggested_tag) — re-processing the same doc with the same suggestion never re-fires.

usage.threshold.reached (new — clean root)

Fires when your organization's API-call count for the current calendar month first crosses the alert threshold configured in Settings. Fires at most once per calendar month — the first crossing in a month sends one event; further calls that month do not re-fire. The counter resets at the start of each month.

{
  "event": "usage.threshold.reached",
  "timestamp": "2026-06-19T17:45:00.000Z",
  "organization_id": "550e8400-…",
  "period_start": "2026-06-01T00:00:00.000Z",
  "threshold": 10000,
  "api_calls": 10034
}

threshold is the configured value; api_calls is the month-to-date count at the moment it crossed (always >= threshold). Use it to get ahead of quota / billing surprises rather than discovering them after the fact.

Opt-in behavior for new events

Existing webhook subscriptions list specific event types in their events column. The newer events (document.failed, classification.changed, tag.suggested, usage.threshold.reached) are not added to existing subscriptions automatically — pick them in Settings → Webhooks when you want them. This guarantees existing integrations never receive surprise events without explicit opt-in.

Feedback

POST /api/v2/feedback

Report classification feedback from your side: a field your users corrected, or an AI draft your users deleted. Feedback is intake only — it never changes the document or its classification. We use it to measure and improve extraction quality.

Request (JSON):

Response 200:

{ "data": { "id": "<feedback-id>", "received": true }, "meta": null, "error": null }

Errors: 400 validation details in error; 401 invalid/missing API key; 404 document not found in your organization; 429 rate limit (100/min, shared with all API calls).

Example:

curl -X POST https://idms.mory.ai/api/v2/feedback \
  -H "Authorization: Bearer idms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "6e27ff62-790a-44e6-9ed5-7d689cbc7602",
    "event_type": "classification.changed",
    "field_path": "doc_type",
    "old_value": "invoice",
    "new_value": "contract"
  }'

# Your user deleted the AI draft — pure negative signal:
curl -X POST https://idms.mory.ai/api/v2/feedback \
  -H "Authorization: Bearer idms_..." \
  -H "Content-Type: application/json" \
  -d '{ "document_id": "6e27ff62-790a-44e6-9ed5-7d689cbc7602", "event_type": "ai_rejected" }'

Error codes

All errors follow the standard envelope:

{ "data": null, "meta": null, "error": "Human-readable message" }

For locked documents, the body also carries a machine-readable code:

{ "data": null, "meta": null, "error": "Document is locked (status_lifecycle=abgeschlossen)", "code": "DOCUMENT_LOCKED" }

The API never returns 403 — cross-org references return 400 (POST/DELETE tag, contact link) or 404 (document lookup) so the response is indistinguishable from a missing resource.

Troubleshooting

"I keep getting 404 on a document I just created"

Most likely your key belongs to a different organization than the document. The API returns 404 instead of 403 for cross-org access so an attacker can't probe for the existence of foreign documents. Verify by listing /api/v2/documents — if your document isn't in the list, it's in a different org.

400 DOCUMENT_LOCKED

The document's status_lifecycle is one of abgeschlossen / finalized / deleted. These are terminal write-states. To edit, either:

1. Have an admin reset the lifecycle to in_bearbeitung (also a PATCH), or
2. Soft-delete and re-upload with external_id=<new-id>.

abgeschlossen is meant to be set when a human has reviewed and signed off — toggling it back means you're explicitly re-opening the review.

"Upload returns idempotent_replay: true but I sent a brand-new file"

You hit one of the two idempotency keys. Check:

1. dedup_by: "external_id" — you sent the same external_id twice. The API considers that intentional; the caller's id is the trust boundary.
2. dedup_by: "content_hash" — the SHA-256 of the file content matches an existing document in your org. If you uploaded the file before (possibly to a different filename), the API returns the existing record. To force a new document, modify any byte of the file or send a fresh external_id.

meta.missing_required_fields is non-empty on a routing-profile response

Routing profiles look up per-template required fields (Pflichtfelder) from a per-client configuration. When extracted_metadata is missing one of these fields, the response succeeds (200) but lists the missing field names in meta.missing_required_fields. This is advisory only — caller can fill them via PATCH /api/v2/documents/:id/metadata and try the same GET again to confirm.

Webhook signature verification fails

The most common cause is hashing the re-serialized JSON body instead of the raw bytes. Example anti-pattern in Express:

// WRONG — req.body is the parsed object, not the raw bytes
const sig = hmac(JSON.stringify(req.body));

// RIGHT — preserve the raw bytes
app.post("/idms-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const sig = hmac(req.body);  // req.body is a Buffer here
});

For frameworks where you don't control the raw bytes, capture them in a middleware before JSON parsing.

"I added a tag.suggested subscription but no events arrive"

Two checks:

1. The org must have at least one document that gets re-processed (the suggestion fires from the AI pipeline). Triggering a one-shot test: use the Reanalyze action in the dashboard.
2. The AI must actually suggest a tag outside the controlled taxonomy. If every model run only returns whitelisted tags, no event fires.

Changelog

2026-07-14 — search: POST /api/v2/search/answer (RAG synthesized answer, optional)

New endpoint (search phase 3). Synthesizes a natural-language answer over the top hybrid-search matches, with every claim cited inline ([1], [2], …); sources lists only excerpts the model actually cited. Opt-in per organization, separate from plain search's opt-in — enabling POST /api/v2/search does not enable this endpoint. LLM calls run on the same EU/CH-compliant (Switzerland North) provider the rest of the AI pipeline uses. See Search.

2026-07-04 — webhook payload: legacy nested data mirror removed

document.processed and batch.completed previously duplicated their fields in a nested data object for backward compatibility. That mirror is removed — all six webhook events now ship the clean root format only (fields at the top level). Receivers must read payload.<field>, not payload.data.<field>.

2026-07-02 — search: contact/property filters + highlighted snippets

POST /api/v2/search gains three optional filters — sender (Absender), receiver (Empfänger), property (Liegenschaft) — substring-matched on the document's entity names. Snippets are now centered on the first query-term match and wrap matched terms in <mark>…</mark> (HTML-escaped). See Search.

2026-07-01 — search: POST /api/v2/search (hybrid semantic + keyword)

New endpoint. Meaning-based and keyword search fused into one ranked list, with matched_via per hit and the same doc_type / bereich / intent / tags / date filters as the documents list. Available per organization (403 until enabled). See Search.

2026-06-30 — usage: historical periods + usage.threshold.reached webhook

• GET /api/v2/usage now accepts ?period=YYYY-MM to read a past month. Current-month data is live (90-day-retention telemetry); past months are served from a durable monthly rollup that outlives the 90-day window, so older per-route history stays queryable. A new source field reports "live" or "rollup". Default behavior (no period) is unchanged — still the current month, month-to-date. A malformed period returns 400.
• New opt-in webhook event usage.threshold.reached — fires once per calendar month when your org's API-call count crosses a configured alert threshold. Clean root payload { event, timestamp, organization_id, period_start, threshold, api_calls }. Like the other opt-in events, existing subscriptions are not auto-subscribed — enable it in Settings → Webhooks.

2026-06-29 — usage: GET /api/v2/usage snapshot endpoint

• New read-only endpoint GET /api/v2/usage returns a month-to-date usage snapshot for your organization: api_calls (total this_period plus a per-route by_route breakdown), documents (total_stored, ingested_this_period), storage.bytes_used, the current rate-limit remaining / rate_limit_reset (mirroring the X-RateLimit-* headers), and limits.* (null = unlimited until per-org quotas land). The organization is taken from the API key, so there are no path or query parameters.
• api_calls.by_route is sourced from request telemetry with 90-day retention, so the per-route history reaches back at most 90 days. Additive — nothing to change in existing integrations.

2026-06-22 — coverage dates: period / validity fields

• New additive fields on extracted_metadata describing the timeframe a document covers:
  • period_from / period_to — the reporting period a document looks back on (tax documents, financial reports, bank statements, HR/payroll).
  • valid_from — the start of a validity window; pairs with the existing valid_until (insurance, certificates, financing documents, contracts).
  • Dates are Swiss DD.MM.YYYY strings. Populated only for the relevant document type and only when the document states the dates explicitly (a bare fiscal year like "2024" expands to 01.01.2024–31.12.2024); null/absent otherwise. A document carries at most one of the two pairs.
• They surface in the read API (GET /api/v2/documents, GET /api/v2/documents/:id) inside extracted_metadata, just like the other metadata fields. Additive only — no client change required; existing integrations are unaffected.

2026-06-22 — v1 API retired

• The legacy /api/v1/* API has been removed; v2 is now the only public API surface. v2 is a field-superset of v1 (every v1 field is still present, plus the current-model fields), so existing integrations migrate by swapping the base path /api/v1 → /api/v2 and reading document_tags[].tag_key (the redundant tag_value is dropped — it always equalled tag_key). The former v1-only batches and sync/documents endpoints are retired — use GET /api/v2/documents?updated_since=<ts> + the meta.server_time cursor for delta sync.

2026-06-14 — docs: batch status & sync endpoints documented

• Added a Batch status & sync section documenting GET /api/v1/batches, GET /api/v1/batches/:id, and GET /api/v1/sync/documents so this page is the single complete API reference. No behavior change — these endpoints already existed on the /api/v1/ path; they are now described here (with a note that the /api/v1/ path is what's live today). (Superseded: the entire /api/v1/* surface was removed — see the latest changelog entry. Use GET /api/v2/documents?updated_since= + meta.server_time for delta sync.)

2026-06-14 — list filters: amount range + due date

• GET /api/v2/documents now supports betrag_min / betrag_max (number — filter on extracted_metadata.total_amount) and faellig_after / faellig_before (ISO date YYYY-MM-DD — filter on extracted_metadata.due_date). All optional, combinable with the existing filters; amount/date parsing is server-side and calendar-invalid stored dates are treated as no-match (never error). Previously documented as not-implemented.

2026-06-13 — classification: non-image doc_types + strict doc_subtype

• doc_type can now also be plan, land_register_extract, or authority_decision — non-image documents (building/floor plans and drawings, land-register/cadastral extracts, authority decisions and permits) that were previously dumped into other. Additive values in the existing open vocabulary; doc_type is a string, not a fixed enum — v1 consumers that whitelist types should add these if they want to surface them, otherwise they behave like any other type.
• doc_subtype is now strict: it is always either a known subtype for its doc_type or null. Previously the model could emit free-text or German variants that leaked into the field; those now collapse to null. No action needed — already-valid subtypes are unchanged; only invented/foreign values stop appearing.
• These are classification-quality improvements applied going forward and via re-analysis of existing documents; no schema change, no breaking change, nothing to update on the client side.

2026-06-13 — classification: new photo doc_type

• doc_type can now be photo — image files (jpg/png/…) the classifier cannot assign to a real document type are typed photo instead of other. Filterable via ?doc_type=photo. Additive value in the existing vocabulary; v1 consumers that whitelist types should add photo if they want to surface it (otherwise it behaves like any other type).

2026-06-13 — metadata: _ai_possible_duplicate marker

• extracted_metadata._ai_possible_duplicate: true is now set on documents whose filename carries a copy marker ("- Kopie", "(1)", "- Copy"). Non-destructive — the document is still processed normally; the flag only surfaces likely duplicates for review. Absent when not a copy. Additive.

2026-06-15 — extraction: vat_rate (MwSt-Satz)

• New additive field extracted_metadata.vat_rate — the VAT/MwSt rate as a percentage number without the % sign (e.g. "8.1", "2.6", "3.8"), nullable. Extracted ONLY when the document explicitly states the rate; never inferred. Appears in the read API and the document.processed webhook alongside the other amounts.
• Requested for accounting flows; existing integrations are unaffected (new key only).

2026-06-15 — documents: extracted_contacts on the detail read (v3 orgs)

• GET /api/v2/documents/{id} now returns the same top-level extracted_contacts array the document.processed webhook delivers (same builder, same v3-org gating, same one-entry-per-contact + relationships semantics). Applies to the raw shape and to every output profile.
• Additive: the key is omitted for v1 orgs and for documents without contacts — existing parsers are unaffected.
• Closes the gap where an integrator re-fetching the document after a webhook (or polling) saw no contact data even though the webhook carried it.

2026-06-19 — documents list: external_id + updated_since filters

• GET /api/v2/documents?external_id=<id> — exact lookup by your external_id.
• GET /api/v2/documents?updated_since=<ISO8601> — documents with updated_at after the timestamp, ordered updated_at ascending (delta sync); malformed timestamp → 400.
• Both additive + backward-compatible (absent → unchanged): external_id for idempotent lookups and updated_since for delta-sync polling.
• The list meta now also carries server_time (the server's query-time timestamp) — save it and pass it as the next updated_since for incremental polling.

2026-06-18 — metadata: internal _-prefixed markers are no longer exposed

• extracted_metadata._ai_possible_duplicate (and any other internal _-prefixed bookkeeping key) is no longer included in API responses or webhook payloads. It remains an internal review marker only. This reverses the 2026-06-13 note above that surfaced _ai_possible_duplicate to clients.
• Cleanup, not a contract break: the field was only ever set on filename-copy documents and was undocumented in the OpenAPI schema. If you relied on it, treat its absence as "not a copy"; duplicate review is an internal/dashboard concern.

2026-06-14 — extraction: booking_date (Buchungsdatum)

• New additive field extracted_metadata.booking_date (format DD.MM.YYYY, nullable) — extracted ONLY when the document explicitly labels a booking date ("Buchungsdatum", "gebucht am"); never inferred from the issue or due date. Appears in the read API and the document.processed webhook payload alongside date_issued.
• Requested for accounting flows; existing integrations are unaffected (new key only).

2026-06-14 — webhooks: stable error_message wordings (incl. password-protected files)

• Password-protected files now fail fast with a stable, documented error_message: File is password-protected and cannot be processed. Remove the password protection and upload it again. Previously an encrypted PDF could complete silently with empty content.
• The document.failed section now lists all stable error_message wordings integrators may match on exactly; they will not change without a changelog entry.

2026-06-14 — feedback: classification-feedback intake endpoint

• New POST /api/v2/feedback — report a field your users corrected (event_type: "classification.changed" with field_path, old_value, new_value) or an AI draft your users deleted (event_type: "ai_rejected", no field detail needed).
• Intake only: feedback never mutates the document or its classification. Stored per organization for extraction-quality analysis.
• Standard v2 envelope, auth and rate limits. 404 for documents outside your organization.

Add-only. Newest entries on top. Older entries are preserved verbatim.

2026-06-12 — uploads: force=true testing flag

• POST /upload (multipart field) and POST /upload/finalize (JSON field) accept force: true to bypass content-hash idempotency and re-process identical bytes as a new document. Forced rows store no content hash (excluded from future dedup); reusing an existing external_id with force returns 400. Response meta gains forced: true. Built for integration test loops — production ingestion should not use it.

2026-06-12 — webhooks: extracted_contacts on document.processed (v3 orgs)

• document.processed for v3-opt-in organizations now carries a top-level extracted_contacts array — the document's deduplicated contact records with per-contact confidence (0..1), the new function field (person's role/job title) and an explicit relationships pairing signal referencing sibling entries. See Webhooks.
• New extracted field on persons: function (e.g. "Geschäftsführerin"); also returned on the contacts endpoint.
• Additive only — existing payload fields unchanged; v1 orgs unaffected.

2026-06-10 — OpenAPI 3.1 spec published

• Machine-readable spec for all v2 endpoints + webhook payloads at /openapi-v2.yaml. Generated from the route handlers; validated with Redocly. The markdown reference stays authoritative for semantics.

2026-06-10 — contact deduplication + id stability guidance

• Duplicate contact records (name variants such as token order, salutations, punctuation, glued digits) are now merged automatically at extraction time, and existing duplicates were merged org-wide. Document links were fully carried over.
• Integrator guidance: contact_id values of merged duplicates no longer resolve. Treat document_id as the stable key and re-fetch contacts instead of caching contact_id long-term (now documented on the contacts endpoint). Document ids, payload structure and webhooks are unchanged.

2026-06-10 — Office lock files rejected + readable corruption errors

• Microsoft Office temporary/owner files (~$… stubs) are now rejected up front: 400 on multipart /upload and presigned /upload/init, and per-entry rejected_reason: "office_lock_file" inside ZIP containers.
• Corrupt Office documents (.docx/.xlsx/.pptx) now fail with the readable error_message "File is corrupt or not a valid Office document (.docx/.xlsx/.pptx)." instead of a raw parser error — visible on the document row and in the document.failed webhook payload.

2026-06-10 — presigned upload: two-step flow up to 250 MB

• New POST /upload/init + POST /upload/finalize flow — file bytes stream directly to storage, lifting the per-file limit from the multipart 4 MB cap to 250 MB. Multipart /upload now returns a descriptive 413 pointing at the presigned flow.
• Documented in Presigned upload — up to 250 MB.

2026-06-10 — docs: contacts payload + ZIP container reference

• The contact object (all fields incl. ISO date_of_birth), the document-level entity fields (sender / receiver / related_contacts / property / unit / equipment), and the ZIP container upload contract (entry rules, per-entry rejected_reason values) are now fully documented. No behavior change.

2026-06-10 — docs: clarify the _v3 field-name suffix

• Strengthened the Versioning note: the _v3 suffix on intent_v3, document_classification_v3, and v1_projection is a stable contract identifier, not an API version. A field tagged _v3 belongs to the current classification model; a field tagged v1 belongs to the legacy taxonomy the v1 API surfaces unchanged.
• Motivation: integrators reading the spec see the suffix and wonder whether they need to track a model version. They don't — the suffix never changes and can be hard-coded.
• No field rename, no behavior change.

2026-06-10 — docs: explicit v3 opt-in section in Classification Model

• Added an "Opt-in per organization" subsection explaining that the current classification model is per-org opt-in; default is the legacy v1 extractor.
• Documented what the v2 read response looks like for v1 orgs vs opted-in orgs: top-level fields stay populated either way (v1 vocabulary / v1 projection); the nested document_classification_v3 object is null on v1 orgs and populated when opted in.
• Spelled out the path to opt in (contact your account manager) and listed which internal/production orgs are already on the current model.
• Motivation: clients reading the v2 spec couldn't tell why their nested document_classification_v3 was null. They assumed it was a bug, not a per-org config. The docs now state this up-front so integrators don't lose time chasing a non-bug.

2026-06-10 — upload: presigned-URL flow for files up to 250 MB

• New POST /api/v2/documents/upload/init returns a Supabase Storage signed PUT URL + the bucket-scoped storage_path + a 2-hour expiry. JSON body, no file bytes.
• New POST /api/v2/documents/upload/finalize registers the document after the caller has PUT the file to the signed URL: idempotency (external_id → content_hash) → storage object existence check → documents row + batch + audit log + pipeline trigger.
• Why a two-step flow: our serverless runtime's 4.5 MB request body cap (platform-level, not application-configurable) makes the multipart /upload endpoint unusable for real-world property-management documents. The presigned flow streams the file content directly to Supabase Storage and never touches our API function, lifting the per-file cap to the storage bucket's file_size_limit (now 250 MB per migration 056).
• No new auth surface: same Authorization: Bearer idms_… key as the rest of v2, same 100 req/min rate-limit shared with /upload, same { data, meta, error } envelope.
• No client SDK required: upload_url is a plain signed PUT — curl -X PUT --data-binary @file … works. Callers using @supabase/supabase-js can also use uploadToSignedUrl(storage_path, upload_token, file).

2026-06-08 — documents: download endpoint (signed URL)

• New GET /api/v2/documents/:id/download returns a short-lived Supabase Storage signed URL for the document's original bytes. Client follows the URL directly — bytes do not travel through the API function. Default TTL 3600 s, clamped to [60, 86400] via ?ttl=.
• Auth + rate-limit + envelope match the rest of v2 (Bearer IDMS_API_KEY, 100 req/min/key, { data, meta, error }).
• Cross-org isolation: the documents lookup is scoped by both id and organization_id; a cross-org hit returns 404 (not 403) so existence is never disclosed.
• Sammel-PDF: container and child rows both resolve to the original uploaded file — per-segment text is already on the child via GET /api/v2/documents/:id.

2026-06-07 — taxonomy: English labels everywhere + German enum glossary

• New: every taxonomy reference table (doc_bereiche, doc_types, doc_subtypes, intents, tag_groups, tags) now carries label_en alongside the existing label_de. Backfilled for all 237 taxonomy entities (8 + 31 + 121 + 13 + 10 + 54). Schema change applied via migration 052; data backfill via migration 053. Strictly additive: a v2 consumer that only reads label_de is unaffected.
• GET /api/v2/taxonomy now returns label_en on every row in bereiche, doc_types, doc_subtypes, intents, tag_groups, and tags. Null in the response means the row pre-dates the backfill — currently nothing is null in prod, but the field is nullable on the wire so a future taxonomy migration can introduce a new row without immediately needing the translation.
• Docs: the auto-generated taxonomy tables under Classification Model now have a Label (EN) column. The new German enum glossary subsection there documents which enum values stay German on the wire (offen, bezahlt, neu, abgeschlossen, eingehend, ausgehend, absender, empfaenger, …) and what each one means. Those values are contract identifiers and will not be renamed.
• Prose: scattered German words inside English sentences (bezüge, Pflichtfelder, Empfänger-Regel, Modul/Ordner/Vorlage/Belegart) now lead with the English term and keep the German in parentheses at first mention.

2026-06-07 — per-org classification-model opt-in flag

• New org_config.classification_version ∈ (v1, v3), default v1 for every existing org (the value v3 here is a model-version literal — the API itself stays at v2). Flip via INSERT INTO org_config … ON CONFLICT … DO UPDATE SET classification_version = 'v3'.
• Opt-in pipeline awaits the current-model extractor before firing document.processed so the payload can carry classification_v3 = { doc_type, doc_subtype, doc_bereich, intent_v3, status_lifecycle, zahlungsstatus, tags[] } ADDITIVELY (v1 fields untouched).
• Rollback: UPDATE org_config SET classification_version = 'v1' WHERE … reverts behavior on the next processed document. Persisted rows in document_classification_v3 are preserved.
• Reclassify existing docs: tsx scripts/reclassify-org.ts --org <uuid> --dry-run (default) or --apply (writes). Rate-limited (default 1.5 s between docs). Refuses to run when the target org is still on v1.

2026-06-07 — webhooks: 3 new event types (opt-in)

• New document.failed — fires after the pipeline exhausts retries. Payload (clean root, no deprecated data wrapper): { event, timestamp, document_id, filename, external_id, error_stage, error_message }. error_message is sanitized (paths, URLs, stack frames stripped, 500-char cap).
• New classification.changed — one event per axis touched in a PATCH /api/v2/documents/:id. Payload: { event, timestamp, document_id, field, old, new, actor: { kind, id } }.
• New tag.suggested — fires when the AI proposes a tag outside the controlled taxonomy. Dedup per (document_id, tag) via extracted_metadata._tag_suggested_fired. Payload: { event, timestamp, document_id, suggested_tag, confidence }.
• Opt-in: existing subscriptions never receive new events automatically. Pick them in Settings → Webhooks. Existing v1 integrations unaffected.
• HMAC + headers + retry policy unchanged. All events — including document.processed and batch.completed — ship the clean root format; the deprecated nested data wrapper on the two original events was removed 2026-07-04.

2026-06-07 — v2 upload + idempotency for high-volume bulk

• New POST /api/v2/documents/upload — single file, multipart. Idempotency via external_id first, then SHA-256 content_hash. Same content uploaded twice in the same org → meta.idempotent_replay = true + the existing document; no second storage object, no second pipeline trigger.
• New POST /api/v2/documents/upload/batch — up to 50 files per request. Per-item result { index, status: "created" | "idempotent_replay" | "failed", doc?, error?, dedup_by? }. One bad item never aborts the rest.
• Repeated filenames are NOT a duplicate signal — at 200 000+ files per ingestion run, timestamp-style filenames (e.g. 20260603105516.pdf) repeat by the thousands; v2 stores each accepted upload at ${orgId}/v2/${stem}-${random8hex}${ext} so storage collisions are impossible. The caller's original filename is preserved in documents.filename.
• Migration 050 adds documents.content_hash (nullable) + partial UNIQUE on (org, content_hash).
• Audit log row written for every outcome.

2026-06-07 — built-in routing profiles + per-org output profiles

• New GET /api/v2/documents/:id?profile=<profile_key> — runs the configured 4-level routing engine for that client: Modul (module) → Ordner (folder) → Vorlage (template) → Belegart (document kind) with direction (inbound/outbound resolved via a receiver rule — Empfänger-Regel) and buchungsrelevanz (posting-relevance) axes, OU resolution from the per-tenant org tree, per-template status set + required-field (Pflichtfeld) validation. Returns { modul, ordner, template, belegart, direction, buchungsrelevant, ou, status_set, status, required_fields, missing_required_fields, ... } with meta.routing_rule + meta.missing_required_fields. Profile keys are provisioned per client by your account manager.
• Per-org config tables seeded: taxonomy_maps (40 routing rows for a typical client). Migration 049 extends taxonomy_maps with direction, buchungsrelevant, and per-client routing columns (target Modul / Ordner / Template / Sub-template).
• Generic mapping engine for clients that don't need 4-level routing: output_profiles.fields JSONB carries { renamed, excluded, included, tag_groups_included, required_fields, fallback_label }.

2026-06-07 — v2 write API: PATCH + tag ops + bulk + audit

• New PATCH /api/v2/documents/:id — atomic correction of doc_type / doc_subtype / doc_bereich / intent / status_lifecycle / zahlungsstatus + tags + optional reason.
• New POST /api/v2/documents/:id/tags and DELETE /api/v2/documents/:id/tags — idempotent tag UPSERT/DELETE with confidence = 1 sentinel marking manual overrides.
• New PATCH /api/v2/documents — bulk (max 100 items, per-item result, one bad item does not abort the rest).
• Every write commits one document_audit_log row with prev/next snapshots and a diff (fields_touched or added/removed).
• Manual override convention: document_tags_v3.confidence = 1 + extracted_metadata._manually_corrected_fields[] + _manually_corrected_at so a future re-classifier can detect and preserve manual edits.

2026-06-06 — v2 API: read + write with the current classification model

• New GET /api/v2/documents — list with current-model filtering (doc_type, subtype, intent, status, zahlungsstatus, bereich, repeatable tag).
• New GET /api/v2/documents/:id — full document with the current classification record, structured metadata, related contacts, and linked entities (Bezüge — property/unit/equipment).
• New GET /api/v2/documents/:id/contacts — extracted Person/Firma contacts with role (absender/empfaenger/cc), normalized across all docs in the org.
• New PATCH /api/v2/documents/:id/classification — correct doc_type, doc_subtype, intent, status_lifecycle, zahlungsstatus, and tag set.
• New PATCH /api/v2/documents/:id/metadata — MERGE update of the current-model extracted_metadata (null deletes a key).
• New PATCH /api/v2/documents/:id/contacts — REPLACE the document's contact links (anti-spoof org check on every contact).
• New GET /api/v2/taxonomy — full taxonomy (8 bereiche, 31 doc_types, 121 subtypes, 13 intents, 10 tag_groups, 54 tags) with German labels and v1 projection.
• New Append-only audit log on every PATCH (actor, API key id, IP, prev/next snapshots, optional reason).
• New current-model fields surfaced on every v2 read: document_classification_v3 (doc_bereich, doc_subtype, intent_v3, status_lifecycle, zahlungsstatus) plus document_tags_v3.
• New Lock semantics: writes to documents with status_lifecycle ∈ {abgeschlossen, finalized, deleted} return 400 DOCUMENT_LOCKED. Reads unaffected.
• Backward-compat: every taxonomy entry exposes v1_projection so clients can translate current-model values back to v1 vocabulary for legacy integrations.
• v1 unchanged. No schema, behavior, or contract changes to /api/v1/*.

2026-06-06 — UI: intra-batch file deduplication

Dashboard file upload no longer silently overwrites files with the same name in a single drag-drop batch. Duplicate names are auto-suffixed (scan.pdf → scan (2).pdf) and surfaced in the upload toast.

2026-05-23 — Signature field

New field signature on documents (list, detail, sync, and the document.processed webhook): { signed, signed_by?, signed_at?, confidence?, raw? }. Auto-detected from text (mainly for contracts) and overridable in the UI. Backward-compatible additive change.

2026-04-29 — Documentation improvements

Added JavaScript examples, rate limit headers, batch.completed webhook payload, error response bodies, pagination guide, API scope notes.

2026-04-21 — 16-category classification + entity extraction

New fields: doc_type, doc_subtype, doc_intent, sender, receiver, property, unit, equipment. Structured tag taxonomy (59 tags, 8 groups — v1 vocabulary). Old classification field kept for backward compatibility.

2026-04-15 — Upload endpoint + sync polling

Added POST /api/v1/documents/upload and GET /api/v1/sync/documents endpoints. Client webhook support via environment variables.

2026-04-12 — Initial API release (v1)

Documents, batches, tags, API key auth, rate limiting, per-org webhooks.