API reference

REST endpoints, authentication, errors and conventions for the Vera engine API.

All endpoints are served under your deployment's base URL, accept and return JSON, and require a bearer token.

Authorization: Bearer vera_sk_...
Content-Type: application/json

Keys are issued per integration from Settings → API keys and carry scoped permissions (read-only, evaluate, full reasoning). Mutating endpoints accept an Idempotency-Key header; retried requests with the same key return the original result.

POST /v1/reason

Run the full pipeline on a task described in natural language: extraction → memory recall → candidate generation → solver verification → ranked recommendation.

Request

{
  "task": "Truck 7 broke down on the E75. Reroute its afternoon deliveries.",
  "context": { "site": "helsinki-depot" },
  "mode": "suggest"
}

mode may be suggest, approve or autonomous and cannot exceed the autonomy ceiling configured for the decision class — requests above the ceiling are downgraded and flagged in the response.

Response — recommended action, all alternatives with per-rule verdicts, the facts used, and a trace_id resolvable in the Audit surface.

POST /v1/plans/evaluate

Check a specific candidate plan against all active rules. This is the pure solver surface — no LLM is involved.

Response (infeasible plan)

{
  "feasible": false,
  "results": [
    { "rule": "R2", "result": "violated" },
    { "rule": "R1", "result": "satisfied" }
  ],
  "unsat_core": {
    "rules": ["R2"],
    "facts": ["T-103.certifications", "WO-4811.equipment_class"],
    "explanation": "R2 requires a certified technician for gas-boiler work; T-103 holds no gas certification."
  }
}

The unsat_core is the minimal conflicting set as computed by Z3 — remove any element and the plan becomes satisfiable with respect to that core.

POST /v1/rules/parse

Translate a plain-English rule into its structured form without activating it. Use this to preview what the solver would enforce. Activation is a separate, explicit step (in the console, an operator confirmation).

GET /v1/rules

List active rules with their structured form, version history, author and timestamps.

GET /v1/audit/decisions and GET /v1/audit/decisions/{trace_id}

Query the decision log. Every decision record contains the task, the facts and rule versions used, every candidate evaluated with its verdict, the unsat cores of rejected candidates, the autonomy mode, and the approving user where applicable. Records are append-only.

GET /v1/memory/query

Semantic and structural queries over the knowledge graph — entities, relationships, and decision precedents.

Errors

Status	Meaning
400	Malformed request body
401 / 403	Missing key / insufficient scope
409	Conflict — e.g. rule activation against a stale version
422	Input parsed but failed schema validation — the response names the failing fields; nothing was executed
429	Rate limit exceeded; respect `Retry-After`

The deliberate one is 422: when the language layer cannot produce a schema-valid structure from your input, the API refuses rather than guesses. That refusal is the architecture working as designed.

← Architecture MCP server →