HELIX Verify

Deterministic, auditable verification for generative output. Submit structured facts and a rule set; receive a signed pass/fail verdict with the reason for every rule. Verdicts are reproducible and tamper-evident.

How it works

HELIX verifies facts against rules. You describe what a piece of content contains as structured facts, you describe the constraints it must satisfy, and HELIX returns a verdict together with a signed certificate. It is a checker, not a generator: it does not produce or alter content, and it does not evaluate your content directly. It evaluates the facts you or your extraction step provide about that content.

There are two request paths:

Authentication

Send your API key in the X-API-Key header on every request. All traffic is served over HTTPS; plaintext HTTP is not offered.

X-API-Key: your-api-key

Requests without a valid key are rejected with 401 before any processing occurs. Keys are issued per partner and can be revoked independently.

Quickstart

Confirm connectivity:

curl https://verify.kuriakeplayground.online/v1/health
# {"status":"ok","engine_version":"1.0.0","deterministic":true,"configured":true}

Submit your first check:

curl -X POST https://verify.kuriakeplayground.online/v1/check \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{
    "ruleset_id": "brand-safety",
    "ruleset_version": "1.0",
    "rules": [
      {"id":"one_product","kind":"count","subject":"product","value":1},
      {"id":"no_text","kind":"absent","target":"text"}
    ],
    "observation": {"counts": {"product": 2}, "contains": ["text"]}
  }'

Guide: verifying text

Submit raw text to /v1/verify and name an extractor. The built-in pii-regex-v1 extractor identifies contact information in the text; your rules decide what is permitted.

curl -X POST https://verify.kuriakeplayground.online/v1/verify \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{
    "extractor": "pii-regex-v1",
    "content": "Questions? Email support@acme.com",
    "rules": [
      {"id":"no_email","kind":"absent","target":"email"},
      {"id":"no_phone","kind":"absent","target":"phone"}
    ]
  }'
# -> verdict: "fail", violation no_email: 'email' present but must be absent

Guide: verifying images

HELIX judges facts about an image, not the pixels themselves. There is no image upload endpoint. The intended flow:

1. Your generation model produces an image.
2. Your vision step (object detector, OCR, classifier, or similar) produces an observation - for example {"counts":{"product":1}, "contains":["logo"]}.
3. You submit that observation to /v1/check together with your policy.
4. Use verdict to gate or route the content; retain certificate for your audit trail.

Example policy: exactly one product, no visible text, brand mark required.

{
  "ruleset_id": "brand-safety", "ruleset_version": "1.0",
  "rules": [
    {"id":"one_product","kind":"count","subject":"product","value":1},
    {"id":"no_text","kind":"absent","target":"text"},
    {"id":"has_logo","kind":"present","target":"logo"}
  ],
  "observation": {"counts":{"product":1}, "contains":["logo"]}
}

A runnable example, including a sample vision step, is provided in the evaluation kit.

Certificates

Every response includes a signed certificate. Treat it as your compliance record and store it in full.

Two calls with identical inputs will always produce the same input_sha256; each still receives its own verification_id and issued_at, since each call is a distinct, independently signed event.

Reference

{
  "verdict": "fail",
  "passed": 1, "total": 2,
  "results": [
    {"id":"one_product","kind":"count","ok":false,"reason":"need 1 'product'; observed 2"},
    {"id":"no_text","kind":"absent","ok":true,"reason":"'text' absent as required"}
  ],
  "violations": [ "...the failing rules..." ],
  "certificate": { "verification_id":"vrf_...", "signature":"...", "..." : "..." }
}

curl -X POST https://verify.kuriakeplayground.online/v1/certificates/verify \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d @stored-response.json

# {"valid": true, "verification_id": "vrf_..."}

{"extractors":[
  {"id":"pii-regex-v1","deterministic":true},
  {"id":"llm-classifier-v1","deterministic":false}
]}

{"status":"ok","engine_version":"1.0.0","deterministic":true,"configured":true}

Rule vocabulary

Rules are drawn from a closed, fixed set of kinds; there is no expression language and no facility for arbitrary logic. Every rule carries an id that you choose (letters, digits, _ - ., maximum 128 characters) so results can be mapped back to your policy.

Observation object

The structured facts produced by your extractor or vision step:

Any field not listed above is rejected by the schema rather than silently ignored, so malformed observations fail fast with a 422.

Integers are validated strictly: "1" and true are rejected with a 422 rather than coerced to 1. Identifiers have surrounding whitespace trimmed before the pattern is applied, so "product " and "product" are the same identifier and produce the same input_sha256.

Errors

Every error response has the same shape, {"error": "..."}, regardless of which layer produced it - including errors raised at the edge before the request reaches the application. This is safe to log verbatim: no stack traces, file paths, or other internal detail are ever included in a response body.

Limits

• Request body: 64 KB maximum, enforced at the edge before the body is parsed. The cap applies to chunked requests as well as those declaring a Content-Length.
• Rules per request: 200 maximum.
• Identifiers (id, subject, target, field): pattern ^[A-Za-z0-9_\-.]+$, 128 characters maximum.
• Per-key request rate: fixed per your onboarding agreement. On 429, back off and retry; sustained excess is not queued.

Versioning

The API is versioned in the URL path (/v1/...). Within a major version, fields are only ever added, never removed or repurposed; treat unrecognized response fields as forward-compatible and ignore them rather than rejecting the response. A breaking change will be introduced under a new path prefix (/v2/...), never in place.

Security and privacy

• Stateless. No request content, facts, or verdicts are persisted by the service.
• No image ingestion. There is no endpoint that accepts image data; only derived facts are submitted.
• Signed verdicts. Every certificate is tamper-evident (HMAC-SHA256); altering any field invalidates the signature.
• Deterministic core. Given identical facts and rules, the verdict is always identical.
• All traffic is served over HTTPS. API keys are issued per partner and can be revoked without affecting other keys.

Evaluation kit

A small, self-contained script bundle that exercises this API end to end for both text and image verification, including a reference vision step for the image example, so the full flow can be inspected without writing integration code first. Set your endpoint URL and API key as environment variables, then run text_test.py and image_test.py. Provided separately alongside your API key.