API Reference

The PRIOR engine is a single native Rust server. It exposes an OpenAI-compatible inference endpoint with the Tri-State WHEN gate + golden-layer steering applied in-process, plus a governance surface under /admin, plus system endpoints. Default port 8089 (PRIOR_PORT).

One request path for proprietary controls. All PRIOR-specific per-request options ride a single prior_options object on POST /v1/chat/completions. A vanilla OpenAI client that never sends prior_options is unaffected (the gate still applies).

Base URL: http://<host>:8089 Auth: Authorization: Bearer <api-key>. /v1 user-auth is off by default and toggleable live (PATCH /admin/runtime or PRIOR_REQUIRE_AUTH); /admin always requires an Operator/Admin key.

Inference

POST /v1/chat/completions

OpenAI-compatible chat completion. messages are chat-templated server-side using the model's own template. The WHEN gate routes on the combined system+user intent (so a jailbreak in the system prompt is gated too), and steering is applied per the routing decision.

Request. Standard OpenAI fields plus the optional prior_options extension:

{
  "model": "prior",
  "messages": [
    {"role": "system", "content": "You are our support assistant."},
    {"role": "user", "content": "What port does our SSH service listen on?"}
  ],
  "max_tokens": 256,
  "stream": false,
  "prior_options": {
    "ephemeral_memory": {
      "target": "6022",
      "pin_phrase": "Our SSH service listens on port 6022"
    }
  }
}

Response. A standard OpenAI chat.completion object (or an SSE stream when stream: true). PRIOR telemetry is returned in response headers (additive; OpenAI clients ignore them).

On a YELLOW route the pack's confirm notice is also prepended to the message content (unless PRIOR_YELLOW_MODE=header), so header-blind UIs still surface it.

prior_options

steer object (advanced; you rarely need this, since the gate does it for you):

steer.logits_only is one-way. A request may opt into logits-only, but it can never opt out of it: if the engine selected logits-only for this model (because the architecture has no usable backward pass, or VRAM is tight), a request asking for L2LM is ignored rather than crashing. Set it globally with PRIOR_LOGITS_ONLY=1 or live via PATCH /admin/runtime.

Bring your own detector

PRIOR's cosine gate is a reference detector, not the product. If you have a classifier that knows your traffic better — an in-house model trained on your own data, a commercial safety classifier, a regex, a deny-list — you can drive PRIOR's enforcement from it directly.

Declare a pack with external_signal, then pass that detector's score on each request:

// the pack
{ "pack": "house_classifier", "external_signal": "house", "on_missing": "red",
  "tristate": { "t_low": 0.55, "t_high": 0.80 }, "enforcement": "hard", … }

// the request — you score first, then call
{ "model": "prior", "messages": [ … ],
  "prior_options": { "signals": { "house": 0.87 } } }

Three properties worth knowing:

• PRIOR never calls out. You score first and pass the result inline. There is no round-trip in the serving path, no second service to keep up, and no new failure mode between the request and the answer.
• The score is on your scale. A foreign score is not a zone. Calibrate the consuming pack's t_low/t_high against your detector's benign distribution, exactly as a cosine pack is calibrated against ours. PRIOR stores and enforces what you declare; it will not re-derive your thresholds, because re-deriving them from exemplars the pack does not have would replace your policy with a meaningless number.
• It composes. An external pack sits in the same precedence lattice as a cosine pack, so a classifier verdict and a membership boundary can both be live, and the more restrictive one wins.

on_missing decides what happens when the named signal is absent from a request — "red" fails closed, which is what you want if the detector going down should stop traffic rather than open the door.

Trust model: the /v1 caller is the operator's authenticated application, not the end user. A signals value is a statement by your backend, so treat the endpoint accordingly (PRIOR_REQUIRE_AUTH=1 whenever it is reachable beyond localhost).

Response headers (x-prior-*)

Emitted on /v1/chat/completions:

The response exposes the decision (zone, winning pack, whether steering engaged) but not the underlying match scores. Raw scores are deliberately kept off the caller-facing surface: exposing them would let a caller probe the exact boundary and map the detection and steering. Scores are retained only in the admin-gated safety audit, for operators tuning their own policies.

POST /v1/completions

Legacy (non-chat) OpenAI completion endpoint, kept for compatibility. New integrations should use /v1/chat/completions.

System

Governance: /admin/*

All /admin routes require an Operator or Admin key (an Observer key gets 403). See Authentication & roles.

Packs & policy

Pack authoring (1.1.0)

Author and refine a pack against real evidence instead of guessing at thresholds. These are the API behind the WebUI's pack editor.

A pack's transitions are typed — refuse, sever, format, ground — so a pack declares what should happen on a match, not just that it matched.

Model & calibration

Keys, license, config, runtime

Audit

There is also a set of low-level triple-store routes (/admin/triples/*) and an /admin/ui/* static-dashboard mount. The triple editor is a Admin-only advanced/legacy tool; native inference does not read those triples. Most operators drive PRIOR through packs (above) and the separate WebUI.

Authentication & roles

API keys are SHA-256-hashed at rest; the raw secret is shown once at creation and never stored or re-served. Present a key as Authorization: Bearer <key>. Keys may carry a label and an optional expiry.

• /v1 auth is off by default; a fresh engine answers inference without a key. Turn it on with PRIOR_REQUIRE_AUTH=1 or live via PATCH /admin/runtime. Always enable it before exposing the engine off loopback.
• /admin is always authenticated and requires Operator or Admin.
• Seed a first Admin key at boot with PRIOR_API_KEY (env-only, not persisted), then create scoped keys through /admin/keys.

Errors & status codes

Statelessness

The server holds no conversation sessions and no server-side user store. The client re-sends the full message history (and any ephemeral_memory) each turn. This is what makes horizontal scaling and air-gap deployment straightforward: any replica can serve any request.

CORS (browser clients)

To call the engine from a browser (e.g. the WebUI on a different origin), set PRIOR_ALLOWED_ORIGINS to your UI's origin(s). The engine lists Authorization + Content-Type explicitly in Access-Control-Allow-Headers (a * wildcard does not cover Authorization per the Fetch spec, so the Bearer key would otherwise be dropped). Restrict origins in production.

See also: Concepts · Policy & Packs · Deployment.