FactLens API reference.

Quickstart

Start in the https://api.factlens.pro/dashboard. Sign in, create a project, then create a project API key. Project API keys are runtime credentials and are shown once when created.

Install FactLens

npm install factlens

The same package contains the SDK and CLI. A local install is available through npx factlens. Install globally only when you want the bare factlens command available from any directory.

npm install -g factlens
factlens configure
factlens verify "The International Space Station circles Earth roughly every 90 minutes."

For servers and CI, prefer environment variables instead of saved CLI configuration:

FACTLENS_API_KEY=fl_live_YOUR_KEY
FACTLENS_DEVELOPER_TOKEN=fldev_live_YOUR_TOKEN

CLI

The official CLI calls the same SDK transport as application code. It does not expose separate search, AI, or transcription commands; those are internal verification stages.

Configure credentials

factlens configure
factlens config show
factlens doctor

factlens configure saves credentials in your operating system user configuration directory and masks them when displayed. Environment variables override saved values.

Verify text

factlens verify "Earth orbits the Sun."

# Local package install
npx factlens verify "Earth orbits the Sun."

Verify an image or post

factlens verify --image screenshot.png
factlens verify --image screenshot.png --claim "Optional focus for the image"

--claim is optional for image verification. When omitted, FactLens identifies the primary factual claim from the image itself.

Verify audio or video content

factlens verify --audio interview.mp3
factlens verify --audio clip.m4a --speaker "Jane Doe"
factlens list
factlens kill REQUEST_ID

The CLI streams long audio directly into the verification pipeline, shows live progress, and can list or stop local FactLens jobs. Audio is transcribed as an internal verification stage. There is no standalone transcription product endpoint.

Automation and diagnostics

factlens verify "A claim" --json
factlens verify "A claim" --timeout 90000 --retries 2
factlens usage
factlens logs --limit 20 --endpoint verify
factlens request 01914f52-79f6-7d4f-b456-426614174000

--json emits machine-readable success output and structured errors suitable for scripts. Human-readable output includes the verdict, explanation, confidence, evidence strength, sources, request ID, response time, and usage when available.

Node.js and TypeScript SDK

Install factlens in Node.js 18 or newer. The SDK supports ESM, CommonJS, and TypeScript declarations.

npm install factlens

Verify a text claim

import FactLens from "factlens";

const factlens = new FactLens();

const result = await factlens.verify({
  mode: "text",
  claim: "Earth orbits the Sun."
});

console.log(result.verdictId);
console.log(result.sources);

Verify an image

const result = await factlens.verify({
  mode: "image_post",
  image_base64: imageBase64,
  content_type: "image/png"
});

The SDK claim field is optional for image verification. Supply it only when you want to give FactLens additional focus or guidance.

Verify audio or video

const result = await factlens.verify({
  mode: "audio_video",
  audio_base64: audioBase64,
  content_type: "audio/mpeg"
});

console.log(result.transcript);
console.log(result.verdictId);

The SDK intentionally exposes Verify rather than generic managed search, AI, or transcription methods. Those capabilities exist only inside the FactLens verification pipeline.

Authentication

FactLens uses two credential classes. Keep both server-side and never commit them to source control.

Create or copy credentials from https://api.factlens.pro/dashboard. Project keys begin with fl_live_ or fl_test_. Developer tokens begin with fldev_live_.

REST authentication

Authorization: Bearer fl_live_YOUR_KEY

For idempotent POST behavior, send a UUID in X-Request-ID. The SDK and CLI generate one automatically for Verify unless you supply one.

Verify

POST /v1/verify is the public runtime operation. FactLens may transcribe media, retrieve current evidence, run required safety checks, and analyze the evidence internally before returning a verification result.

Text request

curl --request POST "https://api.factlens.pro/v1/verify" \
  --header "Authorization: Bearer fl_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Request-ID: 01914f52-79f6-7d4f-b456-426614174000" \
  --data '{
    "mode": "text",
    "claim": "The International Space Station circles Earth roughly every 90 minutes."
  }'

Text mode also accepts a paragraph, article excerpt, or transcript containing multiple factual claims. FactLens automatically extracts distinct checkable claims, removes duplicates, and independently retrieves evidence and produces a verdict for each claim.

Source preferences

Trusted and blocked domains can be saved as defaults for each API key in the developer dashboard. When a request omits a preference list, FactLens uses that key’s saved list. Supplying trusted_domains or blocked_domains on a request overrides the matching saved list for that request only, including an explicit empty array. Trusted domains are prioritized when matching evidence is available. Blocked domains are excluded and always take precedence if a domain appears in both lists.

{
  "mode": "text",
  "claim": "A claim to verify",
  "trusted_domains": ["reuters.com", "apnews.com"],
  "blocked_domains": ["example.com"]
}

Image/post request

{
  "mode": "image_post",
  "image_base64": "...",
  "content_type": "image/jpeg"
}

Image mode remains a single primary claim flow. The request claim field is optional focus or guidance; when omitted, FactLens identifies the primary factual claim in the image and verifies that claim. Image input is base64-only. Supported formats are PNG (image/png), JPEG/JPG (image/jpeg), WebP (image/webp), HEIC (image/heic), and HEIF (image/heif). FactLens checks the decoded signature, declared MIME, byte limit, and pixel dimensions before required image safety and vision analysis. Image bytes are processed in request memory and never stored in the database or request audit. Remote image URLs, SVG, GIF, AVIF, BMP, and TIFF are not accepted.

Audio/video request

{
  "mode": "audio_video",
  "audio_url": "https://example.com/interview.mp3",
  "speaker": "Jane Doe"
}

You may also provide inline audio_base64, a precomputed transcript, or an explicit claim. Audio verification is limited to 3 hours. Uploaded or URL based audio costs one API credit per 10 minutes or part thereof. A direct transcript includes the first 100,000 characters in the normal one credit charge, then adds one credit for every additional 30,000 characters or part thereof. Raw audio bytes are never stored in the database. When audio is supplied, FactLens performs transcription first; the resulting transcript then enters the same automatic multi-claim extraction and verification path used for text.

Single-claim successful response

{
  "request_id": "01914f52-79f6-7d4f-b456-426614174000",
  "mode": "text",
  "claim": "...",
  "verdictId": "TRUE",
  "verdictColor": "#22c55e",
  "explanation": "...",
  "confidence": "HIGH",
  "evidenceStrength": "STRONG",
  "sources": [
    { "url": "https://example.org/evidence", "title": "Evidence source" }
  ],
  "response_time_ms": 6410,
  "usage": { "requests_charged": 1 }
}

Multi-claim successful response

The existing top-level result fields remain backward compatible: the first successful result is copied there, while every independently checked claim is returned in results. claim_count reports the number of extracted claims. If at least one claim succeeds and another fails, failed_claims lists only those per-claim failures.

{
  "request_id": "01914f52-79f6-7d4f-b456-426614174000",
  "mode": "text",
  "claim": "First extracted claim",
  "verdictId": "TRUE",
  "verdictColor": "#22c55e",
  "explanation": "...",
  "confidence": "HIGH",
  "evidenceStrength": "STRONG",
  "sources": [],
  "claim_count": 3,
  "results": [
    {
      "claim": "First extracted claim",
      "verdictId": "TRUE",
  "verdictColor": "#22c55e",
      "explanation": "...",
      "confidence": "HIGH",
      "evidenceStrength": "STRONG",
      "sources": []
    },
    {
      "claim": "Second extracted claim",
      "verdictId": "FALSE",
  "verdictColor": "#22c55e",
      "explanation": "...",
      "confidence": "MEDIUM",
      "evidenceStrength": "MODERATE",
      "sources": []
    }
  ],
  "failed_claims": [
    { "claim": "Third extracted claim", "error": "VERIFICATION_SEARCH_FAILED", "stage": "search", "message": "..." }
  ],
  "response_time_ms": 12430,
  "usage": { "requests_charged": 1 }
}

results is included when multiple claims are detected or a per-claim failure needs to be reported. A normal single-claim request keeps the original response shape without requiring callers to read an array. response_time_ms is the server-measured verification duration. It is a server-owned field, as are request_id, mode, transcript, and usage. AI output cannot replace them. Source URLs are returned only when they match evidence retrieved for this request.

Customization

Each project API key can keep its own saved source preferences, verdict catalog, and supported Verify prompt settings. Configuration is isolated by API key: changing one key never changes another key or your browser-extension Console settings.

Source preferences

Trusted and blocked domains are saved per key. Request fields keep their existing precedence: supplying trusted_domains or blocked_domains overrides the matching saved list for that request only. Blocked domains always win when a domain appears in both lists.

Verdicts

The dashboard can customize the text, audio/video, and image/post verdict catalogs with stable verdict IDs, display names, colors, enabled state, a mode-wide selection instruction, and ordered selection rules. Custom verdicts use stable custom:UUID IDs so presentation changes do not rewrite result history. Every successful claim also returns verdictColor, the six-digit hex color from the effective verdict configuration: request-level verdict override first, then the saved API-key profile, then the FactLens default.

Prompts

API customers can customize claim extraction and evidence evaluation independently for text and audio/video, plus image extraction and image evaluation for images/posts. Extension-only media capture, transcription, search-provider, speaker, image-capture, image-evidence-search, and overlay controls are not exposed by the API dashboard.

Each exposed stage supports guided mode, which combines your instruction with the FactLens default, and Use my prompt only exact mode, which sends your complete rendered prompt for that stage. Supported runtime tags are shown in the dashboard.

Input budgets

Each prompt stage has an independent input budget. The default is 8,000 tokens, the minimum is 2,000, and the maximum is 20,000, normalized in 100-token increments. Existing valid saved values are preserved. The dashboard shows an approximate effective-prompt token count and remaining capacity before save.

The Estimated JSON output range shown beside each prompt is guidance, not a response limit. Actual output depends on the number of claims and sources; FactLens keeps its existing provider/structured-output safety limits independently.

Runtime usage

GET /v1/usage uses the project API key and returns the current account usage snapshot without consuming a verification request.

curl "https://api.factlens.pro/v1/usage" \
  --header "Authorization: Bearer fl_live_YOUR_KEY"

# SDK
const usage = await factlens.usage.get();

# CLI
factlens usage

Account management

Management operations require a developer token. Project API keys are deliberately rejected for account-level management.

CLI

factlens account
factlens projects list
factlens projects create "Production"
factlens projects select PROJECT_ID
factlens keys list
factlens keys create "Backend"
factlens logs --project PROJECT_ID --limit 50
factlens request REQUEST_ID
factlens usage --account

Destructive CLI actions require explicit confirmation with --yes.

SDK

const account = await factlens.account.get();
const projects = await factlens.projects.list();
const project = await factlens.projects.create({ name: "Production" });
factlens.projects.select(project.id);
const created = await factlens.keys.create({ label: "Backend" });
const logs = await factlens.logs.list({ limit: 50 });

New API-key secrets are returned once. Store them immediately in a secret manager.

Limits & billing

Limits and spend are account-level capacity even though credentials and logs are project-scoped. Creating more projects or keys does not create extra free allowance. Eligible free accounts receive 30 shared requests per UTC day. Paid pricing is simple: $1 funds 30 claim checks.

Existing unused paid balances are automatically migrated to the current 30-check request-credit scale; historical USD payment amounts do not change. Paid API credits are separate from FactLens Pro. See Pricing for the current credit model and Free API Credits for qualifying projects.

Errors & retries

Errors have a stable machine-readable error code, a human message, and request_id when the request reached the verification pipeline. Verify-stage failures also include a normalized stage.

Image validation can return INVALID_IMAGE_BASE64, INVALID_IMAGE_BYTES, UNSUPPORTED_IMAGE_TYPE, IMAGE_MIME_MISMATCH, INVALID_IMAGE_DIMENSIONS, IMAGE_PIXELS_TOO_LARGE, or IMAGE_DECODED_TOO_LARGE with HTTP 400 before provider work begins.

Stage-aware failure example

{
  "error": "VERIFICATION_SEARCH_FAILED",
  "message": "FactLens could not retrieve evidence for this verification request. Start a fresh request with a new X-Request-ID.",
  "stage": "search",
  "request_id": "01914f52-79f6-7d4f-b456-426614174000",
  "details": { "upstream_code": "SEARCH_503" }
}

Reuse the same X-Request-ID for an intentional retry. A completed request replays its stored response, an active lease reports REQUEST_IN_PROGRESS, and a crashed request can be recovered after its lease expires without another charge. The SDK and CLI retry retryable transport/status failures with the same request ID during one invocation, then surface the final structured error.

Use factlens verify "..." --json in automation to receive the stable CLI error envelope, including code, HTTP status, request ID, retryability, stage, details, and dashboard help URL when applicable.