Hosted API

ClearRun API

ClearRun scores honesty and consistency: whether the confidence in an AI answer is earned by the reasoning that answer gives. The result is a 0 to 100 score, a grade, a risk label, and named failure categories. It is not a fact-checker. A high score is not a claim that the answer is true.

What the score measures, and what it does not, is spelled out on the methodology page.

Base URL

https://api.clearrun.net

Authentication

Scoring routes require an API key. Send it as Authorization: Bearer <apiKey>. The x-api-key header is also accepted.

Keys are a Pro, Business, or Enterprise feature. Sign in and create one at /account/keys. The full key is shown once. Keys start with crun_. A free account that presents a key receives 403 with code: "API_ACCESS_REQUIRED".

A missing credential returns 401 and { "error": "Missing Authorization: Bearer <apiKey>" }. An unrecognized key returns 401 and { "error": "Unauthorized" }.

The signed-in browser app can call the same routes without a key, but only from this origin. Any other client must send a key. GET /api/verify/{verdictId} and GET /.well-known/jwks.json are public.

Verdict and receipt

verdict on the wire uses this shape. scoringVersion is an opaque tag. The method that produces the score is not part of the API.

{
  "verdictId": "string",
  "schemaVersion": "1.0.0",
  "scoringVersion": "string",
  "score": 0,
  "grade": "Verify before use",
  "risk": "moderate",
  "failureCategories": ["overconfidence"],
  "confidenceInterval": { "min": 0, "max": 0 },
  "summary": "string",
  "componentSignals": [{ "name": "string", "level": 0, "note": "string" }],
  "issues": ["string"],
  "timestamp": "ISO-8601",
  "signature": "string",
  "signatureKeyId": "string",
  "signatureAlg": "ed25519"
}

• score is an integer from 0 to 100, or null when no score is configured. It reflects justification, not truth.
• grade is one of: Well supported, Generally reliable, Verify before use, High risk, Likely misleading, Not configured.
• risk is one of: low, moderate, elevated, high.
• failureCategories names are: overconfidence, unjustified_assertion, internal_inconsistency, ambiguity_suppression, confidence_domain_mismatch, unilateral_assertion, scope_drift, fabrication_risk.
• componentSignals is optional. level is a display bar from 0 to 6.

A hosted call also returns a receipt:

{
  "receiptId": "string",
  "verdictId": "string",
  "workspaceId": "string",
  "inputHash": "string",
  "outputHash": "string",
  "verdictHash": "string",
  "timestamp": "ISO-8601",
  "keyId": "string",
  "alg": "Ed25519",
  "prevHash": "string",
  "receiptHash": "string",
  "signature": "string",
  "encKeyId": "string",
  "status": "stored"
}

status may be omitted, stored, or queued. Optional workspaceId on a scoring call must be a workspace on the caller's account. If you omit it, the receipt is attached to the account's oldest workspace, or to account:<accountId> when the account has none. A workspace that is not on the account returns 403 with code: "WORKSPACE_FORBIDDEN".

POST /api/evaluate

Score text you already have. This is the endpoint to use from a script. The response must be at least 10 characters and at most 100,000.

curl -s https://api.clearrun.net/api/evaluate \
  -H "Authorization: Bearer $CLEARRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "responseText": "Paris is the capital of France. I am certain of this.",
    "prompt": "What is the capital of France?",
    "modelId": "openai/gpt-4o-mini"
  }'

Request fields:

• responseText (string, required). Alias: content.
• prompt (string, optional). The prompt that produced the answer, when you have it. Alias: originalPrompt.
• modelId (string, optional). Alias: sourceModel.
• workspaceId (string, optional).
• sourceProvider (string, optional). Stored with the evaluation record.

sessionId is accepted and ignored. enableFactCheck: true does not check facts. The response then includes factLayer: { "status": "not_enabled_yet" }. Otherwise factLayer is null.

{
  "verdict": { },
  "receipt": { },
  "creditsConsumed": 3,
  "creditsRemaining": 97,
  "factLayer": null
}

Credit cost is 2 credits plus 1 credit for each started block of about 4,000 characters, so a call costs at least 3, plus any credits the scoring step itself reports. creditsRemaining is -1 for an enterprise account with unlimited credits.

POST /api/score

Score text you already have, without a prompt. Same credit price as evaluate for the same text length, with no extra scoring-step credits. Same rate-limit bucket as evaluate.

{
  "responseText": "string, required",
  "modelId": "string, optional",
  "workspaceId": "string, optional"
}

{
  "verdict": { },
  "receipt": { },
  "creditsConsumed": 3,
  "creditsRemaining": 97
}

POST /api/chat

Ask an OpenAI model, then score that answer. Chat does not run other vendors. message is required and must be a string of at most 32,000 characters. Optional fields: modelId, sessionId, workspaceId. A model id that chat cannot run returns 400 and { "error": "Model unavailable" }.

The account must hold at least 26 credits before the turn starts, unless it is enterprise and unlimited. The body reports what was actually charged in creditsConsumed. responseText and response are the same model text.

{
  "sessionId": "string",
  "messageId": "string",
  "executionId": "string",
  "responseText": "string",
  "response": "string",
  "verdict": { },
  "receipt": { },
  "creditsConsumed": 1,
  "creditsRemaining": 99,
  "model": {
    "requested": "string",
    "resolved": "openai/gpt-4o-mini",
    "displayName": "string",
    "vendorName": "string",
    "substituted": false
  }
}

GET /api/verify/{verdictId}

No API key. Confirms the signature and whether this receipt sits on an intact workspace chain.

curl -s https://api.clearrun.net/api/verify/VERDICT_ID

{
  "verified": true,
  "signatureValid": true,
  "chainIntact": true,
  "receipt": { },
  "verdict": { }
}

verified is true only when the signature is valid, the payload matches, and the chain is intact. An unknown id returns 404 and { "error": "verdict not found" }.

GET /api/verify/chain

Requires a key (or a same-origin session) and a Pro plan or higher. Query: workspaceId, required. The workspace must belong to the caller. An account-scoped id looks like account:<accountId>.

{
  "workspaceId": "string",
  "intact": true,
  "length": 1,
  "head": "string or null",
  "links": [
    {
      "verdictId": "string",
      "receiptId": "string",
      "signatureValid": true,
      "payloadIntact": true,
      "linkIntact": true
    }
  ]
}

GET /api/audit/export

Requires a key and workspaceId for a workspace row on the caller's account (an account: id is not exportable). The workspace audit level must allow a summary export, or the route returns 403 with code: "AUDIT_LEVEL".

{
  "bundleVersion": 1,
  "generatedAt": "ISO-8601",
  "workspaceId": "string",
  "auditLevel": "summary",
  "genesis": "string",
  "chainHead": "string or null",
  "chainIntact": true,
  "jwks": { "keys": [] },
  "receipts": [
    { "receipt": { }, "publicVerdict": { } }
  ]
}

A full audit level can also include input and output text on each receipt. A summary export does not.

GET /.well-known/jwks.json

Public Ed25519 keys used to check receipt signatures. Cached for 5 minutes. If signing keys are not configured, the route returns 503 and { "error": "Signing keys are not configured" }.

GET /api/models

Lists OpenAI models that chat can run. No API key. A signed-in session selects the plan lane. Without a session the list is the self-serve lane. ?grouped=true groups by vendor. ?vendors=true lists vendors and marks the ones chat cannot run. The body includes note: chat runs OpenAI models, and other vendors are not available.

Rate limits

Limits follow the account plan. Evaluate and score share one counter. Chat has its own. Chain verification, audit export, model listing, and public verification are not on these counters.

• Pro: 30 requests per minute, 300 per hour, 2,000 per day.
• Business: 100 per minute, 1,000 per hour, 10,000 per day.
• Enterprise: 500 per minute, 5,000 per hour, no daily cap.

Over the limit, the route returns 429, a Retry-After header in seconds, and { "error": "Rate limit exceeded", "retryAfter": 60 }. Chat also includes remaining counts for the minute, hour, and day.

Errors

• 400 validation. Examples: responseText is required, RESPONSE_TEXT_REQUIRED, CONTENT_TOO_LONG, MESSAGE_TOO_LONG, Message required, ACTION_NOT_ALLOWED, or Content blocked.
• 401 missing or rejected key.
• 402 { "error": "Insufficient credits", "creditsNeeded": 3, "currentBalance": 0 }. Chat uses the same error and also includes a message.
• 403 API_ACCESS_REQUIRED, WORKSPACE_FORBIDDEN, or AUDIT_LEVEL.
• 404 no account, unknown verdict, or unknown workspace.
• 429 rate limit.
• 500 { "error": "Verdict was not signed", "code": "UNSIGNED_VERDICT" }, or { "error": "string" } with the message truncated.
• 503 PERSIST_FAILED when a receipt cannot be stored.

Open packages

These clients call this API. They do not include the scoring method.

• @clearrun/sdk
• @clearrun/cli
• @clearrun/mcp
• github.com/Adepoco/ClearRun

ClearRun is a product of Adepoco, a California corporation. Questions: contact@adepoco.com.