HTTP API

The decision service puts the embedded engine behind REST, Server-Sent Events and WebSocket, so services in any language can use it. This page lists every endpoint, its JSON and its current limits.

Running the service#

The service evaluates in-process: no model calls and no outbound network traffic. Base URL in the examples: http://127.0.0.1:18734. See Services and Serve decisions to other languages.

Authentication and origins#

• Bearer token. When the service has a token (--token, token= or HELIXOR_SERVICE_TOKEN), every request except GET /v1/health and CORS preflight must send Authorization: Bearer <token>. Otherwise HTTP answers 401 with {"detail": "Missing or invalid bearer token"} and a WWW-Authenticate: Bearer header, and a WebSocket is closed with code 1008. Without a token the service has no authentication.
• Binding. The default host is 127.0.0.1. Starting on any non-loopback address without a token fails with ServerConfigurationError.
• CORS. Off by default. HELIXOR_CORS_ORIGINS takes a comma-separated list of browser origins; credentials are allowed only for those. An origin containing * is rejected at startup.
• One engine. A service that serves a compiled pack answers 400 to a request that sets license_key, so a caller cannot swap in another engine.

Errors#

See Errors. A client must treat any non-200 response, timeout or connection failure as "do not proceed".

GET /v1/health#

Liveness and metadata. It needs no token. pack_id and engine_edition (the license tier) describe the engine actually being served, so a readiness check can compare them with what you deployed. regulatory_rules lists the rules the served engine evaluates: the built-in checks, plus a compiled pack's own rules with "source": "pack". supported_regulations is derived from it. The response from the built-in pack on runtime 0.3.1:

{
  "status": "healthy",
  "service": "helixor-decision-demos",
  "version": "1.1.0",
  "engine_edition": "COMMUNITY",
  "pack_id": "compliance.regulatory_pii_guard.v1",
  "supported_protocols": ["REST", "SSE", "WebSocket"],
  "supported_regulations": ["CCPA", "FCRA", "GDPR", "GLBA", "HIPAA", "PCI-DSS", "TCPA"],
  "regulatory_rules": [
    {"rule_id": "RULE-GLBA-SSN-BLOCK", "regulations": ["FCRA", "GLBA"], "source": "builtin"},
    {"rule_id": "RULE-PCI-DSS-PAN-BLOCK", "regulations": ["PCI-DSS"], "source": "builtin"},
    {"rule_id": "RULE-HIPAA-PHI-BLOCK", "regulations": ["HIPAA"], "source": "builtin"},
    {"rule_id": "RULE-GDPR-EMAIL-REDACT", "regulations": ["CCPA", "GDPR"], "source": "builtin"},
    {"rule_id": "RULE-TCPA-PHONE-REDACT", "regulations": ["CCPA", "TCPA"], "source": "builtin"},
    {"rule_id": "RULE-GDPR-IP-REDACT", "regulations": ["GDPR"], "source": "builtin"}
  ],
  "decision_functions": ["evaluate", "solve_constraints", "vrp"]
}

POST /v1/evaluate#

Evaluates one payload and returns the full result.

POST /v1/evaluate HTTP/1.1
Content-Type: application/json

{"text": "Employee note: SSN is 123-45-6789, email jane@example.com."}

{
  "pack_id": "compliance.regulatory_pii_guard.v1",
  "action": "block_glba_ssn_leakage",
  "invariants_passed": false,
  "reason": "Statutory violation: Social Security Number (GLBA / FCRA) detected",
  "triggers": [
    {
      "rule_id": "RULE-GLBA-SSN-BLOCK",
      "law": "Gramm-Leach-Bliley Act & FCRA",
      "severity": "FATAL",
      "matched_items": ["123-45-6789"]
    },
    {
      "rule_id": "RULE-GDPR-EMAIL-REDACT",
      "law": "GDPR Article 6 & CCPA",
      "severity": "WARNING",
      "matched_items": ["jane@example.com"]
    }
  ],
  "remedy": {
    "clean_text": "Employee note: SSN is [REDACTED_SSN], email [REDACTED_EMAIL].",
    "redactions_count": 2,
    "redacted_categories": ["SSN (GLBA/FCRA)", "Email (GDPR/CCPA)"]
  },
  "latency_us": 70.12,
  "tokens_spent": 0,
  "egress_bytes": 0,
  "receipt_hash": "hx_proof_5b46797af4f9af1e982eabe8",
  "license_status": "COMMUNITY_PERPETUAL",
  "active_key_id": "hx_lic_community_developer_ep1_0",
  "active_epoch": 1,
  "edition": "COMMUNITY",
  "upgrade_notice": "Free Community Edition: …"
}

The first evaluation after start-up is slower than later ones; the latency above is from a first call. The fields are described under EvaluationResult in the Python reference.

curl -s http://127.0.0.1:18734/v1/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"text": "Card 4111-1111-1111-1111"}' | jq '{action, clean: .remedy.clean_text}'

POST /v1/evaluate/stream#

Returns text/event-stream. You send the whole text; the server cuts it into chunk_size-character pieces and pushes them through a streaming session. That simulates a token stream, which makes the endpoint useful for testing streaming behavior. It cannot filter a stream your application is receiving; use the WebSocket for that.

Each event is one line, data: <StreamChunkResult JSON>, followed by a blank line. After a "blocked": true event the stream ends.

data: {"chunk_index": 1, "text": "Call ", "is_final": false, "redacted": false, "blocked": false, "action": "stream_token", "reason": null, "triggers": []}

data: {"chunk_index": 2, "text": "[REDACTED_PHONE] today, ask for Jane.", "is_final": true, "redacted": true, "blocked": false, "action": "stream_token", "reason": null, "triggers": []}

That is the real output for {"text": "Call (415) 555-0100 today, ask for Jane.", "chunk_size": 6}. Chunk boundaries fall at delimiters the lookahead window allows, never inside a value or a redaction token. redacted is true on exactly the chunks whose text was changed. Concatenate chunk text before you display or store it; the result equals the /v1/evaluate clean_text.

POST /v1/decision#

A single dispatcher for decision functions, with optional license checks on each request.

{"domain": "evaluate", "parameters": {"text": "Contact jane@example.com"}}

{
  "function": "evaluate",
  "status": "success",
  "latency_us": 31.75,
  "result": { "action": "redact_and_permit_contact_pii", "remedy": {"clean_text": "Contact [REDACTED_EMAIL]", "…": "…"}, "…": "…" }
}

result is the same object /v1/evaluate returns. The other domain values (vrp/fleet, bin_packing/packing, solve_constraints/solver) call engines that are out of scope for this edition of the reference. Unknown values return 400.

WS /v1/ws/decision#

A persistent connection for many evaluations or for live stream filtering. Send and receive one JSON object per message. The connection uses the service's engine (your pack under serve); license_key is not accepted here. When the service has a token, send it in the Authorization header of the upgrade request.

A message without type is treated as evaluate. Messages are handled in order on each connection. A {"type": "solve"} message also exists; it is out of scope for this edition. If a handler raises, the server sends {"type": "error"} and closes the connection.

→ {"type": "stream_start"}
← {"type": "stream_started", "lookahead_chars": 28}
→ {"type": "stream_chunk", "token": "Reach me at jane@example.com or on the phone any time this week please."}
← {"type": "stream_token", "token": "Reach me at [REDACTED_EMAIL] or on the ", "blocked": false, "action": "stream_token", "reason": null}
→ {"type": "stream_flush"}
← {"type": "stream_token", "token": "phone any time this week please.", "blocked": false, "action": "stream_token", "reason": null}
← {"type": "stream_completed"}

The same connection after a block:

→ {"type": "stream_start"}
← {"type": "stream_started", "lookahead_chars": 28}
→ {"type": "stream_chunk", "token": "SSN 123-45-6789 and more text to pass the window"}
← {"type": "stream_token", "token": "", "blocked": true, "action": "block_glba_ssn_leakage", "reason": "Statutory violation: Social Security Number (GLBA / FCRA) detected"}
→ {"type": "stream_chunk", "token": " Patient in room 402."}
← {"type": "error", "code": "STREAM_BLOCKED", "message": "The stream was blocked by a fatal invariant; send stream_start to begin a new stream.", "action": "block_glba_ssn_leakage", "reason": "Statutory violation: Social Security Number (GLBA / FCRA) detected"}
→ {"type": "stream_start"}
← {"type": "stream_started", "lookahead_chars": 28}