Skip to content
TruthVouch Docs

API Overview

The TruthVouch REST API provides direct HTTP access to all governance, compliance, brand intelligence, and certification features. All SDKs use this API under the hood.

Trust API Dashboard

Base URLs

ServiceURLPurpose
Governance Firewallhttps://gateway.truthvouch.com/api/v1LLM routing, scanning, governance
Main APIhttps://api.truthvouch.com/api/v1Dashboard data, alerts, certifications, users
Trust APIhttps://trust.truthvouch.com/api/v1Public fact-checking service (no auth)

Authentication

All endpoints (except Trust API) require authentication via one of:

Terminal window
curl -H "Authorization: Bearer tv_live_..." \
  https://api.truthvouch.com/api/v1/alerts

API Key Header

Terminal window
curl -H "X-API-Key: tv_live_..." \
  https://api.truthvouch.com/api/v1/alerts

JWT Token

Terminal window
curl -H "Authorization: Bearer <access_token>" \
  https://api.truthvouch.com/api/v1/alerts

Request Format

All requests use application/json:

Terminal window
curl -X POST https://api.truthvouch.com/api/v1/governance/scan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tv_live_..." \
  -d '{
    "prompt": "Tell me about AI",
    "response": "AI stands for artificial intelligence..."
  }'

Response Format

All successful responses follow this envelope:

{
  "data": {
    "id": "alert-uuid",
    "severity": "high",
    "type": "hallucination"
  },
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 150,
    "totalPages": 6
  }
}

Structure:

  • data — The actual response (object, array, or primitive)
  • meta — Pagination and response metadata (omitted for non-list endpoints)

Error Responses

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request payload",
    "statusCode": 400,
    "details": [
      {
        "field": "response",
        "message": "response is required"
      }
    ],
    "requestId": "req_1234567890abcdef"
  }
}

Fields:

  • code — Standardized error code for programmatic handling
  • message — Human-readable error description
  • statusCode — HTTP status code
  • details — Field-level validation errors (if applicable)
  • requestId — Trace ID for support inquiry

See Error Handling → for all error codes.

HTTP Status Codes

CodeMeaningExample
200SuccessRequest succeeded
201CreatedResource created successfully
204No ContentSuccess with no response body
400Bad RequestInvalid request payload
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
409ConflictResource already exists
422Validation ErrorInvalid field values
429Too Many RequestsRate limit exceeded
500Server ErrorInternal error (rare)
503Service UnavailableMaintenance or outage

Rate Limiting

Requests are rate-limited based on your subscription tier:

TierRequests/MinConcurrentBurst
Sandbox605100
Professional1,000252,000
EnterpriseCustomCustomCustom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1678886400

On 429 Too Many Requests, check Retry-After:

Retry-After: 60

Pagination

List endpoints support pagination:

Terminal window
curl "https://api.truthvouch.com/api/v1/alerts?page=2&pageSize=50" \
  -H "Authorization: Bearer tv_live_..."

Query Parameters:

  • page — Page number (default: 1)
  • pageSize — Results per page (default: 25, max: 100)
  • sortBy — Field to sort by (default: createdAt)
  • sortOrder — asc or desc (default: desc)

Response includes metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "pageSize": 50,
    "total": 1250,
    "totalPages": 25
  }
}

Filtering

List endpoints support filtering:

Terminal window
curl "https://api.truthvouch.com/api/v1/alerts?severity=high&status=open" \
  -H "Authorization: Bearer tv_live_..."

Available filters vary by endpoint. See individual endpoint docs for details.

Versioning

Current API version: v1

Version in URL path: https://api.truthvouch.com/api/v1/...

All v1 endpoints are stable. Breaking changes require a major version bump with 6-month deprecation notice.

Webhooks

Subscribe to real-time events:

Terminal window
POST https://api.truthvouch.com/api/v1/webhooks \
  -H "Authorization: Bearer tv_live_..." \
  -d '{
    "url": "https://myapp.com/webhooks/alerts",
    "events": ["alert.created", "correction.deployed"],
    "active": true
  }'

Webhook Documentation →

Timeouts

  • Default timeout: 30 seconds
  • Max request duration: 5 minutes (for batch operations)
  • Streaming: No timeout (event-driven)

For longer operations, use batch APIs or webhooks instead of polling.

API Domains

TruthVouch API is organized by domain:

Governance

Control and monitor LLM call policies.

Shield

Manage truth nuggets, cross-checks, and alerts.

Compliance

Manage compliance registry and audit trails.

Brand Intelligence

Audit competitor sites and track brand narratives.

Certification

Submit and verify content certifications.

Trust API

Public fact-checking service (no authentication required).

Platform

User management, notifications, webhooks.

Next Steps