API Reference

All endpoints are served under the /v1 prefix. Request and response bodies are JSON (Content-Type: application/json).

Note: every span this API returns ({ "start": ..., "end": ... } on transform entities, detect entities, and batch detect entities) is a pair of UTF-8 byte offsets into the exact request text, not code-point or UTF-16 indices. end is exclusive. Slice the original bytes, or convert to your language's index unit before slicing: Python string slicing indexes code points and JavaScript and Java index UTF-16 code units, so on any non-ASCII payload a direct slice by these numbers lands on the wrong characters. The RAG chunk start_offset / end_offset are byte offsets into the submitted document text on the same basis. When a topical redaction rule matched the document, a chunk overlapping a redacted region reports that region's full original extent.

Detected values are replaced with semantic tokens. The emitted form is always three segments, {{type:id:cap}} (for example {{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}): a lowercase type label, an id stable within a session, and a per-token capability cap. Every transform emits the cap, RAG or not. The :cap segment is matched exactly at rehydrate and fails closed: a capless {{type:id}} token, like a wrong cap, never resolves, so a guessed id cannot restore a value. In the default per-request scheme the id is a prefix_NNN counter (e_001, p_001) and the cap is 32 random hex characters (16 random bytes); RAG calls that pass a corpus_id instead derive a deterministic corpus-scoped identity (a 24-hex id suffix and a 32-hex cap), so the same value maps to the same token across documents and queries. Token examples in this reference show the full emitted form, because only that form round-trips.

Endpoint Table

Port note: Examples below use port 3000 (the server default). The Docker quick start (deploy/docker/docker-compose.yml) also publishes port 3000; the two-instance compose stack (deploy/docker/docker-compose.ha.yml) fronts the server with nginx on port 8080. For other deployments, substitute the appropriate host and port.

Round-trip field flow

The protect then restore round trip uses a different field name at each step, because the text changes role as it moves through the pipeline:

The request field is input on transform but output on rehydrate because rehydrate's input is the LLM's output. The text field is safe_text after transform and restored_text after rehydrate. Carry the session_state from step 1 into step 3: it holds the token map that makes restoration deterministic.

Authentication

API Key

Send the key in the X-API-Key header:

curl -H "X-API-Key: your-key-here" http://localhost:3000/v1/transform ...

JWT Bearer Token

Send a JWT in the Authorization header:

curl -H "Authorization: Bearer eyJhbG..." http://localhost:3000/v1/transform ...

In the jwt auth mode, tokens are validated with a configured shared secret (HMAC: HS256, HS384, or HS512). Asymmetric and JWKS verification are not part of this mode; use the oidc mode below for those.

OIDC (JWKS)

For asymmetric tokens issued by an OIDC provider, set auth.mode: oidc and configure [auth.oidc] with issuer, jwks_url, audience, tenant_claim, and the allowlisted asymmetric algorithms (RS*, ES*, or PS* families). The server fetches and caches the provider's JWKS, verifies the token signature against it, pins the algorithm allowlist (rejecting alg: none and HMAC-in-asymmetric confusion), and requires the tenant claim on every token. Send the token the same way as a JWT:

curl -H "Authorization: Bearer eyJhbG..." http://localhost:3000/v1/transform ...

Scopes

The runtime supports 11 scopes:

admin implies every other scope, so an admin key reaches all endpoints. /v1/revocations/count stays admin-only; it returns a scope-local count (the caller's own tenant, or the unscoped partition for a platform admin), never a cross-tenant total.

Migration (granular route scopes): the batch, RAG, and revoke endpoints now require their own scope instead of reusing transform. A key that previously relied on transform to reach /v1/batch/* or /v1/rag/*, or on admin to revoke, must be granted batch, rag, or revoke. This is a deliberate least-privilege change: a key now gets exactly the route classes it is granted.

When auth is disabled (default for development), all endpoints are accessible without credentials.

Idempotent retries (Idempotency-Key)

The mutating, non-streaming endpoints accept an optional Idempotency-Key request header so a network retry cannot execute the same mutation twice: POST /v1/transform, POST /v1/transform/file, POST /v1/transform/image, POST /v1/redact/image, POST /v1/batch/transform, POST /v1/rag/ingest, POST /v1/rag/ingest/batch, POST /v1/rag/delete, POST /v1/revoke, POST /v1/revoke/bulk, and DELETE /v1/sessions. Requests without the header, and every read, detect, or streaming route, are never deduplicated.

curl -X POST http://localhost:3000/v1/revoke \
  -H "X-API-Key: your-key" \
  -H "Idempotency-Key: 7f3d2c1e-revoke-julia" \
  -H "Content-Type: application/json" \
  -d '{ "entity_type": "email", "value": "erika.mustermann@example.com" }'

The contract:

• The key must be 1 to 255 printable ASCII characters; anything else is rejected with 400 GUARDAI_IDEMPOTENCY_KEY_INVALID.
• The first request with a key executes normally. A retry with the same key, method, path, Content-Type, and body within the retention window replays the stored response byte-identically, stamped with the response header Idempotency-Replayed: true.
• Reusing a key with a different method, path, Content-Type, or body is a client bug and returns 409 GUARDAI_IDEMPOTENCY_KEY_REUSE; the request is never silently re-run. Send the retry with the same Content-Type as the original request.
• A concurrent duplicate while the first attempt is still running returns 409 GUARDAI_IDEMPOTENCY_IN_PROGRESS.
• Only 2xx responses are recorded. A failed attempt releases the key, so an identical retry may re-execute.
• If the mutation succeeded but its result was not retained for replay (too large, or a binary body such as a redacted image), a retry gets 409 GUARDAI_IDEMPOTENCY_RESULT_UNAVAILABLE: the operation completed, the result is not replayable, do not retry blindly.
• POST /v1/redact/image never retains its redacted image in the store, so a same-key retry returns 409 GUARDAI_IDEMPOTENCY_RESULT_UNAVAILABLE rather than the image; resend under a fresh key when you need the image again. JSON responses replay unchanged.
• If the store is at capacity the request is rejected with 503 GUARDAI_IDEMPOTENCY_STORE_FULL before the mutation runs, so it is safe to retry once the store has room.
• A keyed /v1/batch/transform or /v1/rag/ingest/batch retried after an abort resumes on the Redis idempotency backend in independent session mode: items that already committed replay from their checkpoints and only the remaining items execute, each checkpointed in the same synchronous step as its commit; an item whose process died between the two executes once more on the retry. A keyed /v1/batch/transform in shared session mode does not resume after an abort: every item continues the session the previous item advanced, so no later attempt can safely redo or skip an item whose checkpoint never landed. A same-key retry of an aborted shared-mode batch returns 409 GUARDAI_IDEMPOTENCY_RESULT_UNAVAILABLE for the whole request without executing anything, and further retries replay that outcome; resend under a fresh key. A shared-mode batch whose every item was checkpointed still replays its combined result. A retry that is refused before any item runs (a rate limit, an entitlement) while a committed prefix exists returns 503 GUARDAI_IDEMPOTENCY_INDETERMINATE and keeps that prefix for the next same-key retry. A converged independent-mode retry yields one audit event and one session per item. The memory backend supports the same mechanism within one process but does not survive a restart.

Keys are partitioned by the authenticated tenant, so one caller's key can never collide with another's. The store is configured under idempotency: backend (memory, the default, per replica; or redis, shared across replicas via session.redis_url), ttl_seconds (how long a completed response is replayed, default 86400), and in_progress_ttl_seconds (how long an abandoned in-flight claim is held before it becomes reclaimable, default 60).

POST /v1/transform

Transform input text, replacing detected entities with semantic tokens.

Request

{
  "input": "Contact Erika Mustermann at erika.mustermann@example.com",
  "input_type": "text",
  "policy": "default",
  "language": "de",
  "session_state": "(optional sealed blob from previous transform)",
  "detectors": ["builtin_regex"],
  "context": {
    "destination": "external_llm",
    "provider": "openai",
    "caller_role": "support_agent",
    "caller_purpose": "customer inquiry response"
  },
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Exactly one input source is permitted: input (text), input_json, or input_messages.

Response

{
  "safe_text": "Contact Erika Mustermann at {{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}",
  "session_id": "01916a3e-7b2c-7000-8000-000000000001",
  "session_state": "eyJ2IjoxLCJzaWQiOi...",
  "entity_context": [
    {
      "token": "{{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}",
      "type": "email"
    }
  ],
  "entities": [
    {
      "token": "{{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}",
      "type": "email",
      "protection_level": "2",
      "action_applied": "tokenize",
      "confidence": 0.99,
      "detector": "builtin_regex",
      "span": { "start": 27, "end": 42 }
    }
  ],
  "stats": {
    "entities_detected": 1,
    "entities_transformed": 1,
    "entities_blocked": 0,
    "detection_time_ms": 1.2,
    "transform_time_ms": 0.3
  }
}

Fields are omitted when not set. safe_json and safe_messages are covered under the JSON and chat input modes below.

Entity metadata fields (gender, formality, language, role, belongs_to) appear only when the policy exposes them (metadata_policy.expose_*) and a value was inferred. role is the policy-defined entity role, for example labelling a person as the patient or the doctor (see the extensibility guide); belongs_to links an entity to the person or entity it belongs to (the relational side of the role taxonomy). Both are always declared labels, never raw values.

JSON input mode

Set input_type to "json" and pass the document as input_json. Any JSON value is accepted (an object, an array, or a bare string, number, boolean, or null). Each string value and each object key is detected and tokenized independently, and the response adds safe_json: the same structure with PII replaced by {{type:id:cap}} tokens. safe_text is the serialized safe_json, so you can send either to the LLM. The same value in two fields receives the same token id, and one sealed session_state rehydrates the whole document.

Request:

{
  "input_type": "json",
  "input_json": {
    "customer": "Erika Mustermann",
    "email": "erika.mustermann@example.com",
    "card": 4111111111111111,
    "notes": "VIP account"
  }
}

Response:

{
  "safe_json": {
    "customer": "{{person:p_001:9f2c4a7b1e8daa11bb22cc33dd44ee55}}",
    "email": "{{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}",
    "card": "{{credit_card:cc_001:7d1a3f5b9c2eaa11bb22cc33dd44ee55}}",
    "notes": "VIP account"
  },
  "safe_text": "{\"customer\":\"{{person:p_001:9f2c4a7b1e8daa11bb22cc33dd44ee55}}\",\"email\":\"{{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}\",\"card\":\"{{credit_card:cc_001:7d1a3f5b9c2eaa11bb22cc33dd44ee55}}\",\"notes\":\"VIP account\"}",
  "session_id": "01916a3e-7b2c-7000-8000-000000000001",
  "session_state": "eyJ2IjoxLCJzaWQiOi..."
}

Notes:

• The structure is always preserved: same keys, same array lengths, same nesting. A structural mismatch fails closed (the request errors) rather than returning a partially tokenized object.
• A numeric leaf that is itself PII (for example a credit-card number sent as a JSON number) is tokenized to a string token, so its type changes from number to string in safe_json. A number with no detected PII is returned unchanged as a number. Booleans and null always pass through.
• Object keys are detected too: a key that is itself PII (for example an object keyed by an email address) is tokenized or redacted; non-PII keys pass through unchanged.
• Limits: a JSON document may not exceed 64 levels of nesting, 10,000 scannable slots, or 1 MB of total scanned text. Exceeding any limit fails closed.

Chat input mode

Set input_type to "chat_messages" and pass an OpenAI-format message array as input_messages. The whole conversation is protected in one call: every string-bearing field of every message (content, multimodal text parts, tool-call arguments) is detected and tokenized, and the response adds safe_messages with the same shape. The same value across messages receives the same token id, and one sealed session_state rehydrates the whole conversation. safe_text is the serialized safe_messages.

Request:

{
  "input_type": "chat_messages",
  "input_messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "My email is erika.mustermann@example.com" }
  ]
}

Response:

{
  "safe_messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "My email is {{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}" }
  ],
  "session_id": "01916a3e-7b2c-7000-8000-000000000001",
  "session_state": "eyJ2IjoxLCJzaWQiOi..."
}

Notes:

• Each message must be an object with a non-empty string role and a content that is a string, a content-part array, or null. Only role, content, name, tool_calls, and tool_call_id are supported; a message carrying any other text-bearing field is rejected so raw data cannot ride through an unscanned field.
• Tool-call arguments is a JSON string and is protected structurally: it is parsed, its values are tokenized, and it is re-serialized as valid JSON. A non-JSON arguments string is rejected.
• Non-PII fields pass through unchanged, so a static system prompt is returned as sent.

POST /v1/rehydrate

Restore semantic tokens in LLM output to their original values.

Request

{
  "output": "Dear {{person:p_001:9f2c4a7b1e8daa11bb22cc33dd44ee55}}, your order {{order:o_001:4b8e2d6f0a1caa11bb22cc33dd44ee55}} has shipped.",
  "session_state": "eyJ2IjoxLCJzaWQiOi...",
  "output_channel": "customer_email",
  "restore_mode": "formatted",
  "restore_overrides": {
    "e_001": "none"
  }
}

Response

{
  "restored_text": "Dear Frau Erika Mustermann, your order ORD-2026-4892 has shipped.",
  "tokens_resolved": 2,
  "tokens_unresolved": [],
  "stats": {
    "rehydrate_time_ms": 0.8
  },
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Restore Modes

POST /v1/output-guard

Scan model-generated output for sensitive values the model produced, with no session. Every detected value counts as new, because there is no session to exempt against. The deployment's output-protection posture and the resolved policy's egress obligations govern the verdict, exactly as the transparent proxy applies on a sessionless egress. Use it from an SDK or an agent framework that has model output but never opened a transform session.

The output text is never written to a log or an error body: only the policy identifier (fingerprinted), the channel, and the trigger flag are recorded.

Request

{
  "output": "Please reach escalation@backoffice.example to proceed.",
  "policy": "german-support",
  "output_channel": "customer_email"
}

Response

{
  "safe_output": "Please reach [EMAIL] to proceed.",
  "output_guard_triggered": true
}

A content block answers 422 GUARDAI_OUTPUT_BLOCKED. A scanner outage, and a deployment whose output guard is disabled (output_protection.enabled: false), answer 503 GUARDAI_OUTPUT_GUARD_UNAVAILABLE: a dedicated guard call cannot be honored by a disabled guard, so it fails closed rather than echoing the text. The route is a replayable read; it mints no session and mutates no store, so a network retry is safe.

POST /v1/detect

Detect entities in text without performing transformation.

Request

{
  "input": "Email: test@example.com, SSN: 123-45-6789",
  "language": "en",
  "detectors": ["builtin_regex", "python_ner"],
  "entity_types": ["email", "ssn"],
  "threshold": 0.5,
  "policy": "healthcare",
  "include_values": true
}

Response

{
  "entities": [
    {
      "type": "email",
      "value": "test@example.com",
      "span": { "start": 7, "end": 23 },
      "confidence": 1.0,
      "detector": "builtin_regex"
    },
    {
      "type": "ssn",
      "value": "123-45-6789",
      "span": { "start": 30, "end": 41 },
      "confidence": 1.0,
      "detector": "builtin_regex"
    }
  ],
  "stats": {
    "detection_time_ms": 0.9,
    "detectors_used": ["builtin_regex"],
    "detector_mode": "builtin_regex"
  },
  "warnings": ["NER sidecar not active"]
}

Each span is a UTF-8 byte range into the submitted input, with an exclusive end. The example above is ASCII, so the numbers happen to match character positions; on any non-ASCII text they do not. Slice the request bytes, not the decoded string.

Each detected entity may also carry metadata (gender, formality, language, role, belongs_to) when a policy exposes it. stats.detector_mode reports the mode used (builtin_regex, builtin_and_ner, or python_ner). Top-level warnings carries the same honest degraded-coverage advisory as transform, for example when the NER sidecar is not active. All three are omitted when empty.

POST /v1/evaluate-policy

Evaluate a policy against entities without performing transformation or creating a session. Useful for previewing what actions would be taken. The optional output_channel (default user_output) previews the channel-resolved restore_mode each entity would get, clamped by the safe-sink ceiling exactly as rehydrate does.

Request

{
  "policy": "strict-pii",
  "entities": [
    { "type": "person", "value": "Erika Mustermann" },
    { "type": "ssn", "value": "123-45-6789" }
  ],
  "output_channel": "customer_email"
}

Response

{
  "decisions": [
    {
      "entity_type": "person",
      "action": "tokenize",
      "protection_level": "1",
      "rule_matched": "strict-pii/person",
      "restore_mode": "masked",
      "reason": "Level 1 entity, masked restore for customer_email channel"
    },
    {
      "entity_type": "ssn",
      "action": "redact",
      "protection_level": "1",
      "rule_matched": "strict-pii/ssn",
      "restore_mode": "none"
    }
  ],
  "policy_version": "1.0.0",
  "warnings": ["output_channel filtering previewed; restore_mode is channel-resolved"]
}

Each decision may include an optional reason explaining the resolved action or restore mode. The response may also carry top-level warnings advising about unsupported or unimplemented request fields. Both are omitted when empty.

POST /v1/batch/transform

Transform many inputs in one request. Requires the batch scope. Accepts up to max_batch_size items (see capabilities).

Request

{
  "session_mode": "independent",
  "policy": "default",
  "items": [
    { "text": "Hello Erika Mustermann", "language": "de" },
    { "text": "Contact erika.mustermann@example.com", "policy": "gdpr-strict" },
    { "input_type": "json", "input_json": { "email": "erika.mustermann@example.com" } }
  ]
}

In shared session mode the credential's policy entitlement is decided before any item executes, against every policy the batch can run under: each item's own policy (or the batch-level policy) and, for any item that omits both, the deployment default. An item that relies on inheriting the shared session's policy must therefore also be entitled to the default; a batch that should run entirely under one named policy sets it at the batch level.

Each item (BatchTransformItem) supports:

Response

{
  "results": [
    {
      "index": 0,
      "safe_text": "Hello {{person:p_001:a1b2c3d4e5f6aa11bb22cc33dd44ee55}}",
      "session_state": "eyJ2IjoxLCJ...",
      "entities_detected": 1,
      "entities_transformed": 1
    },
    {
      "index": 2,
      "safe_text": "{\"email\":\"{{email:e_001:0f9e8d7c6b5aaa11bb22cc33dd44ee55}}\"}",
      "safe_json": { "email": "{{email:e_001:0f9e8d7c6b5aaa11bb22cc33dd44ee55}}" },
      "entities_detected": 1,
      "entities_transformed": 1
    }
  ],
  "stats": { "total_items": 3, "total_entities": 2, "total_time_ms": 15.5 }
}

Each result carries its index (matching the request order), safe_text, and entities_detected / entities_transformed. A JSON item also returns safe_json; a chat item returns safe_messages. If a single item fails, its result carries an error string and an empty safe_text while the rest of the batch still processes. stats aggregates total_items, total_entities, and total_time_ms.

Batch works on every session backend. With the default sealed backend each result carries a session_state blob; with a server-side backend (memory or redis) each result instead carries a session_id, and the token map lives server-side. In shared mode only the last successful result carries the combined session_state or session_id for the whole batch.

POST /v1/batch/detect

Detect entities across many inputs in one request. Requires the batch scope.

Request

{
  "policy": "default",
  "include_values": false,
  "items": [
    { "text": "Erika Mustermann works at Musterfirma GmbH", "language": "de", "policy": "german-support" },
    { "text": "Contact erika.mustermann@example.com" }
  ]
}

Response

{
  "results": [
    {
      "index": 0,
      "entities": [
        { "type": "person", "value": "", "span": { "start": 0, "end": 15 }, "confidence": 0.95, "detector": "python_ner" }
      ]
    }
  ],
  "stats": { "total_items": 2, "total_entities": 1, "total_time_ms": 3.2 }
}

The value fields are empty strings because the request set include_values: false. That is also what an api-key caller sees by default in production: the raw detected value comes back only when the resolved include_values is true, which requires the detect_values scope. Each result carries its index and its detected entities (the same shape as /v1/detect). Per-item warnings mirror the single-item detect advisory (for example, the NER sidecar did not run), so a batch never hides degraded coverage. A failed item carries an error string and empty entities.

POST /v1/rag/ingest

Chunk a document and tokenize each chunk for safe vector-store ingestion. Requires the rag scope. The five RAG endpoints share one identity concept: corpus_id. When you pass the same corpus_id on ingest, query, and context, the same raw value tokenizes to the same token id across every document and query in that corpus, which is what lets a query entity align with an ingested document entity. Absent corpus_id, ids are session-scoped counters with random caps and cross-document alignment does not hold.

Request

{
  "text": "Max Mustermann opened case CR-4821 about his account.",
  "chunking_strategy": "paragraph",
  "chunk_size": 1000,
  "chunk_overlap": 100,
  "policy": "default",
  "language": "en",
  "corpus_id": "support-kb-2026",
  "document_metadata": { "document_id": "doc-001", "classification": "internal", "owner": "admin", "tags": ["support"] }
}

Response

{
  "chunks": [
    {
      "chunk_index": 0,
      "safe_text": "{{person:p_8a4f2c9d1e6b3a7f5c0d2e8b:1f3e5d7c9b2a4e6f8d0c1b3a5e7f9d2c}} opened case CR-4821 about his account.",
      "entity_count": 1,
      "start_offset": 0,
      "end_offset": 54,
      "chunk_session_state": "eyJ2Ijox...chunk0"
    }
  ],
  "session_state": "eyJ2IjoxLCJz...",
  "total_entities": 1
}

Because this request passed a corpus_id, the token id and cap are corpus-derived (a 24-hex id suffix and a 32-hex cap) rather than the shorter p_001 per-request form; the same person yields the same token in every document and query of this corpus. CR-4821 stays raw here: a domain reference like a case number is tokenized only when the policy defines a matching custom_patterns entry (custom types render as {{custom:<name>:x_...:cap}} tokens), and detecting the person name requires the NER detector. Each chunk returns safe_text (store this in the vector DB) plus a per-chunk chunk_session_state, the sealed blob that holds only that chunk's tokens. Carry those back later as document_sessions on /v1/rag/context. The top-level session_state is shared across chunks, and warnings may advise that the NER sidecar did not run for a chunk (so undetected person/company/location may remain). Composing document_sessions into a context request requires a corpus_id shared by ingest, query, and context: without one each session mints ids from its own counter, so independently ingested documents can collide on the same id for different values. A /v1/rag/context call that carries document_sessions without a corpus_id is rejected with 400.

POST /v1/rag/ingest/batch

Ingest multiple documents in one request. Requires the rag scope. Each item is a full /v1/rag/ingest request body and is processed exactly like a single ingest, yielding its own chunks and its own sealed session, so documents never share a token map. The batch accepts up to max_batch_size items, and the rate limiter charges one token per document, not one per request. One item's failure never fails the batch.

Request

{
  "items": [
    { "text": "First support case ...", "chunking_strategy": "paragraph", "corpus_id": "support-kb-2026" },
    { "text": "Second support case ...", "corpus_id": "support-kb-2026" }
  ]
}

Response

{
  "results": [
    { "index": 0, "result": { "chunks": ["..."], "session_state": "eyJ2Ijox...", "total_entities": 2 } },
    { "index": 1, "error": "chunk_size must be at least 100" }
  ]
}

Each result carries its index (matching the request order) and exactly one of result (the same shape as a single /v1/rag/ingest response for that document) or error (a per-item failure message; the other items are unaffected).

POST /v1/rag/query

Tokenize a user query before vector search. Requires the rag scope.

Request

{
  "query": "What is Max Mustermann's account status?",
  "policy": "default",
  "language": "en",
  "corpus_id": "support-kb-2026"
}

Pass the same corpus_id used at ingest so the query's person token derives the same corpus-scoped id and cap as the document's.

Response

{
  "safe_query": "What is {{person:p_8a4f2c9d1e6b3a7f5c0d2e8b:1f3e5d7c9b2a4e6f8d0c1b3a5e7f9d2c}}'s account status?",
  "session_state": "eyJ2IjoxLCJxdWVye...",
  "entities_detected": 1
}

Send safe_query to your vector store; carry session_state into the following /v1/rag/context call.

POST /v1/rag/context

Tokenize the retrieved chunks and merge them into the query session. Requires the rag scope.

Request

{
  "chunks": ["Raw retrieved chunk about Max Mustermann ..."],
  "session_state": "eyJ2IjoxLCJxdWVye...",
  "policy": "default",
  "language": "en",
  "access_level": "internal",
  "chunk_classifications": ["internal"],
  "document_sessions": ["eyJ2Ijox...chunk0"],
  "corpus_id": "support-kb-2026"
}

Response

{
  "safe_chunks": ["{{person:p_8a4f2c9d1e6b3a7f5c0d2e8b:1f3e5d7c9b2a4e6f8d0c1b3a5e7f9d2c}} ..."],
  "session_state": "eyJ2IjoxLCJjdHh0...",
  "entities_detected": 3,
  "chunks_filtered": 0
}

safe_chunks are the tokenized chunks for the LLM prompt (filtered chunks are omitted). chunks_filtered counts how many were dropped by access_level (omitted when zero).

POST /v1/rag/answer

Rehydrate the LLM's answer using the accumulated RAG session. Requires the rag scope.

This endpoint does not call a model and does not generate an answer. You call your LLM yourself, then post its tokenized reply here as answer; the endpoint restores the tokens in it and returns restored_answer. answer is required. /v1/rag/answer/metadata runs the identical restore but returns only tokens_resolved and tokens_unresolved: the restored answer is dropped inside the runtime and never serialized, so a caller outside the trust boundary (the MCP server) never receives restored PII.

Request

{
  "answer": "The account for {{person:p_8a4f2c9d1e6b3a7f5c0d2e8b:1f3e5d7c9b2a4e6f8d0c1b3a5e7f9d2c}} is active.",
  "session_state": "eyJ2IjoxLCJjdHh0...",
  "output_channel": "user_output"
}

output_channel (default user_output) selects the restore rules, exactly as /v1/rehydrate.

Response

{
  "restored_answer": "The account for Max Mustermann is active.",
  "tokens_resolved": 1,
  "tokens_unresolved": []
}

POST /v1/rag/delete

Forget every value in a session, so any later rehydrate resolves it to [DELETED]. Requires the revoke scope. To erase one document, pass that document's ingest session_state.

Request

{ "session_state": "eyJ2IjoxLCJp..." }

Response

{
  "deleted": true,
  "session_invalidated": true,
  "entities_purged": 5,
  "message": "Session a1b2c3d4e5f60718 invalidated (5 entities). Application should delete corresponding vector store chunks.",
  "manifest": {
    "session_fingerprint": "a1b2c3d4e5f60718",
    "entities_revoked": 5,
    "timestamp_unix": 1700000000,
    "status": "completed"
  }
}

The manifest is a PII-free deletion receipt for a GDPR / audit trail. It carries no raw session id, token, or value: the erased corpus/document is identified only by the one-way session_fingerprint (the same fingerprint the audit log records), entities_revoked is the number of values revoked from the store, and timestamp_unix is when the deletion was recorded.

status is the terminal outcome of a success. Every success state returns 200; none is a retry signal.

Failure responses

A delete can also fail. Each failure is retryable and converges on a keyed retry (send the same Idempotency-Key); none pins a committed error.

Audit reconstruction

Each attempt shares one trace_id across its audit records: one rag_delete_intent (write-ahead) followed by at most one rag_delete terminal. A terminal with no failure is a fully completed erasure; a terminal that names a failure reason (session_removal_failed, persistence_failed, or rollback_incomplete) records what survived. An intent with no terminal is an attempt that was cut off before it finished, and the next attempt's terminal is authoritative. There is no server-side reconciliation worker: convergence requires a keyed retry, and a retained encrypted record expires at the session TTL.

POST /v1/transform/image

Extract text from an uploaded image with OCR, then tokenize any detected PII. Requires the transform scope. The official server Docker image bundles Tesseract with English, German, and Arabic language data, so this endpoint works out of the box in that image. The native release binary needs Tesseract installed on the host. When Tesseract is absent, the endpoint fails closed with 503 GUARDAI_OCR_UNAVAILABLE while the text and JSON endpoints keep working.

Request

Multipart form (Content-Type: multipart/form-data):

curl -H "X-API-Key: your-key" \
  -F "image=@scan.png" -F "language=de" \
  http://localhost:3000/v1/transform/image

The form is strict: an unknown field, a nameless part, or a repeated field is rejected with 400 GUARDAI_BAD_REQUEST before entitlement or OCR runs, and the language control field is capped at 255 bytes. A blank language falls back to the server default, matching the JSON transform body.

If OCR yields no readable text, or cannot read the text with enough confidence to prove it free of PII, the endpoint refuses with 422 GUARDAI_OCR_UNVERIFIABLE rather than release unverified pixels. A language the resolver cannot recognize is rejected with 400 GUARDAI_OCR_LANGUAGE_UNRECOGNIZED (use an ISO or Tesseract code such as de, en, or chi_tra), so an image is never scanned with the wrong model.

Response

{
  "safe_text": "Rechnung an {{person:p_001:9f2c4a7b1e8daa11bb22cc33dd44ee55}}, {{email:e_001:5873cc5722d8aa11bb22cc33dd44ee55}}",
  "entities": [
    {
      "entity_type": "person",
      "token": "{{person:p_001:9f2c4a7b1e8daa11bb22cc33dd44ee55}}",
      "bounding_box": { "left": 120, "top": 48, "width": 180, "height": 22 },
      "confidence": 0.94
    }
  ],
  "bounding_boxes": [ { "left": 120, "top": 48, "width": 180, "height": 22 } ],
  "session_id": "01916a3e-7b2c-7000-8000-000000000001",
  "session_state": "eyJ2IjoxLCJ..."
}

safe_text is the OCR text with tokens in place. Each entities item maps a detected token to its bounding_box (pixel coordinates) in the image; bounding_boxes is the flat list of those regions. warnings carries the same NER-sidecar advisory as text transform.

POST /v1/redact/image

Return the uploaded image with PII regions blacked out. Requires the transform scope. Redaction blacks out every detected PII region regardless of policy action (a policy allow is still visually redacted), and it drops the policy's ner_min_confidence floor so it does not under-redact. It honors the tenant policy's custom_patterns and required_for (fail closed if a required NER detector is down). Same 503 GUARDAI_OCR_UNAVAILABLE behavior when Tesseract is absent.

Request

Multipart form with an image file (PNG, JPEG, TIFF, BMP), plus an optional language control. The form is strict: an unknown field, a nameless part, or a repeated field is rejected with 400 GUARDAI_BAD_REQUEST before entitlement or OCR runs, and language is capped at 255 bytes. As with /v1/transform/image, an image whose text cannot be read or verified free of PII is refused with 422 GUARDAI_OCR_UNVERIFIABLE, and an unrecognized language with 400 GUARDAI_OCR_LANGUAGE_UNRECOGNIZED.

curl -H "X-API-Key: your-key" \
  -F "image=@scan.png" \
  http://localhost:3000/v1/redact/image --output redacted.png

Response

200 OK with Content-Type: image/png: the raw redacted image bytes (not JSON).

POST /v1/transform/stream and POST /v1/rehydrate/stream

Stream the result as Server-Sent Events. transform/stream requires the transform scope, rehydrate/stream the rehydrate scope. Both run the full pipeline first, then stream the finished text in token-boundary-aware chunks: transform streams safe_text, rehydrate streams restored_text. Request bodies are the same JSON as /v1/transform and /v1/rehydrate.

Each SSE data: frame is a JSON object. Content frames carry { "chunk": "...", "complete": false }. The final frame carries "complete": true plus the session metadata: transform adds session_state, session_id, and stats; rehydrate adds tokens_resolved, tokens_unresolved, and stats. If a detection error occurs mid-stream, a single frame { "error": "...", "complete": true } is emitted and the connection closes; partial results are not recoverable.

POST /v1/transform/file and POST /v1/rehydrate/file

Process an uploaded document. transform/file requires the transform scope, rehydrate/file the rehydrate scope.

transform/file takes a multipart form with file (required), plus optional policy and language fields. The form is strict: an unknown field, a nameless part, or a repeated field is rejected with 400 GUARDAI_BAD_REQUEST before extraction runs, and each control field is capped at 255 bytes. policy and language carry the same meaning as in the JSON transform body: an empty policy is treated as a named policy (and rejected as unknown), and a blank language falls back to the server default. Supported extensions are pdf, txt, csv, html, htm, md, and docx. A PDF or DOCX is also recognized by its magic bytes, and that signature wins over a disagreeing extension. A PDF is read from its embedded text layer only, so a scanned page yields no text and belongs on /v1/transform/image. The endpoint extracts the text and runs the standard transform over the whole document in one pass, returning JSON:

{
  "safe_text": "...tokenized document text...",
  "entities": [ /* diagnostic entity list */ ],
  "session_id": "01916a3e-...",
  "session_state": "eyJ2IjoxLCJ...",
  "original_format": "Pdf",
  "original_size": 84213,
  "stats": { "entities_detected": 3, "entities_transformed": 3 }
}

rehydrate/file delegates to the standard text rehydrate; send the RehydrateRequest JSON body (it does not take a file). session_state is required.

Document failures are classified, not all blamed on the upload

A failed extraction returns one of three statuses, and they mean different things. Do not treat every non-200 as a bad file:

The 503 body is a fixed message; the cause is recorded in the server logs rather than returned, because the underlying error can carry filesystem paths and document fragments.

POST /v1/revoke, POST /v1/revoke/bulk, GET /v1/revocations/count

Revoke entity values so any later rehydrate resolves them to [DELETED]. Only an HMAC-SHA-256 digest of each value is stored; no raw PII is persisted. /v1/revoke and /v1/revoke/bulk require the revoke scope; /v1/revocations/count requires the admin scope and returns a scope-local count (the caller's own tenant, or the unscoped partition for a platform admin), never a cross-tenant total.

If a compensating rollback after a failed durable persist is incomplete, /v1/revoke and /v1/revoke/bulk fail closed with 500 GUARDAI_REVOCATION_STATE_INCONSISTENT rather than acknowledge an inconsistent state. A retry is safe: the idempotent re-insert converges the store and records the audit.

POST /v1/revoke

{ "entity_type": "email", "value": "erika.mustermann@example.com" }

Response:

{
  "revoked": true,
  "entity_type": "email",
  "total_revoked": 1,
  "message": "Entity value revoked. Future rehydration will return [DELETED] for this value."
}

total_revoked (the global total) is present only for unscoped platform admins; it is omitted for a tenant-scoped caller so the cross-tenant revocation volume is not disclosed.

POST /v1/revoke/bulk

{
  "entities": [
    { "entity_type": "email", "value": "erika.mustermann@example.com" },
    { "entity_type": "person", "value": "Erika Mustermann" }
  ]
}

Response: { "revoked_count": 2, "total_revoked": 5 } (again, total_revoked is admin-only).

GET /v1/revocations/count

Returns { "total_revoked": 42 }, where the value is the number of revocations in the caller's own scope. A tenant-authenticated caller sees only its own tenant's revocations; an unscoped platform-admin caller sees only the unscoped (global-scope) revocations. The store partitions digests by tenant, so one tenant can never observe another tenant's revocation volume through this count. Requires the admin scope. On the shared (Redis) backend, a store that still holds revocations recorded before per-scope indexing returns 409 GUARDAI_REVOCATION_COUNT_UNAVAILABLE rather than a possibly wrong number. One unattributable digest breaks the count invariant, so this degrade is store-wide (every tenant's count returns 409, not just the affected scope) until those digests drain: they re-index when each value is revoked again, or an operator clears the store (which drops every tenant's revocations, so prefer draining by re-revoke).

POST /v1/sessions/status, DELETE /v1/sessions

Inspect or invalidate a session by its lifecycle. Both require the session scope. The session is identified in the JSON body (never the URL): pass exactly one of session_id or the sealed session_state blob, so a bearer credential never lands in an access log. A missing or cross-tenant session is a non-disclosing 404 GUARDAI_SESSION_NOT_FOUND, so a caller cannot probe another tenant's session ids.

POST /v1/sessions/status

Reports whether a session is live and, when it is, its backend, expiry, and entity count.

{ "session_state": "eyJ2IjoxLCJz..." }

Response:

{
  "status": "active",
  "backend": "sealed",
  "expires_at": 1700003600,
  "entity_count": 3
}

status is one of active, stateless, deleted, or not_found. backend is the active session backend (sealed, memory, or redis). expires_at (Unix seconds) and entity_count are present only for a live session. On the sealed backend, where the caller holds the only copy of the state, the status is stateless.

DELETE /v1/sessions

Removes a server-held session (memory or redis backend). Mapped entity values are not revoked here; use /v1/revoke or /v1/rag/delete for value erasure.

{ "session_id": "01916a3e-7b2c-7000-8000-000000000001" }

Response:

{ "deleted": true, "status": "deleted" }

deleted is true only when a server-held session was actually removed. The sealed backend has no server-side state to remove, so it returns { "deleted": false, "status": "stateless" }.

POST /v1/entity-types and POST /v1/patterns

Both endpoints are validate-only. Nothing is persisted: they run the same name and pattern compilation a transform runs and report whether it would be accepted, so a custom detector can be checked before it is deployed. Pass the validated pattern inline as custom_patterns on the next transform or detect request.

Request

{ "name": "ticket_ref" }

{
  "custom_pattern": {
    "entity_type": "ticket_ref",
    "pattern": "TKT-[0-9]{1,10}",
    "confidence": 0.9,
    "context_words": ["ticket"]
  }
}

The first body is POST /v1/entity-types (name only), the second is POST /v1/patterns. A name must match [a-z0-9_-]+ and must not shadow a built-in entity type. confidence defaults to 0.8, context_words to empty, and value_group restricts the tokenized span to one capture group.

Response

{
  "custom_pattern": {
    "entity_type": "ticket_ref",
    "pattern": "TKT-[0-9]{1,10}",
    "confidence": 0.9,
    "context_words": ["ticket"],
    "value_group": null
  },
  "entity_type": "custom:ticket_ref",
  "scope": "request",
  "persisted": false,
  "max_patterns_per_request": 128
}

scope: "request" and persisted: false state the contract plainly: validation does not register anything, so every request that wants the detector must carry it. /v1/entity-types returns the name, its custom:<name> form, and the x_ token id prefix policy-defined custom types share.

Custom pattern constraints

A refused pattern is a 400 carrying the reason: GUARDAI_BAD_REQUEST from POST /v1/patterns, GUARDAI_INVALID_INPUT when it arrives inline on transform or detect. Two rules decide it. They apply identically to this endpoint, to inline custom_patterns, and to a policy's custom_patterns at load:

1. Bounded match length. An open-ended quantifier (+, *, {n,}) is refused: TKT-[0-9]+ is rejected, TKT-[0-9]{1,10} is accepted. A streamed response withholds a trailing window of at most 8192 bytes while an entity assembles, so a match that can outgrow the window would put the leading bytes of a real value on the wire before it could be masked. This is a trust-boundary requirement, not a performance limit. Length is measured on normalized text, where a whitespace run is already collapsed, so \s* between two parts of a pattern stays bounded; a class mixing whitespace with other characters ([:\s]*) does not. The pattern source is capped at 2000 bytes.
2. Discriminating shape. A pattern that matches the empty string or arbitrary text (.*, \w+, \p{L}+, or a bare \d{1,10}) is refused, because it would mask everything rather than an identifier.

The error names the entity type and the rule, never the pattern text, since an operator-authored regex can itself contain a literal value. max_patterns_per_request is the ceiling on the merged set (a policy's patterns plus the inline ones) a single request may carry. Full authoring guidance: Extending Entities.

GET /v1/health

Returns runtime health status plus the deployment's licence. Requires auth when auth is enabled. Use /livez or /readyz for unauthenticated probes.

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600.5,
  "components": {
    "detector": { "status": "healthy", "message": "builtin_and_ner (full entity detection)" },
    "session": { "status": "healthy", "message": "sealed" },
    "policies": { "status": "healthy", "message": "4 policies loaded" }
  },
  "license": {
    "status": "valid",
    "edition": "business",
    "release_date": "2026-07-29",
    "license_id": "lic-000007",
    "customer_id": "nordwind",
    "customer_name": "Musterversicherung AG",
    "updates_until": "2027-01-15",
    "declared_edition": "business",
    "contract": {
      "deployment_allowance": 2,
      "support_level": "standard",
      "reference": "ORD-4471"
    }
  }
}

Status values: healthy, degraded, unhealthy. The detector component reports the CONFIGURED detector mode, not live sidecar reachability, so it does not flip on an NER outage.

The license block

Verification is not operative in this release. No verifying key is compiled into the binary, so the server cannot check a licence file at all: a correctly signed licence and a forged one are indistinguishable to it. Any licence it can read reports "status": "malformed" with a reason naming the missing key, "edition": "developer", and no identity fields. The valid example above is what the block reports once a release ships the key. Only a licence file that cannot be read or is oversized refuses a non-dev start.

The server optionally loads a signed licence file (GUARDAI_LICENSE_FILE), resolves it once at startup, and reports the result here. Resolution checks an Ed25519 signature against a compiled-in key; the check is local, so the runtime never contacts Oronts and an air-gapped deployment behaves identically.

Nothing is gated by the licence. No capability is withheld and no request takes a different path because of it. Do not branch client behaviour on this block; read it for inventory and support.

The identity and contract fields (license_id, customer_id, customer_name, updates_until, declared_edition, contract) are a per-deployment operator fact, so the server discloses them only to an admin-scoped caller. A non-admin credential gets the verdict fields (status, edition, release_date) an integration needs, with the identity and contract fields omitted.

The block never carries the signature, key material, or entitlement flags. Absent fields are omitted rather than sent as null, so an unlicensed deployment reports {"status": "absent", "edition": "developer", "release_date": "..."} and nothing else.

version_cutoff means the running binary was published after updates_until. Enforcement is on the VERSION axis, comparing the compiled-in release date against updates_until, never a wall clock, so no running process changes behaviour because a date passed. That grading sits behind verification, so neither valid nor version_cutoff is reachable until a release ships a verifying key. See Licensing for the start behaviour behind each status.

GET /v1/capabilities

Returns supported entity types, languages, available detectors, restore modes, the batch size limit, and the per-session budget (max_session_entities, max_session_bytes). Requires auth when auth is enabled.

{
  "entity_types": [
    { "name": "person", "protection_level": "2", "source": "ner", "id_prefix": "p_" },
    { "name": "email", "protection_level": "2", "source": "builtin", "id_prefix": "e_" },
    { "name": "ssn", "protection_level": "1", "source": "builtin", "id_prefix": "ss_" }
  ],
  "languages": [
    { "code": "de", "name": "German", "detection_support": "full", "rehydration_support": "full" }
  ],
  "detectors": [
    { "name": "builtin_regex", "type": "builtin", "entity_types": ["email", "phone", "ssn"] }
  ],
  "restore_modes": ["full", "partial", "masked", "formatted", "abstract", "none"],
  "ner_active": true,
  "max_batch_size": 100,
  "max_session_entities": 20000,
  "max_session_bytes": 8388608,
  "detection_floor": { "entity_types": ["email", "person", "company", "location"], "ner_required": true }
}

max_batch_size is the maximum number of items accepted by /v1/batch/transform and /v1/batch/detect in a single request (a ceiling of 100, lowerable via limits.max_batch_size).

max_session_entities and max_session_bytes report the per-session budget that backs 422 GUARDAI_SESSION_TOO_LARGE, so a client can size its session before a transform is refused. An optional gender_inference object is present only when a name-gender overlay is installed.

Each entity_types entry also carries a source field that tells the fixed built-in floor apart from the policy or config-extensible surface: builtin (a universal-PII-format regex detector), builtin_custom (a built-in custom detector such as money or de_tax_id), ner (detected by the NER model, for example person, company, location), config_custom (added by this deployment's detector config), or policy_custom (defined by a loaded policy's custom_patterns). An optional description may accompany a type, and each language may report rehydration_support alongside detection_support. ner_active reflects the configured mode, not live sidecar reachability; monitor GUARDAI_DETECTION_UNAVAILABLE (a sidecar outage under a policy that requires NER) and GUARDAI_DETECTION_FAILED (a capability rejection) for sidecar issues.

detection_floor reports the types a request under the default policy cannot succeed without, and whether that policy fails closed when NER did not run (ner_required). It is derived from the same predicates the request path enforces, so a builtin-only server reports ner_required: false with only the regex types, while a server whose default policy floors NER (for example default-ner-required) reports ner_required: true with person, company, and location included. Informational; a server predating the field omits it.

Error Codes

All error responses follow this format:

{
  "error": "Human-readable description",
  "code": "ERROR_CODE",
  "details": "optional additional context",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Every error response carries a request_id (a fresh UUID generated per error), so a caller can correlate a failure with the server logs. details and request_id are omitted when null.

Note: The two output guard codes are not interchangeable. 503 GUARDAI_OUTPUT_GUARD_UNAVAILABLE means the scan itself could not run or could not complete (no output NER scanner is installed where the policy requires one, the scanner answered without running the required pass, a detector errored, or the guard could not render a replacement), so the content was never judged and the same request may succeed once the deployment is fixed. 422 GUARDAI_OUTPUT_BLOCKED means the content was judged and refused, so retrying the same content will not help. Both withhold the response; only the 503 is worth retrying. The restore endpoints that run the output guard are /v1/rehydrate, /v1/rehydrate/metadata, /v1/rehydrate/stream, /v1/rehydrate/file, /v1/rag/answer, and /v1/rag/answer/metadata.

For machine-readable schemas, see schemas/openapi.yaml (the canonical description of every route the server mounts) and the per-endpoint JSON Schema files under schemas/api/. The API Explorer lists which endpoints have a dedicated schema file.