Quickstart — 5 minutes to your first analyzed result

Pricing units and billing buckets

Billing is prepaid usage-based. Text buckets are character-based, not token-based and not per-call.

Limits, sync behavior, and client timeouts

Observed latency, last 30 days

Measured from analysis_logs.latency_ms over the last 30 days. These are observed production logs, not an SLA; small media/video samples are directional.

Complete response example

Text responses include scores, evidence, fixes, routing, limitations, model version, and billing. Media responses keep the same routing spine and add modality-specific fields such as synthetic_image_risk, synthetic_audio_risk, or synthetic_video_risk.

{
  "analysis_id": "ana_01HX...",
  "modality": "text",
  "content_trust_score": 0.42,
  "synthetic_risk": 0.61,
  "slop_risk": 0.74,
  "specificity_risk": 0.74,
  "provenance_weakness": 0.55,
  "synthetic_texture_risk": 0.61,
  "risk_level": "high",
  "recommended_action": "human_review",
  "primary_reason": "unsupported_claim",
  "confidence": "medium",
  "evidence": [
    {
      "type": "unsupported_claim",
      "severity": "high",
      "span": "pickpockets are everywhere",
      "explanation": "Absolute safety claim without a named source, location, or bounded condition."
    }
  ],
  "recommended_fixes": [
    "Replace absolute warnings with named locations, mechanisms, dates, and sourceable evidence."
  ],
  "limitations": ["Workflow signals, not forensic proof."],
  "revised_text": "Only present when auto_revise:true and recommended_action is revise.",
  "model_version": "v0.1",
  "billing": {"units_analyzed":1,"bucket":"text_1k_units","price_cents":0.5,"remaining_balance_cents":149.5}
}

Evidence spans

evidence[].span is currently the exact substring or observable cue text, not a character-offset object. If you need UI highlighting, find the first matching substring in the submitted text and fall back to displaying the evidence card when no exact match exists. Character offsets are a roadmap improvement.

Recommended fixes

recommended_fixes are human/agent instructions. They are not guaranteed patches. Use them to prompt a writer, revision agent, moderation queue, or source-checking workflow.

Error response shape

Errors use application/problem+json plus an x-request-id header. See /docs/errors for retry policy.

{
  "type": "https://veracityapi.com/problems/bad_request",
  "title": "Bad Request",
  "status": 400,
  "detail": "content: Text content must be 20-100000 characters",
  "instance": "req_01HX...",
  "code": "bad_request"
}

Action policy and score relationships

For text v0.1, risk_level = threshold(max(synthetic_risk, slop_risk)): below 0.40 = low, below 0.70 = medium, 0.70+ = high. specificity_risk and provenance_weakness are derived explanatory axes: they help queues and dashboards understand why the content trust score fell, but they do not independently override risk_level in v0.1.

content_trust_score is higher-is-better and derived from the strongest quality/provenance/texture penalty. Use confidence to decide whether to trust automation: high confidence can route automatically in low-stakes workflows; medium/low confidence should bias toward review when stakes are high.

This is workflow triage, not forensic proof. Do not use VeracityAPI as legal, academic misconduct, identity, speaker-verification, or authorship evidence.

Batch endpoint semantics

POST https://api.veracityapi.com/v1/analyze-batch
GET  https://api.veracityapi.com/v1/balance

• Batch v0.1 supports text items only.
• Results preserve request order: results[i] corresponds to items[i].
• The HTTP status is 200 for a syntactically valid batch; per-item failures are returned as {"status":"error","error":...} inside the array.
• The batch is debited before processing using the sum of per-item rounded-up text units. If the scoring provider fails for the whole batch, usage is refunded. Per-item validation should be caught before billing by request validation.
• auto_revise is disabled for batch v0.1.

Versioning, idempotency, and language coverage

• Model version: every response includes model_version. The public default is v0.1. There is no request-body model selector yet.
• Rollouts: threshold-changing model updates should ship with a new model version, docs update, and eval note before being treated as production-stable.
• Idempotency: send Idempotency-Key on POST /v1/analyze retries. Successful responses are cached for 24h per account, endpoint, and key. Replays return the original JSON with Idempotency-Replayed: true and do not debit credits again. Reusing the same key with a different request body returns 409 idempotency_conflict.
• Language: English-calibrated first. Non-English and RTL content are experimental until language-specific evals are published.

auto_revise behavior

auto_revise:true runs an additional revision pass only when text routes to revise. It is designed to preserve factual claims, links, Markdown-ish structure, and the caller's domain context when possible. It is not a deterministic diff engine and should not be used for legal/compliance rewrites without review. HTML should be submitted as text or pre-extracted content; sanitize rendered HTML in your own application.

Privacy, auth, and browser guidance

• Customer-submitted content is not used to train models.
• Raw text/content/media bytes/full media URLs are not stored by default; logs retain hashes, metadata, response JSON, billing, model version, and latency.
• Image/audio/video endpoints store no raw media bytes, base64 payloads, contact sheets, frames, or full URLs.
• privacy-safe defaults: customer content is not used for training, and API keys are bearer secrets. Keep keys server-side, rotate keys from /account, and never hardcode them in Chrome extensions or browser JavaScript. Use a backend token exchange for browser/extension flows.

See Privacy, Security, Subprocessors, and Status.