umpirix/public/openapi.json
caelum0x 4847e35451 OpenJev: open-source typed decision service
Typed decision/classification service with an in-process gte-small ONNX
embedding engine and lexical fallback, JS/Python SDKs, adapters, and the
otsone model family. Apache-2.0 (sub-packages keep their MIT licenses).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 00:12:36 +03:00

2080 lines
62 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"openapi": "3.1.0",
"info": {
"title": "OpenJev API",
"description": "Typed decisions — Choice, Score, and Noul — with calibrated confidence. One POST returns a typed answer per question over a shared state; no text generated.",
"version": "1",
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"contact": {
"name": "OpenJev",
"url": "https://github.com/caelum0x/opentypesafe"
}
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Self-hosted (Docker)"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Decisions",
"description": "Execute typed decisions over a shared state."
},
{
"name": "Status",
"description": "Backend health and model availability."
},
{
"name": "Keys",
"description": "API key management."
},
{
"name": "Usage",
"description": "Token and call usage statistics."
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "API key (ots_live_…) from /keys. Omit or send 'anon' for self-hosted anonymous use."
}
},
"schemas": {
"ChoiceQuestion": {
"type": "object",
"required": [
"type",
"instructions",
"criteria"
],
"description": "Classify the state into exactly one of the labelled options.",
"properties": {
"type": {
"type": "string",
"enum": [
"choice"
]
},
"instructions": {
"description": "The question. Backtick-wrap state keys to reference them, e.g. 'Intent of `ticket`?'."
},
"criteria": {
"type": "object",
"description": "Map of label key → description. Keys become the valid output labels (2–255 entries).",
"additionalProperties": {}
},
"abstain": {
"type": "boolean",
"description": "Opt into abstention: when the input is out of scope or confidence is below abstain_below, the answer comes back with abstained: true (choice answers pick the reserved __none__ option)."
},
"abstain_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence floor for abstention. Implies abstain: true."
},
"escalate_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "auto model only: escalate this question to the LLM when its local confidence is below this value."
}
}
},
"ScoreQuestion": {
"type": "object",
"required": [
"type",
"instructions",
"criteria"
],
"description": "Rate the state on an ordered scale of 2–10 rubric levels.",
"properties": {
"type": {
"type": "string",
"enum": [
"score"
]
},
"instructions": {
"description": "The rubric question."
},
"criteria": {
"type": "array",
"description": "Ordered array of level descriptions, from lowest to highest. The array index is the returned score value.",
"items": {},
"minItems": 2,
"maxItems": 10
},
"abstain": {
"type": "boolean",
"description": "Opt into abstention: when the input is out of scope or confidence is below abstain_below, the answer comes back with abstained: true (choice answers pick the reserved __none__ option)."
},
"abstain_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence floor for abstention. Implies abstain: true."
},
"escalate_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "auto model only: escalate this question to the LLM when its local confidence is below this value."
}
}
},
"NoulQuestion": {
"type": "object",
"required": [
"type",
"instructions"
],
"description": "Return a calibrated P(yes) for a single yes/no proposition.",
"properties": {
"type": {
"type": "string",
"enum": [
"noul"
]
},
"instructions": {
"description": "A yes/no proposition, e.g. 'Does `reply` leak PII?'"
},
"criteria": {
"type": "object",
"properties": {
"true": {
"description": "Description for the affirmative case."
},
"false": {
"description": "Description for the negative case."
}
}
},
"abstain": {
"type": "boolean",
"description": "Opt into abstention: when the input is out of scope or confidence is below abstain_below, the answer comes back with abstained: true (choice answers pick the reserved __none__ option)."
},
"abstain_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Confidence floor for abstention. Implies abstain: true."
},
"escalate_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "auto model only: escalate this question to the LLM when its local confidence is below this value."
}
}
},
"Question": {
"oneOf": [
{
"$ref": "#/components/schemas/ChoiceQuestion"
},
{
"$ref": "#/components/schemas/ScoreQuestion"
},
{
"$ref": "#/components/schemas/NoulQuestion"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"choice": "#/components/schemas/ChoiceQuestion",
"score": "#/components/schemas/ScoreQuestion",
"noul": "#/components/schemas/NoulQuestion"
}
}
},
"ChoiceAnswer": {
"type": "object",
"required": [
"type",
"choice",
"probabilities",
"confidence"
],
"properties": {
"type": {
"type": "string",
"enum": [
"choice"
]
},
"choice": {
"type": "string",
"description": "The winning label key."
},
"probabilities": {
"type": "object",
"description": "Full distribution: every option key → probability. Sums to 1.",
"additionalProperties": {
"type": "number"
}
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Calibrated confidence for the winning label. Gate actions on this value."
},
"ood": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Out-of-scope score (distance of the state from the question vocabulary, modulated by answer entropy). >= 0.6 means out of scope."
},
"abstained": {
"type": "boolean",
"description": "Present and true when the model said 'I don't know' (abstention opted in)."
},
"abstain_reason": {
"type": "string",
"enum": [
"out_of_scope",
"low_confidence"
]
},
"p_none": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Probability mass on 'none of the above / I don't know'."
},
"calibrated": {
"type": "boolean",
"description": "True when a customer calibration map rewrote this answer's confidence."
},
"escalated": {
"type": "boolean",
"description": "True when the auto model re-asked this question to an LLM."
}
}
},
"ScoreAnswer": {
"type": "object",
"required": [
"type",
"score",
"probabilities",
"confidence"
],
"properties": {
"type": {
"type": "string",
"enum": [
"score"
]
},
"score": {
"type": "number",
"description": "The winning level index (matches the position in the criteria array)."
},
"legend": {
"type": "object",
"description": "Map of level index → description, for display.",
"additionalProperties": {}
},
"probabilities": {
"type": "object",
"description": "Full distribution over levels.",
"additionalProperties": {
"type": "number"
}
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ood": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Out-of-scope score (distance of the state from the question vocabulary, modulated by answer entropy). >= 0.6 means out of scope."
},
"abstained": {
"type": "boolean",
"description": "Present and true when the model said 'I don't know' (abstention opted in)."
},
"abstain_reason": {
"type": "string",
"enum": [
"out_of_scope",
"low_confidence"
]
},
"p_none": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Probability mass on 'none of the above / I don't know'."
},
"calibrated": {
"type": "boolean",
"description": "True when a customer calibration map rewrote this answer's confidence."
},
"escalated": {
"type": "boolean",
"description": "True when the auto model re-asked this question to an LLM."
}
}
},
"NoulAnswer": {
"type": "object",
"required": [
"type",
"noul"
],
"properties": {
"type": {
"type": "string",
"enum": [
"noul"
]
},
"noul": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Calibrated P(yes). Gate at your chosen threshold, e.g. > 0.7 for high-confidence yes."
},
"ood": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Out-of-scope score (distance of the state from the question vocabulary, modulated by answer entropy). >= 0.6 means out of scope."
},
"abstained": {
"type": "boolean",
"description": "Present and true when the model said 'I don't know' (abstention opted in)."
},
"abstain_reason": {
"type": "string",
"enum": [
"out_of_scope",
"low_confidence"
]
},
"p_none": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Probability mass on 'none of the above / I don't know'."
},
"calibrated": {
"type": "boolean",
"description": "True when a customer calibration map rewrote this answer's confidence."
},
"escalated": {
"type": "boolean",
"description": "True when the auto model re-asked this question to an LLM."
}
}
},
"Answer": {
"oneOf": [
{
"$ref": "#/components/schemas/ChoiceAnswer"
},
{
"$ref": "#/components/schemas/ScoreAnswer"
},
{
"$ref": "#/components/schemas/NoulAnswer"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"choice": "#/components/schemas/ChoiceAnswer",
"score": "#/components/schemas/ScoreAnswer",
"noul": "#/components/schemas/NoulAnswer"
}
}
},
"SystemOneRequest": {
"type": "object",
"required": [
"state",
"questions"
],
"properties": {
"model": {
"type": "string",
"description": "Model id. Defaults to system-one (the always-on local engine). See GET /api/v1/status for which models are available on this deployment. `auto` is the cascade: local first, LLM only for low-confidence or out-of-scope questions.",
"enum": [
"auto",
"system-one",
"jev-sharp",
"jev-decisive",
"jev-contrastive",
"laya-mlx",
"laya-onnx",
"openjev-grok",
"system-one-cloud",
"otsone-1",
"otsone-mini"
],
"default": "system-one"
},
"state": {
"description": "The shared context for every question in this request. Can be a plain string, a structured object, or an array.",
"oneOf": [
{
"type": "string"
},
{
"type": "object"
},
{
"type": "array",
"items": {}
}
]
},
"questions": {
"type": "object",
"description": "Map of answer key → typed question. Each key becomes a matching key in the returned `answers` object.",
"additionalProperties": {
"$ref": "#/components/schemas/Question"
},
"minProperties": 1
},
"abstain": {
"type": "boolean",
"description": "Request-wide abstention default."
},
"abstain_below": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"escalate_below": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "auto model: request-wide escalation threshold (default 0.6 or OTS_AUTO_ESCALATE_BELOW)."
},
"calibration_id": {
"type": "string",
"pattern": "^cal_[a-z0-9]{4,40}$",
"description": "Apply a calibration fitted on your labels (POST /api/v1/calibrations). Requires an authenticated caller."
}
}
},
"SystemOneResponse": {
"type": "object",
"required": [
"model",
"answers",
"usage",
"latency_ms"
],
"properties": {
"model": {
"type": "string",
"description": "The model id that produced this response."
},
"answers": {
"type": "object",
"description": "Map of answer key → typed answer. Keys match the `questions` map in the request.",
"additionalProperties": {
"$ref": "#/components/schemas/Answer"
}
},
"usage": {
"type": "object",
"required": [
"input_tokens",
"output_tokens"
],
"properties": {
"input_tokens": {
"type": "integer",
"description": "Tokens consumed reading state and questions."
},
"output_tokens": {
"type": "integer",
"description": "Tokens generated (near-zero for local backends)."
}
}
},
"latency_ms": {
"type": "number",
"description": "End-to-end decision latency in milliseconds."
},
"fallback": {
"type": "object",
"description": "Present when the requested backend was unavailable and the local engine answered instead.",
"properties": {
"requested": {
"type": "string",
"description": "The model id the caller asked for."
},
"served": {
"type": "string",
"description": "The model id that actually produced the answer."
},
"reason": {
"type": "string",
"description": "Stable machine-readable reason, e.g. laya_sidecar_unavailable."
},
"detail": {
"type": "string",
"description": "Human-readable explanation."
}
}
},
"escalation": {
"type": "object",
"description": "auto model only: which questions escalated to the LLM and why.",
"properties": {
"local_model": {
"type": "string"
},
"escalated": {
"type": "array",
"items": {
"type": "string"
}
},
"kept": {
"type": "array",
"items": {
"type": "string"
}
},
"needed": {
"type": "array",
"items": {
"type": "string"
}
},
"threshold": {
"type": "number"
},
"provider": {
"type": [
"string",
"null"
]
},
"llm_model": {
"type": [
"string",
"null"
]
},
"skipped_reason": {
"type": "string",
"enum": [
"no_llm_configured",
"rate_limited",
"llm_error"
]
}
}
},
"calibration": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"temperature",
"isotonic"
]
},
"questions": {
"type": "array",
"items": {
"type": "string"
}
},
"skipped_reason": {
"type": "string"
}
}
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request",
"rate_limit",
"internal",
"unauthorized",
"not_found",
"plan_required",
"report_signing_not_configured",
"invalid_calibration_id",
"invalid_json",
"payload_too_large"
],
"description": "Stable error type for programmatic handling."
},
"message": {
"type": "string",
"description": "Human-readable error description."
},
"used": {
"type": "integer",
"description": "Calls used in the current window (rate_limit only)."
},
"limit": {
"type": "integer",
"description": "Limit for this window (rate_limit only)."
},
"reset_at": {
"type": "string",
"format": "date-time",
"description": "When the window resets (rate_limit only)."
}
}
}
}
},
"AuditReport": {
"type": "object",
"description": "Signed calibration audit report. The signature is HMAC-SHA256 over the canonical JSON of every other field (keys sorted, no whitespace).",
"required": [
"schema",
"report_id",
"issued_at",
"calibration",
"questions",
"skipped",
"drift",
"shadow",
"limitations",
"signature"
],
"properties": {
"schema": {
"type": "string",
"const": "openjev.audit-report/v1"
},
"report_id": {
"type": "string",
"pattern": "^rep_[0-9a-f]{20}$"
},
"issued_at": {
"type": "string",
"format": "date-time"
},
"issuer": {
"type": [
"string",
"null"
],
"description": "Public origin of the issuing server, when configured."
},
"calibration": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"model": {
"type": "string"
},
"method": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"upload",
"eval_run"
]
},
"eval_run_id": {
"type": [
"string",
"null"
]
},
"labels": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"map": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"temperature",
"isotonic"
]
},
"temperature": {
"type": "number"
},
"knots": {
"type": "integer"
}
}
},
"evaluation": {
"type": "string",
"enum": [
"held_out",
"in_sample",
"unknown"
]
},
"labels": {
"type": "integer"
},
"train_labels": {
"type": [
"integer",
"null"
]
},
"heldout_labels": {
"type": [
"integer",
"null"
]
},
"raw": {
"$ref": "#/components/schemas/AuditStats"
},
"calibrated": {
"$ref": "#/components/schemas/AuditStats"
},
"ece_change": {
"type": "number"
},
"brier_change": {
"type": "number"
},
"threshold": {
"type": "object",
"properties": {
"target_precision": {
"type": "number"
},
"recommended": {
"type": [
"object",
"null"
],
"properties": {
"threshold": {
"type": "number"
},
"precision": {
"type": [
"number",
"null"
]
},
"coverage": {
"type": "number"
}
}
}
}
}
}
}
},
"skipped": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question_id": {
"type": "string"
},
"reason": {
"type": "string"
}
}
}
},
"drift": {
"type": "object",
"properties": {
"monitor": {
"type": [
"object",
"null"
]
},
"checks": {
"type": "integer"
},
"drift_events": {
"type": "integer"
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"checked_at": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"ok",
"drift",
"insufficient"
]
},
"drifted": {
"type": "array",
"items": {
"type": "string"
}
},
"observations": {
"type": "integer"
},
"alerted": {
"type": "boolean"
}
}
}
}
}
},
"shadow": {
"type": [
"object",
"null"
],
"properties": {
"window_days": {
"type": "integer"
},
"pairs": {
"type": "integer"
},
"agreement": {
"type": [
"number",
"null"
]
},
"label_pairs": {
"type": "integer"
},
"label_agreement": {
"type": [
"number",
"null"
]
}
}
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
},
"signature": {
"type": "object",
"required": [
"alg",
"key_id",
"value"
],
"properties": {
"alg": {
"type": "string",
"const": "HMAC-SHA256"
},
"key_id": {
"type": "string"
},
"value": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
}
}
}
},
"AuditStats": {
"type": "object",
"properties": {
"accuracy": {
"type": "number"
},
"ece": {
"type": "number"
},
"brier": {
"type": "number"
},
"avg_confidence": {
"type": "number"
}
}
}
}
},
"paths": {
"/api/v1/systemone": {
"post": {
"operationId": "createSystemOne",
"tags": [
"Decisions"
],
"summary": "Execute typed decisions",
"description": "Submit a shared state and one or more typed questions. Returns a calibrated typed answer per question — Choice (label + full distribution), Score (level + distribution), or Noul (calibrated P(yes)). Multiple questions share one state read, so a 13-item checklist is one call.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SystemOneRequest"
},
"example": {
"state": {
"ticket": "My card was charged twice last Friday."
},
"questions": {
"category": {
"type": "choice",
"instructions": "Main request in `ticket`?",
"criteria": {
"refund": "Wants money returned.",
"rebooking": "Wants a replacement flight.",
"info": "Asking for information only."
}
},
"severity": {
"type": "score",
"instructions": "Urgency of `ticket` (0 = low, 5 = critical)?",
"criteria": [
"Cosmetic or negligible impact",
"Low — can wait",
"Moderate — within SLA",
"High — same-day response",
"Critical — immediate action",
"Existential — all hands"
]
},
"is_angry": {
"type": "noul",
"instructions": "Does `ticket` express anger or strong frustration?"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Decision executed successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SystemOneResponse"
},
"example": {
"model": "system-one",
"answers": {
"category": {
"type": "choice",
"choice": "refund",
"probabilities": {
"refund": 0.87,
"rebooking": 0.09,
"info": 0.04
},
"confidence": 0.87
},
"severity": {
"type": "score",
"score": 3,
"legend": {
"3": "High — same-day response"
},
"probabilities": {
"0": 0.02,
"1": 0.04,
"2": 0.1,
"3": 0.61,
"4": 0.18,
"5": 0.05
},
"confidence": 0.61
},
"is_angry": {
"type": "noul",
"noul": 0.31
}
},
"usage": {
"input_tokens": 74,
"output_tokens": 0
},
"latency_ms": 4.2
}
}
}
},
"400": {
"description": "Invalid request (missing fields, bad question shape, unknown model).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Allowance exceeded for this key (Railyard integration).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit or monthly quota exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"get": {
"operationId": "getSystemOneInfo",
"tags": [
"Decisions"
],
"summary": "API info",
"description": "Returns the API name, available model ids, supported primitives, and the wire-compatibility string. No auth required.",
"security": [],
"responses": {
"200": {
"description": "API info.",
"content": {
"application/json": {
"example": {
"name": "openjev",
"models": [
"system-one",
"jev-sharp",
"jev-decisive",
"jev-contrastive",
"laya-mlx",
"laya-onnx",
"openjev-grok",
"system-one-cloud"
],
"primitives": [
"choice",
"score",
"noul"
],
"endpoint": "POST /api/v1/systemone",
"compatible": "OpenJev System One v1"
}
}
}
}
}
}
},
"/api/v1/batch": {
"post": {
"operationId": "batchSystemOne",
"tags": [
"Decisions"
],
"summary": "Batch decisions",
"description": "Execute multiple independent System One requests in a single HTTP call. Requests in the batch are evaluated in parallel; the response array preserves input order.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"requests"
],
"properties": {
"requests": {
"type": "array",
"description": "System One requests to execute in parallel.",
"items": {
"$ref": "#/components/schemas/SystemOneRequest"
},
"minItems": 1,
"maxItems": 100
}
}
},
"example": {
"requests": [
{
"state": "This product is fantastic, arrived in two days.",
"questions": {
"sentiment": {
"type": "score",
"instructions": "Sentiment (1 negative … 5 positive)?",
"criteria": [
"Very negative",
"Negative",
"Neutral",
"Positive",
"Very positive"
]
}
}
},
{
"state": "Order still hasn't arrived after three weeks.",
"questions": {
"sentiment": {
"type": "score",
"instructions": "Sentiment (1 negative … 5 positive)?",
"criteria": [
"Very negative",
"Negative",
"Neutral",
"Positive",
"Very positive"
]
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "All decisions resolved.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SystemOneResponse"
}
}
}
}
}
}
}
}
}
},
"/api/v1/validate": {
"post": {
"operationId": "validateRequest",
"tags": [
"Decisions"
],
"summary": "Validate a request payload",
"description": "Dry-run validation for a System One payload. Returns any schema errors without executing a decision — useful for catching malformed questions before sending to production.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SystemOneRequest"
}
}
}
},
"responses": {
"200": {
"description": "Validation result.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"valid"
],
"properties": {
"valid": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable validation errors. Empty when valid is true."
}
}
},
"example": {
"valid": true,
"errors": []
}
}
}
}
}
}
},
"/api/v1/calibration": {
"post": {
"operationId": "runCalibration",
"tags": [
"Decisions"
],
"summary": "Calibration metrics",
"description": "Evaluate calibration quality (ECE, Brier score) over a labelled example set. Measures how well the model's confidence tracks observed accuracy on your data, so you can pick operating thresholds with confidence.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"examples"
],
"properties": {
"model": {
"type": "string",
"description": "Model to evaluate. Defaults to system-one.",
"default": "system-one"
},
"examples": {
"type": "array",
"description": "Labelled examples: each has the System One request and the expected answer per key.",
"items": {
"type": "object",
"required": [
"request",
"gold"
],
"properties": {
"request": {
"$ref": "#/components/schemas/SystemOneRequest"
},
"gold": {
"type": "object",
"description": "Map of answer key → expected label / level / boolean.",
"additionalProperties": {}
}
}
},
"minItems": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Calibration metrics.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"model": {
"type": "string"
},
"n": {
"type": "integer",
"description": "Number of examples evaluated."
},
"accuracy": {
"type": "number",
"description": "Fraction of top answers that matched gold."
},
"ece": {
"type": "number",
"description": "Expected calibration error (lower is better; 0 = perfectly calibrated)."
},
"brier": {
"type": "number",
"description": "Mean Brier score over all questions (lower is better)."
}
}
},
"example": {
"model": "system-one",
"n": 500,
"accuracy": 0.891,
"ece": 0.043,
"brier": 0.118
}
}
}
}
}
}
},
"/api/v1/status": {
"get": {
"operationId": "getStatus",
"tags": [
"Status"
],
"summary": "Backend health",
"description": "Returns health for every backend on this deployment — local (always available), native sidecar, neural (Laya MLX/ONNX), any-LLM, and OpenJev cloud — plus a per-model availability array. Not cached.",
"security": [],
"responses": {
"200": {
"description": "Backend status.",
"content": {
"application/json": {
"example": {
"object": "backend_status",
"local": {
"available": true
},
"native": {
"available": false,
"url": "http://localhost:8765",
"engine": null
},
"laya": {
"available": false,
"backend": "onnx",
"url": "http://localhost:8766",
"engine": null
},
"llm": {
"available": false
},
"cloud": {
"available": false
},
"models": [
{
"id": "system-one",
"backend": "local",
"available": true
},
{
"id": "laya-onnx",
"backend": "laya",
"available": false,
"reason": "laya_sidecar_unreachable",
"install": "Start the neural sidecar (Laya). See SELF-HOSTING.md."
}
]
}
}
}
}
}
}
},
"/api/v1/": {
"get": {
"operationId": "getHealth",
"tags": [
"Status"
],
"summary": "Liveness / API info",
"description": "Lightweight liveness check. Returns API name, version, wire-compatibility info, active engine info, and the endpoint list.",
"security": [],
"responses": {
"200": {
"description": "API is live.",
"content": {
"application/json": {
"example": {
"name": "openjev",
"version": "0.2",
"compatible": "http://localhost:3000/api/v1/systemone",
"engine": {
"backend": "typescript-fallback"
},
"models": [
{
"id": "system-one",
"label": "System One"
}
],
"endpoints": [
"POST /api/v1/systemone",
"GET /api/v1/models",
"GET /api/v1/status"
]
}
}
}
}
}
}
},
"/api/v1/keys": {
"get": {
"operationId": "listKeys",
"tags": [
"Keys"
],
"summary": "List API keys",
"description": "Returns all API keys for the authenticated account. Full key values are never returned; only prefix and metadata.",
"responses": {
"200": {
"description": "Keys returned.",
"content": {
"application/json": {
"example": {
"keys": [
{
"id": "key_01hx",
"name": "Production",
"prefix": "ots_live_",
"created_at": "2026-09-01T00:00:00Z",
"last_used_at": "2026-09-23T08:12:00Z"
}
]
}
}
}
}
}
},
"post": {
"operationId": "createKey",
"tags": [
"Keys"
],
"summary": "Create API key",
"description": "Creates a new API key. The full key value (ots_live_…) is returned exactly once — store it securely. It cannot be retrieved again.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Human-readable label for this key."
}
}
},
"example": {
"name": "Production"
}
}
}
},
"responses": {
"200": {
"description": "Key created.",
"content": {
"application/json": {
"example": {
"id": "key_01hx",
"name": "Production",
"key": "ots_live_xxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-09-23T09:00:00Z"
}
}
}
}
}
}
},
"/api/v1/usage": {
"get": {
"operationId": "getUsage",
"tags": [
"Usage"
],
"summary": "Usage statistics",
"description": "Returns token and call counts for the authenticated key, broken down by model and period.",
"parameters": [
{
"name": "period",
"in": "query",
"description": "Aggregation period.",
"schema": {
"type": "string",
"enum": [
"day",
"week",
"month"
],
"default": "month"
}
}
],
"responses": {
"200": {
"description": "Usage data.",
"content": {
"application/json": {
"example": {
"period": "month",
"total_calls": 14820,
"total_input_tokens": 1092400,
"total_output_tokens": 420,
"by_model": [
{
"model": "system-one",
"calls": 14100,
"input_tokens": 1039800
},
{
"model": "openjev-grok",
"calls": 720,
"input_tokens": 52600
}
]
}
}
}
}
}
}
},
"/api/v1/calibrations": {
"get": {
"operationId": "listCalibrations",
"tags": [
"Decisions"
],
"summary": "List calibrations, or get one with ?id=cal_...",
"parameters": [
{
"name": "id",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Calibration list or detail"
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"post": {
"operationId": "createCalibration",
"tags": [
"Decisions"
],
"summary": "Fit a per-question calibration from your labelled examples",
"description": "Each example is answered by `model` and graded against its labels; a temperature or isotonic map is fitted per question (10+ labels each; a pooled map covers the rest). Or pass eval_run_id to fit from an eval run. Apply with calibration_id on /api/v1/systemone.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"model": {
"type": "string",
"default": "system-one"
},
"method": {
"type": "string",
"enum": [
"auto",
"temperature",
"isotonic"
]
},
"target_precision": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.95
},
"questions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Question"
}
},
"examples": {
"type": "array",
"maxItems": 2000,
"items": {
"type": "object",
"required": [
"state",
"labels"
],
"properties": {
"state": {},
"labels": {
"type": "object",
"description": "question id -> label: option key (choice), level index (score), boolean (noul)"
}
}
}
},
"eval_run_id": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "The fitted calibration with maps, before/after ECE and Brier, threshold curve and recommended threshold"
},
"400": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"operationId": "deleteCalibration",
"tags": [
"Decisions"
],
"summary": "Delete a calibration (?id=cal_...)",
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Deleted"
},
"404": {
"description": "Not found"
}
}
}
},
"/api/v1/shadow": {
"post": {
"operationId": "runShadow",
"tags": [
"Decisions"
],
"summary": "Shadow your current LLM: answer the same questions and log agreement",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"state",
"questions"
],
"properties": {
"model": {
"type": "string",
"default": "system-one"
},
"state": {},
"questions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Question"
}
},
"calibration_id": {
"type": "string"
},
"incumbent": {
"type": "object",
"description": "Your production LLM's answers. Omit `answers` to have this server ask its configured LLM chain instead.",
"properties": {
"name": {
"type": "string"
},
"answers": {
"type": "object"
},
"latency_ms": {
"type": "integer"
},
"usage": {
"type": "object",
"properties": {
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Our answers, the incumbent's, and per-question agreement"
},
"400": {
"description": "Invalid input or no incumbent available",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"get": {
"operationId": "shadowSummary",
"tags": [
"Usage"
],
"summary": "Shadow dashboard: agreement overall, per question, per confidence band, and projected savings",
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"default": 30
}
},
{
"name": "threshold",
"in": "query",
"schema": {
"type": "number",
"default": 0.8
}
},
{
"name": "incumbent",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Shadow summary"
}
}
}
},
"/api/v1/reports/{calibrationId}": {
"get": {
"operationId": "getAuditReport",
"tags": [
"Decisions"
],
"summary": "Signed calibration audit report (HTML or JSON)",
"description": "Bundles the per-question calibration map, raw vs calibrated accuracy / ECE / Brier, the recommended threshold, drift monitor and check history, 30-day shadow agreement and the report's limitations, signed with HMAC-SHA256. Team plan on the hosted service; included when self-hosted. Requires OPENJEV_REPORT_SIGNING_SECRET or BETTER_AUTH_SECRET on the server.",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "calibrationId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^cal_[a-z0-9]{4,64}$"
}
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string",
"enum": [
"json",
"html"
],
"default": "json"
}
},
{
"name": "download",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1"
]
},
"description": "Send Content-Disposition: attachment."
}
],
"responses": {
"200": {
"description": "The signed report",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditReport"
}
},
"text/html": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Invalid id or format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"402": {
"description": "Plan does not include audit reports (plan_required)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Calibration not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "Report signing is not configured on this server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/reports/verify": {
"post": {
"operationId": "verifyAuditReport",
"tags": [
"Decisions"
],
"summary": "Verify a signed audit report",
"description": "Send the report JSON exactly as downloaded. Returns whether this server issued it and it is unmodified. No authentication required.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditReport"
}
}
}
},
"responses": {
"200": {
"description": "Verification result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"properties": {
"valid": {
"const": true
},
"report_id": {
"type": "string"
},
"calibration_id": {
"type": "string"
},
"issued_at": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"properties": {
"valid": {
"const": false
},
"reason": {
"type": "string",
"enum": [
"malformed",
"unknown_key",
"bad_signature"
]
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "Body is not JSON or too large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "Report signing is not configured on this server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
}
}