Make your first verification request in five minutes. We'll create a key, run a Unify query, and parse the response.

Before you start

You'll need a TruVerifAI account. Sign up at truverif.ai/auth/login — 50 free credits land in your account immediately. No credit card required.

1. Create an API key

Sign in and go to Settings · API · Create key. Give it a name and accept the Acceptable Use Policy.

2. Run your first query

All requests go to https://api.truverif.ai/v1/queries. Pick a mode (unify, justify, or verify) and pass your prompt. The endpoint returns a request_id immediately — the job runs asynchronously.

curl https://api.truverif.ai/v1/queries \
  -H "Authorization: Bearer $TVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "unify",
    "prompt": "What is the capital of France?"
  }'

3. Get the result

Two patterns:

• Polling. Hit GET /v1/queries/<id> every 5–10 seconds. Read the status field; when it's completed, the body has the full answer.
• SSE stream. Open GET /v1/queries/<id>/stream once. Receive progress events plus a final result event.

Verify mode can take up to 5 minutes. Plan your timeout accordingly — the 30-second default in most HTTP clients won't work.

curl https://api.truverif.ai/v1/queries/$REQUEST_ID \
  -H "Authorization: Bearer $TVAI_KEY"

Every request requires a Bearer token. Pass it in the Authorization header:

Authorization: Bearer tvai_a3k9hKwM2qFs8xPnRtVu1bBcDeFgHjKmNpQrStUv

Key format

Keys start with tvai_followed by an 8-character public fingerprint and a 32-character secret body — 45 characters total. The fingerprint is safe to log; the body isn't.

Key safety

• Never commit keys to source control. Use environment variables or a secrets manager.
• Never call the API directly from a browser, mobile app, or any end-user-controlled environment. Always proxy through your own backend.
• If a key leaks, revoke it from Settings · API — revocation is terminal. Disable instead if you want a reversible pause.

Errors

• 401 invalid_api_key— secret doesn't verify. Check the value, including the prefix.
• 401 key_revoked — terminal revocation. Create a new key.
• 403 key_suspended — admin-suspended (AUP review, billing dispute, etc.). Contact support.
• 403 key_disabled — you disabled it via the dashboard. Re-enable from Settings · API.

Pick the depth of verification. All three return the same shape; differences are in what blocks are populated.

1, 2.5, and 5 credits assume Standard-tier models across all four families. Actual credits per query also vary with query complexity and the amount of web research required. Call POST /v1/estimate-cost for a pre-flight estimate of the current selection.

Selecting models per request

The optional models field on POST /v1/queriesoverrides the user's default selection for that request. Pass null to skip a provider entirely.

curl https://api.truverif.ai/v1/queries \
  -H "Authorization: Bearer $TVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "unify",
    "prompt": "...",
    "models": {
      "openai": "gpt-5.4-2026-03-05",
      "anthropic": null,
      "google": null,
      "xai": null
    }
  }'

Pass any of these model_id values in the models object on POST /v1/queries. The default model per provider runs when you omit that provider's key.

Per-request override pattern

The models field on a request is an object keyed by provider. Set nullto skip a provider entirely; omit a key to fall back to the user's default.

{
  "mode": "unify",
  "prompt": "...",
  "models": {
    "openai":    "gpt-5.4-2026-03-05",   // pin a specific OpenAI model
    "anthropic": null,                    // skip Anthropic for this request
    "google":    null,                    // skip Google
    "xai":       null                     // skip xAI
  }
}

Skipping providers reduces actual provider cost but currently does not reduce the credit multiplier — billing still uses the full default-model multiplier. (We're fixing this; see the post-launch backlog.)

Bring Your Own Modellets you plug your own API keys — OpenAI, Anthropic, Google AI Studio, Together, OpenRouter, Fireworks, Ollama, AWS Bedrock, GCP Vertex — into TruVerifAI alongside our four default providers. You pay your provider directly; TruVerifAI doesn't charge for BYOM inference and treats it as zero variable cost when deducting credits.

What you can do in the web app

Visit /settings/byom to add a custom model. You'll paste your provider's API key, give the BYOM a display name, and pick the model_id to call. We test the connection before saving, encrypt the key at rest, and surface it in the chat composer alongside the four default-provider toggles. Per query, run any combination of the four first-party providers plus your enabled BYOMs.

Setup walkthroughs per provider — including the exact base URLs for OpenAI-compatible aggregators — live at /docs/byom.

How BYOMs participate in queries

BYOMs flow through the same pipeline as first-party models for all three modes (Unify / Justify / Verify):

• Same web-search two-round flow — BYOMs decide when to search and get Tavily results back the same way first-party does.
• Same file-attachment handling (PDFs / images / docs) shaped per the BYOM's declared capabilities.
• Same project-memory + verification-mode prompt prepends.
• Justify Round 2 deliberation — BYOMs see the other participants' Round 1 answers and produce a revision.
• Verify ledger — claims extracted from BYOM responses are verified against web sources, same as first-party claims.

Calling a BYOM from the API

Add a custom_models array to POST /v1/queries. Each entry is a byom_<id> string — the same ids GET /v1/models returns in its custom group. The BYOM participates alongside the four first-party models, or set the first-party models to null to run a BYOM-only query.

curl https://api.truverif.ai/v1/queries \
  -H "Authorization: Bearer $TVAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "unify",
    "prompt": "Compare GPT-4o with our fine-tuned model.",
    "custom_models": ["byom_42"]
  }'

In the response, that BYOM's entry in models[] reports provider: "custom" with a custom_model field echoing the id, so you can map responses back to the BYOM that produced them.

Cost & credits

BYOM model invocation costs are notbilled by TruVerifAI — you're paying your provider directly. We do still incur cost for the rest of the pipeline (web search, Justify Round 2 aggregation, Verify claim extraction, etc.) and those run regardless of who provided the models.

Concretely: in the credit-multiplier formula, BYOMs contribute zero to the variable cost. A 4-first-party query and a 3-first-party + 1-BYOM query are charged the same. A BYOM-only query still costs the mode's fixed orchestration credits.

Verifications run in the background. Submit returns 202 with a request_id; the actual answer arrives via polling or SSE.

Polling

Poll GET /v1/queries/<id> until status is completed or failed. Recommended cadence: 5s for the first 60 seconds, 10s after. Don't poll faster than 1s — you'll burn rate-limit quota on no-op fetches.

SSE stream

Open GET /v1/queries/<id>/stream once. The server pushes progress events while the job runs and a terminal result event when complete (or error on failure). The connection closes after the terminal event.

event: progress
data: {"stage": "running_models", "percent": 25, "message": "openai responded"}

event: progress
data: {"stage": "aggregating", "percent": 80}

event: result
data: {"request_id": "req_...", "status": "completed", "answer": {...}}

Restart caveat (V1)

Pass Idempotency-Key on POST /v1/queries to make submission safe to retry.

Behavior

• Replay within 24 hours with the same body — original request_id returned with idempotent_replayed: true.
• Replay with a different body — 409 idempotency_conflict. Either change the key or let the original expire.
• Retry after 24h — keys expire; submission treated as a fresh request.

Choosing keys

Any unique string ≤ 200 characters. UUIDs are fine. For retry loops on a specific source object (a CMS post, an article ID), derive the key from the object's ID + a short hash of the prompt so retries on the same object collapse but distinct operations don't collide.

Per API key:

• 60 requests / minute. Sliding window.
• 8 concurrent in-flight queries. Submitting while at the cap returns 429.
• 32 KB max prompt size.Files are uploaded separately and don't count toward this.
• 5 files per request.

When you hit a limit

429 rate_limited with a Retry-After header (seconds). Honor it; don't retry sooner. Exponential backoff is unnecessary at this scale.

Every error returns the same envelope. The code field is stable — branch on it, not on the message.

{
  "error": {
    "code": "invalid_model",
    "message": "Unknown model_id: gpt-99",
    "request_id": null,
    "retriable": false,
    "retry_after_seconds": null,
    "docs_url": "https://docs.truverif.ai/errors/invalid_model"
  }
}

Retry guidance

• 4xx with retriable: false — fix the request before retrying.
• 429 — honor Retry-After.
• 5xx with retriable: true — retry after a short backoff (1s, then 5s, then give up).
• 503 service_restarting — re-submit with the same Idempotency-Key.

Common codes

• invalid_request, invalid_prompt, invalid_mode, invalid_models, invalid_model — validation. Fix the request.
• insufficient_credits, monthly_cap_exceeded — billing. Top up or raise the cap.
• rate_limited, idempotency_conflict — retry-able with delay or new key.
• provider_error, aggregation_failed, service_restarting — server-side. Retry per guidance above.

Full list with HTTP status codes and triggers: API reference.

Upload first via POST /v1/files, then reference the returned file_id in your query.

Supported types

• Images — PNG / JPG / GIF / WEBP (max 20 MB)
• PDFs — max 32 MB
• Documents — DOC / DOCX (max 32 MB)
• Code — py / js / ts / html / css / json / yaml / sql (max 10 MB)

Per request: 5 files max, 20 MB combined. Files auto-expire 48h after upload.

Files & credit cost

Files don't apply a fixed multiplier under the V2 credit system — the actual credits charged depend on the tokens the attached file consumes when fed through the models. Larger or more complex files (multi-page PDFs, dense images) increase per-query tokens, which raises the cost+ charge; small files often add negligible credits.

Provider compatibility

Not every provider handles every file type natively. The engine falls back to text extraction where possible. Anthropic handles images and PDFs natively; OpenAI extracts text from PDFs. The details rarely matter — submit the file and the engine routes it.

Verify mode performs web search automatically. Unify and Justify accept an explicit web_search parameter.

Values

• auto (default) — engine decides based on prompt heuristics
• always — force web search regardless of mode
• never — disable web search even on Verify

Sources in the response

When web search runs, the response includes an evidence_sources array — URLs, titles, snippets, and which providers cited each source. Verify mode additionally returns per-claim source attribution under verify.facts.verified[*].verification.sources.

• Browse the full API reference for every endpoint and field.
• Get a key from Settings · API.
• Hit a wall? Email vivek@truverif.ai.