OGuardAI
API Reference

API Reference

Complete API reference for all OGuardAI v1 endpoints including transform, rehydrate, detect, policy evaluation, health, and capabilities

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

Endpoint Table

MethodPathDescriptionAuth Required
POST/v1/transformTransform text, replacing entities with semantic tokensYes (if enabled)
POST/v1/transform/streamStreaming transform (SSE)Yes (if enabled)
POST/v1/transform/fileTransform an uploaded file (multipart)Yes (if enabled)
POST/v1/transform/imageTransform text detected in an imageYes (if enabled)
POST/v1/rehydrateRestore semantic tokens in LLM output to original valuesYes (if enabled)
POST/v1/rehydrate/streamStreaming rehydrate (SSE)Yes (if enabled)
POST/v1/rehydrate/fileRehydrate an uploaded file (multipart)Yes (if enabled)
POST/v1/detectDetect entities without transformingYes (if enabled)
POST/v1/batch/transformBatch transform multiple inputs in one requestYes (if enabled)
POST/v1/batch/detectBatch detect entities in multiple inputsYes (if enabled)
POST/v1/evaluate-policyEvaluate policy against entities (dry run)Yes (if enabled)
POST/v1/rag/ingestIngest a document for RAG with PII protectionYes (if enabled)
POST/v1/rag/queryQuery RAG index with PII-safe contextYes (if enabled)
POST/v1/rag/contextRetrieve RAG context chunks (tokenized)Yes (if enabled)
POST/v1/rag/answerGenerate a RAG answer with automatic rehydrationYes (if enabled)
POST/v1/rag/deleteDelete ingested RAG documentsYes (if enabled)
POST/v1/revokeRevoke a single entity (makes it non-restorable)Yes (if enabled)
POST/v1/revoke/bulkRevoke multiple entities in one requestYes (if enabled)
GET/v1/revocations/countGet the count of revoked entitiesYes (if enabled)
POST/v1/redact/imageRedact PII regions in an imageYes (if enabled)
POST/v1/admin/policy/validateValidate policy configuration filesYes (admin scope)
GET/v1/healthHealth checkNo (always public)
GET/v1/capabilitiesList entity types, languages, detectorsNo (always public)
GET/v1/diagnosticsRuntime diagnostics (detector mode, config, versions)Yes (Admin scope required)
GET/metricsPrometheus metrics endpointYes (Admin scope required)

Port note: Examples below use port 8080 (Docker quick start). For other deployments, use the appropriate port (default: 3000).

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 ...

JWT tokens are validated against the configured JWKS endpoint.

Scopes

The runtime currently supports 5 scopes:

ScopeGrants Access To
transform/v1/transform, /v1/transform/stream, /v1/transform/file, /v1/transform/image, /v1/batch/transform
rehydrate/v1/rehydrate, /v1/rehydrate/stream, /v1/rehydrate/file
detect/v1/detect, /v1/batch/detect
policy/v1/evaluate-policy
adminAll endpoints including /v1/admin/policy/validate and config management

Note: rag and revoke scopes are not yet implemented in the auth runtime. RAG and revoke endpoints currently require one of the existing scopes (typically transform or admin).

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

POST /v1/transform

Transform input text, replacing detected entities with semantic tokens.

Request

{
  "input": "Contact Julia Schneider at julia@firma.de",
  "input_type": "text",
  "policy": "default",
  "language": "de",
  "session_state": "(optional sealed blob from previous transform)",
  "detectors": ["builtin-regex"],
  "context": {
    "destination": "external_llm",
    "provider": "openai",
    "model": "gpt-4o"
  }
}
FieldTypeRequiredDescription
inputstringYes (for text)Raw input text
input_typestringNo"text" (default), "json", or "chat_messages"
input_jsonobjectFor JSON modeStructured JSON with field-level transformation
input_messagesarrayFor chat modeOpenAI-format message array [{role, content}]
languagestringNoISO 639-1 hint (auto-detected if omitted)
policystringNoPolicy name (uses server default if omitted)
session_idstringNoExisting session ID for multi-turn continuity
session_statestringNoSealed session blob from previous transform
detectorsstring[]NoExplicit detector list (all if omitted)
protection_overridesobjectNoPer-entity-type action overrides
contextobjectNoDestination, provider, model, max_tokens

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

Response

{
  "safe_text": "Contact {{person:p_001}} at {{email:e_001}}",
  "session_id": "01916a3e-7b2c-7000-8000-000000000001",
  "session_state": "eyJ2IjoxLCJzaWQiOi...",
  "entity_context": [
    {
      "token": "{{person:p_001}}",
      "type": "person",
      "gender": "female",
      "formality": "formal",
      "language": "de"
    }
  ],
  "entities": [
    {
      "token": "{{person:p_001}}",
      "type": "person",
      "protection_level": 2,
      "action_applied": "full",
      "confidence": 0.95,
      "detector": "builtin-regex",
      "metadata": { "gender": "female", "formality": "formal", "language": "de" },
      "span": { "start": 8, "end": 24 }
    }
  ],
  "stats": {
    "entities_detected": 2,
    "entities_transformed": 2,
    "entities_blocked": 0,
    "detection_time_ms": 1.2,
    "transform_time_ms": 0.3
  }
}
FieldDescription
safe_textTransformed text with semantic tokens. Send this to the LLM.
session_idSession identifier
session_stateSealed session blob. Pass this to rehydrate.
entity_contextSafe metadata for the LLM system prompt. Never contains raw values.
entitiesFull diagnostic metadata. For debugging, NOT for the LLM.
statsPerformance metrics

POST /v1/rehydrate

Restore semantic tokens in LLM output to their original values.

Request

{
  "output": "Dear {{person:p_001}}, your order {{order:o_001}} has shipped.",
  "session_state": "eyJ2IjoxLCJzaWQiOi...",
  "output_channel": "customer_email",
  "restore_mode": "formatted",
  "restore_overrides": {
    "e_001": "none"
  }
}
FieldTypeRequiredDescription
outputstringYesLLM output containing {{type:id}} tokens
session_idstringNoSession ID from transform response
session_statestringNoSealed session blob from transform response
restore_modestringNoDefault restore mode: full, partial, masked, formatted, abstract, none
restore_overridesobjectNoPer-token overrides keyed by token ID
output_channelstringNouser_output, internal_summary, customer_email, tool_payload, export, log_safe

Response

{
  "restored_text": "Dear Frau Julia Schneider, your order ORD-2026-4892 has shipped.",
  "tokens_resolved": 2,
  "tokens_unresolved": [],
  "stats": {
    "rehydrate_time_ms": 0.8
  }
}

Restore Modes

ModeBehaviorPerson ExampleEmail Example
fullComplete original valueJulia Schneiderjulia@firma.de
partialDeterministic subsetJ. Schneiderj***@firma.de
maskedCharacter masking******* *********j*******************e
formattedOriginal + contextual formattingFrau Julia Schneiderjulia@firma.de (email)
abstractSemantic description(female customer)(email on file)
noneRemoved / redacted[REDACTED][REDACTED]

POST /v1/detect

Detect entities in text without performing transformation.

Request

{
  "input": "Email: test@example.com, SSN: 123-45-6789",
  "language": "en",
  "entity_types": ["email", "ssn"],
  "threshold": 0.5
}

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"]
  }
}

POST /v1/evaluate-policy

Evaluate a policy against entities without performing transformation. Useful for previewing what actions would be taken.

Request

{
  "policy": "strict-pii",
  "entities": [
    { "type": "person", "value": "Julia Schneider" },
    { "type": "ssn", "value": "123-45-6789" }
  ]
}

Response

{
  "decisions": [
    {
      "entity_type": "person",
      "action": "hard_mask",
      "protection_level": 1,
      "rule_matched": "strict-pii/person"
    },
    {
      "entity_type": "ssn",
      "action": "block",
      "protection_level": 1,
      "rule_matched": "strict-pii/ssn"
    }
  ],
  "policy_version": "1.0.0"
}

GET /v1/health

Returns runtime health status. Always public (no auth required).

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600.5,
  "components": {
    "detector_builtin": { "status": "healthy" },
    "session_backend": { "status": "healthy" },
    "policy_engine": { "status": "healthy" }
  }
}

Status values: healthy, degraded, unhealthy.

GET /v1/capabilities

Returns supported entity types, languages, and available detectors. Always public.

{
  "entity_types": [
    { "name": "person", "protection_level": 2, "id_prefix": "p_" },
    { "name": "email", "protection_level": 2, "id_prefix": "e_" },
    { "name": "ssn", "protection_level": 1, "id_prefix": "ss_" }
  ],
  "languages": [
    { "code": "de", "name": "German", "detection_support": "full" }
  ],
  "detectors": [
    { "name": "builtin-regex", "type": "builtin", "entity_types": ["email", "phone", "ssn"] }
  ],
  "ner_active": true
}

Error Codes

All error responses follow this format:

{
  "error": "Human-readable description",
  "code": "ERROR_CODE",
  "details": "optional additional context"
}
CodeHTTP StatusDescription
GUARDAI_INVALID_INPUT400Malformed request, missing fields, type mismatch
GUARDAI_AUTH_FAILED401Authentication is enabled but no credentials provided
GUARDAI_POLICY_DENIED403Policy blocks the detected entity type or credentials lack required scope
GUARDAI_SESSION_EXPIRED410Session TTL has elapsed or sealed blob failed integrity check
GUARDAI_OUTPUT_BLOCKED422Output guard blocked the response due to hallucinated PII
GUARDAI_TOKEN_REPAIR_FAILED422Token repair could not resolve tokens in LLM output
GUARDAI_DETECTION_FAILED500Detector service is down or detection failed
GUARDAI_INTERNAL_ERROR500Unexpected server error
GUARDAI_BAD_REQUEST400Generic bad request (e.g., missing field)
GUARDAI_PAYLOAD_TOO_LARGE413Request payload exceeds configured size limit

For full JSON schemas, see the product specification.

Multi-Tenant SaaS

How a SaaS platform serves three customers with different data protection policies using a single OGuardAI deployment

API Changelog

Breaking changes, new endpoints, and deprecations by version for the OGuardAI API

On this page

Endpoint TableAuthenticationAPI KeyJWT Bearer TokenScopesPOST /v1/transformRequestResponsePOST /v1/rehydrateRequestResponseRestore ModesPOST /v1/detectRequestResponsePOST /v1/evaluate-policyRequestResponseGET /v1/healthGET /v1/capabilitiesError Codes