QEAR API documentation.

Quickstart

QEAR is a single HTTPS endpoint. You send a question and (for verification) the candidate answer; QEAR returns a confidence score plus a diagnosis of the kind of uncertainty involved.

1. Get an API key

Sign up at app.qear.ai/signup with your email. After clicking the magic link, you can generate your first API key on the dashboard. The key is shown once — save it in a password manager.

2. Make your first call

Use the /v1/verify endpoint to check whether an answer is trustworthy. Replace qe_YOUR_KEY with the key you just generated.

curl https://api.qear.ai/v1/verify \
  -H "Authorization: Bearer qe_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What year did Napoleon die?",
    "answer": "1821"
  }'

import requests

response = requests.post(
    "https://api.qear.ai/v1/verify",
    headers={"Authorization": "Bearer qe_YOUR_KEY"},
    json={
        "prompt": "What year did Napoleon die?",
        "answer": "1821",
    },
)

result = response.json()
print(result["verdict"], result["confidence"])
print(result["diagnosis"])

const response = await fetch(
  "https://api.qear.ai/v1/verify",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer qe_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "What year did Napoleon die?",
      answer: "1821",
    }),
  }
);

const result = await response.json();
console.log(result.verdict, result.confidence);
console.log(result.diagnosis);

3. Read the response

A typical successful response looks like this:

{
  "confidence": 0.92,
  "verdict": "high_confidence",
  "uncertainty_class": "none",
  "diagnosis": "All 5 valid candidates agreed semantically. High confidence in the consensus answer.",
  "recommended_action": "Trust the answer.",
  "consensus_answer": "1821",
  "customer_answer_relation": "ENTAILMENT",
  ...
}

The four fields you'll almost always use:

• verdict — one of high_confidence, low_confidence, insufficient_information. Use this to decide whether to surface the answer to a user.
• confidence — a number in [0.0, 1.0] for fine-grained thresholding.
• uncertainty_class — the kind of uncertainty. Distinguishes "model doesn't know" from "model is making it up" from "candidates disagree." See Response schemas.
• diagnosis — a human-readable explanation of why the score came out the way it did. Surface this to your engineers or to end users.

Authentication

Every request must include your API key in the Authorization header as a Bearer token. Keys look like qe_ followed by ~42 random characters.

Authorization: Bearer qe_YOUR_KEY_HERE
Content-Type: application/json

Missing or invalid keys return 401 unauthorized. The most common causes are: typo in the key, key was revoked, or the Bearer prefix was omitted.

Rotating a key

Go to the dashboard and click the rotate (↻) button next to your masked key. The old key is revoked instantly and a new one is shown once. Any code using the old key will start returning 401 immediately, so deploy the new key first.

POST /v1/verify

Given a prompt (the question) and a candidate answer, returns a confidence score and diagnosis. This is the primary endpoint — use it whenever you have an AI-generated answer and want to know whether to trust it.

Request body

Example request

curl https://api.qear.ai/v1/verify \
  -H "Authorization: Bearer qe_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Who wrote the novel '\''The Master and Margarita'\''?",
    "answer": "Mikhail Bulgakov",
    "confidence_target": 0.8
  }'

import requests

r = requests.post(
    "https://api.qear.ai/v1/verify",
    headers={"Authorization": f"Bearer {QEAR_KEY}"},
    json={
        "prompt": "Who wrote 'The Master and Margarita'?",
        "answer": "Mikhail Bulgakov",
        "confidence_target": 0.8,
    },
)
data = r.json()

const r = await fetch("https://api.qear.ai/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${QEAR_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Who wrote 'The Master and Margarita'?",
    answer: "Mikhail Bulgakov",
    confidence_target: 0.8,
  }),
});
const data = await r.json();

Example response

{
  "confidence": 0.94,
  "verdict": "high_confidence",
  "customer_answer_relation": "ENTAILMENT",
  "uncertainty_class": "none",
  "diagnosis": "All 5 valid candidates agreed semantically. High confidence in the consensus answer.",
  "recommended_action": "Trust the answer.",
  "consensus_answer": "Mikhail Bulgakov",
  "alternative_answers": [],
  "semantic_entropy": 0.0,
  "cascade": {
    "rounds": 1,
    "cumulative_samples": 5,
    "cluster_count": 1,
    "nli_calls": 0
  },
  "auxiliary_signals": {
    "default_fraction": 0.0,
    "refusal_fraction": 0.0
  },
  "usage": {
    "input_tokens": 142,
    "output_tokens": 38,
    "latency_ms": 812
  },
  "model": {
    "provider": "groq",
    "id": "llama-3.3-70b-versatile"
  }
}

See Response schemas for the full field reference, including all possible verdict and uncertainty_class values and what each means.

POST /v1/generate

Asks QEAR to generate an answer to a prompt and assess its own confidence in that answer. Unlike /v1/verify, you don't supply a candidate answer — QEAR produces one and returns it alongside the diagnostic. Use this when you don't have an LLM call of your own to verify.

Request body

Example request

curl https://api.qear.ai/v1/generate \
  -H "Authorization: Bearer qe_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the capital of Australia?"
  }'

Example response

The response shape is the same as /v1/verify, except there is no customer_answer_relation field (you didn't provide an answer). The consensus_answer is QEAR's best answer, and the verdict applies to that answer.

{
  "confidence": 0.96,
  "verdict": "high_confidence",
  "uncertainty_class": "none",
  "diagnosis": "All 5 valid candidates agreed semantically. High confidence in the consensus answer.",
  "recommended_action": "Trust the answer.",
  "consensus_answer": "Canberra",
  "alternative_answers": [],
  "semantic_entropy": 0.0,
  ...
}

Errors

All errors return a JSON body with an error.code machine-readable identifier and a human-readable error.message. The HTTP status code reflects the error class.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exceeded for this endpoint",
    "quota": {
      "current": 200,
      "limit": 200,
      "remaining": 0,
      "is_over_limit": true
    }
  },
  "request_id": "req_eb50bd77341e474b"
}

Errors include a request_id. Include it in any support email — it lets us look up exactly what happened.

Rate limits & quotas

QEAR enforces two kinds of limits: per-minute rate limits to prevent abuse, and monthly quotas that determine your tier. Both apply at the user level (not per API key), so generating more keys doesn't increase your allotment.

When you exceed a monthly quota, QEAR returns 429 quota_exceeded and stops processing requests until the start of the next calendar month (UTC). Upgrade your tier at the dashboard to lift the limit immediately.

Response schemas

Both /v1/verify and /v1/generate return the same shape (verify additionally includes customer_answer_relation). The fields that drive integration decisions:

verdict

A single token summarizing whether the answer should be trusted.

uncertainty_class

The kind of uncertainty involved. This is the diagnostic signal that distinguishes "model doesn't know" from "model is making it up" — most use cases should branch on this field.

customer_answer_relation

(Only on /v1/verify.) How the customer's submitted answer relates to QEAR's consensus answer.

Diagnostic fields

Cascade & usage metadata

Auxiliary fields useful for debugging and cost tracking.