{
"openapi": "3.1.0",
"info": {
"title": "CalibratedAgents API",
"version": "1.0.0",
"description": "Check an AI answer against the passages it was based on: one calibrated score for the answer, and for every wrong claim, what is wrong, why, where in the source and the fix."
},
"servers": [
{
"url": "https://api.calibratedagents.com"
}
],
"security": [
{
"bearer": []
}
],
"paths": {
"/v1/ground/basic": {
"post": {
"operationId": "checkAnswer",
"summary": "Check one answer",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckRequest"
}
}
}
},
"responses": {
"200": {
"description": "Checked",
"headers": {
"X-RateLimit-Limit": {
"schema": {
"type": "integer"
},
"description": "Today's allowance, in tokens."
},
"X-RateLimit-Remaining": {
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"schema": {
"type": "string"
},
"description": "When the allowance renews (00:00 UTC)."
}
},
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/CheckResult"
},
{
"type": "object",
"properties": {
"usage": {
"type": "object",
"properties": {
"tokens": {
"type": "integer"
},
"remaining_today": {
"type": "integer"
},
"resets_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Missing, malformed, wrong or revoked key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The key is limited to your company's IP addresses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body over 1 MB, or an item over the plan's per-request token limit",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A required field is missing or empty, a value has the wrong type, or a batch has more than 50 items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Today's allowance is used up",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "The checking service couldn't run. Nothing was charged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "We couldn't verify the key right now",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/ground/basic/batch": {
"post": {
"operationId": "checkBatch",
"summary": "Check up to 50 answers",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"$ref": "#/components/schemas/CheckRequest"
}
},
"profile": {
"type": "string",
"enum": [
"precision",
"balanced"
],
"deprecated": true,
"description": "Accepted for compatibility; it no longer changes the result."
},
"metadata": {
"type": "object",
"description": "Labels: environment, session_id, tags (≤ 20) and ≤ 20 other keys; ≤ 2,000 characters in total.",
"properties": {
"environment": {
"type": "string"
},
"session_id": {
"type": "string"
},
"tags": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Results in the same order as items. Items that couldn't be checked are refunded.",
"headers": {
"X-RateLimit-Limit": {
"schema": {
"type": "integer"
},
"description": "Today's allowance, in tokens."
},
"X-RateLimit-Remaining": {
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"schema": {
"type": "string"
},
"description": "When the allowance renews (00:00 UTC)."
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckResult"
}
},
"count": {
"type": "integer"
},
"usage": {
"type": "object",
"properties": {
"tokens": {
"type": "integer"
},
"remaining_today": {
"type": "integer"
},
"resets_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
},
"401": {
"description": "Missing, malformed, wrong or revoked key",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The key is limited to your company's IP addresses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Body over 1 MB, or an item over the plan's per-request token limit",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A required field is missing or empty, a value has the wrong type, or a batch has more than 50 items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Today's allowance is used up",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "The checking service couldn't run. Nothing was charged.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "We couldn't verify the key right now",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/health": {
"get": {
"operationId": "health",
"summary": "Is checking available?",
"security": [],
"responses": {
"200": {
"description": "Up",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"checked_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"503": {
"description": "Checking is unavailable right now"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearer": {
"type": "http",
"scheme": "bearer",
"description": "Authorization: Bearer ca_live_… (create keys in the console)"
}
},
"schemas": {
"CheckRequest": {
"type": "object",
"required": [
"question",
"context",
"answer"
],
"properties": {
"question": {
"type": "string",
"minLength": 1,
"description": "What the user asked."
},
"context": {
"oneOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
],
"description": "The retrieved passages."
},
"answer": {
"type": "string",
"minLength": 1,
"description": "The model's answer to check."
},
"profile": {
"type": "string",
"enum": [
"precision",
"balanced"
],
"deprecated": true,
"description": "Accepted for compatibility; it no longer changes the result."
},
"metadata": {
"type": "object",
"description": "Labels: environment, session_id, tags (≤ 20) and ≤ 20 other keys; ≤ 2,000 characters in total.",
"properties": {
"environment": {
"type": "string"
},
"session_id": {
"type": "string"
},
"tags": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"Claim": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"span": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2,
"description": "[start, end] character offsets into answer, counted in Unicode code points."
},
"text": {
"type": "string",
"description": "The claim."
},
"type": {
"type": "string",
"enum": [
"fact",
"computation",
"comparison",
"inference",
"decision",
"opinion",
"refusal"
]
},
"status": {
"type": "string",
"enum": [
"contradicted",
"not_stated",
"depends_on_error",
"unverified_step",
"supported",
"not_checked"
],
"description": "What: contradicted, not_stated, depends_on_error (see rests_on), unverified_step (a reasoning step — checking it is the Pro tier), supported, not_checked (greetings and framing)."
},
"checks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Why: short, human-readable reasons. Empty when supported."
},
"evidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
}
}
},
"description": "Where: the source passages the claim was checked against. May be empty for not_stated — nothing in the source covers it."
},
"fix": {
"type": [
"string",
"null"
],
"description": "What next: one sentence saying what to change. null when there is nothing to fix."
},
"rests_on": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ids of earlier claims this one follows from."
}
}
},
"Sentence": {
"type": "object",
"properties": {
"index": {
"type": "integer"
},
"span": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 2,
"maxItems": 2,
"description": "[start, end] character offsets into answer, counted in Unicode code points."
},
"text": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"contradicted",
"not_stated",
"depends_on_error",
"unverified_step",
"supported",
"not_checked"
],
"description": "The worst status of its claims."
},
"claims": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Claim"
}
}
}
},
"CheckResult": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"unavailable"
],
"description": "unavailable = nothing was checked; treat the answer as unverified."
},
"id": {
"type": "string",
"description": "The check's id, for support."
},
"score": {
"type": "object",
"properties": {
"p_hallucinated": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "One calibrated score for the whole answer: higher = more likely to say something the source doesn't support. null if the model isn't loaded."
},
"model": {
"type": "string",
"description": "Model version, for support."
}
}
},
"sentences": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Sentence"
}
},
"corrections": {
"type": "array",
"items": {
"type": "string"
},
"description": "One line per claim to fix. Present only when something needs fixing."
},
"regeneration_hint": {
"type": "string",
"description": "A ready-made instruction to rewrite the answer. Present only when something needs fixing."
},
"meta": {
"type": "object",
"properties": {
"latency_ms": {
"type": "integer"
}
}
}
}
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"auth_unavailable",
"daily_quota_exceeded",
"invalid_api_key",
"invalid_request",
"ip_not_allowed",
"method_not_allowed",
"not_found",
"rate_limited",
"request_too_large",
"verification_unavailable"
]
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}