Eve library

Veritas API Documentation

Architecture

Revision 1

On this page

Complete REST API reference for the Veritas news platform. The API is built on Hono and serves all endpoints under the /api/v1 prefix on port 3001.

Base URL: http://localhost:3001/api/v1 (development) OpenAPI Spec: Available at /openapi.json and interactive docs at /docs when OPENAPI_ENABLED=true.


Table of Contents#

  1. Authentication
  2. Rate Limiting
  3. Error Handling
  4. Pagination
  5. Endpoints
  6. Schemas
  7. Environment Variables

Authentication#

The API supports two authentication mechanisms:

Bearer Token (JWT)#

Obtain a token via POST /api/v1/auth/login, then include it in subsequent requests:

text
Authorization: Bearer <access_token>

Token Details:

  • Algorithm: HMAC-SHA256 (custom implementation, no external library)
  • Default TTL: 7 days
  • Payload: { sub: userId, email, iat, exp }
  • Signature verification uses timing-safe comparison to prevent timing attacks

API Key#

For B2B and machine-to-machine access, include the API key in a header:

text
X-API-Key: <your_api_key>

The header name is configurable via API_KEY_HEADER. API key validation uses timing-safe constant-time comparison.

Exempt Endpoints (no auth required):

  • GET /health, GET /healthz, GET /readyz, GET /health/detailed
  • GET /docs, GET /openapi.json
  • All public read endpoints (article listing, search, sources, taxonomy)

Rate Limiting#

All /api/* endpoints are rate-limited using a sliding window algorithm.

Defaults:

  • Window: 60 seconds
  • Max Requests: 120 per window
  • Backend: Redis sorted sets (falls back to in-memory if Redis unavailable)

Client Identification:

Priority order: X-Forwarded-For -> X-Real-IP -> "unknown"

Response Headers:

Header Description
X-RateLimit-Limit Maximum requests allowed in the window
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the window resets
Retry-After Seconds until requests are allowed (on 429 only)

429 Response:

json
{
  "error": "Too Many Requests",
  "retryAfterSeconds": 42
}

Error Handling#

All errors return consistent JSON responses.

Error Response Formats#

Standard Error:

json
{
  "error": "Human-readable error message"
}

Validation Error (400):

json
{
  "error": "Validation Error",
  "issues": [
    { "path": "email", "message": "Invalid email format" },
    {
      "path": "password",
      "message": "String must contain at least 8 character(s)"
    }
  ]
}

Rate Limit Error (429):

json
{
  "error": "Too Many Requests",
  "retryAfterSeconds": 42
}

HTTP Status Codes#

Code Meaning When Used
200 OK Successful GET, PUT, PATCH
201 Created Successful POST creating a resource
204 No Content Successful DELETE
400 Bad Request Validation errors, malformed JSON
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
409 Conflict Resource already exists (e.g., email)
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server error
503 Service Unavailable Database or dependency down

Error Helper Functions#

The API uses standardized error constructors:

typescript
validationError(c, issues); // 400
unauthorizedError(c, message); // 401
forbiddenError(c, message); // 403
notFoundError(c, resource); // 404
conflictError(c, message); // 409
serviceUnavailableError(c, msg); // 503

In development mode (NODE_ENV !== 'production'), 500 errors include additional debugging details in the response.


Pagination#

Cursor-Based Pagination#

Most list endpoints use cursor-based pagination for consistent performance:

Query Parameters:

Parameter Type Default Description
limit int 20 Items per page (max: 100)
cursor string null Opaque cursor from previous response

Response:

json
{
  "items": [...],
  "nextCursor": "eyJpZCI6Ijk5OSIsInB1Ymxpc2hlZEF0IjoiMjAyNi0wMS0yNSJ9"
}

When nextCursor is null, there are no more items.

Search endpoints use offset-based pagination:

Parameter Type Default Description
page int 1 Page number
pageSize int 20 Items per page

Response:

json
{
  "items": [...],
  "total": 1523,
  "page": 1,
  "pageSize": 20,
  "totalPages": 77
}

Endpoints#

Health#

Health check endpoints are exempt from authentication and rate limiting.

GET /health#

Basic liveness check.

json
{ "status": "ok", "service": "veritas-api", "time": "2026-01-26T12:00:00.000Z" }

GET /healthz#

Kubernetes liveness probe. Returns 200 with minimal body.

GET /readyz#

Kubernetes readiness probe. Checks database, Redis, and Elasticsearch connectivity.

Response (healthy):

json
{
  "status": "ok",
  "service": "veritas-api",
  "time": "2026-01-26T12:00:00.000Z",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "elasticsearch": "ok"
  }
}

Response (degraded - 503):

json
{
  "status": "degraded",
  "checks": {
    "database": "ok",
    "redis": "error",
    "elasticsearch": "ok"
  }
}

GET /health/detailed#

Full health report with latency metrics for each dependency.

json
{
  "status": "ok",
  "service": "veritas-api",
  "time": "2026-01-26T12:00:00.000Z",
  "checks": {
    "database": { "status": "ok", "latencyMs": 2 },
    "redis": { "status": "ok", "latencyMs": 1 },
    "elasticsearch": { "status": "ok", "latencyMs": 15 }
  }
}

Auth#

POST /api/v1/auth/register#

Register a new user account.

Request Body:

json
{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "Kwame Asante"
}
Field Type Required Constraints
email string Yes Valid email format
password string Yes Min 8 characters
name string No Display name

Response (201):

json
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "Kwame Asante"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "accessTokenExpiresAtMs": 1738000000000
}

Errors: 400 (validation), 409 (email exists), 503 (DB unavailable)

POST /api/v1/auth/login#

Authenticate and receive a JWT token.

Request Body:

json
{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200):

json
{
  "user": { "id": "...", "email": "...", "name": "..." },
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "accessTokenExpiresAtMs": 1738000000000
}

Errors: 401 (invalid credentials), 503 (DB unavailable)

GET /api/v1/auth/me#

Get the currently authenticated user's profile.

Headers: Authorization: Bearer <token> (required)

Response (200):

json
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "Kwame Asante"
  }
}

Errors: 401 (not authenticated)


Articles#

GET /api/v1/articles#

List published articles with optional filtering.

Query Parameters:

Parameter Type Default Description
limit int 20 Items per page (1-100)
cursor string -- Pagination cursor
category string -- Filter by category slug
topic string -- Filter by topic slug
source string -- Filter by source domain
lang string -- Filter by language tag (en, tw, etc.)

Response (200):

json
{
  "items": [
    {
      "id": "uuid",
      "slug": "ghana-election-results-2024",
      "headline": "Ghana Election Results: NPP Wins...",
      "summary": "Summary text...",
      "publishedAt": "2026-01-26T08:00:00.000Z",
      "languageTag": "en",
      "readTimeSeconds": 240,
      "source": { "name": "GhanaWeb", "domain": "ghanaweb.com", "url": "..." },
      "sourceUrl": "https://ghanaweb.com/...",
      "featuredImage": {
        "url": "...",
        "alt": "...",
        "width": 800,
        "height": 450
      },
      "categories": [{ "slug": "politics", "name": "Politics" }],
      "topics": [
        { "slug": "elections", "name": "Elections", "categorySlug": "politics" }
      ]
    }
  ],
  "nextCursor": "eyJpZCI6Ijk5OSJ9"
}

GET /api/v1/articles/trending#

Get trending articles based on view velocity.

Query Parameters:

Parameter Type Default Description
limit int 10 Number of articles (1-50)
period str 24h Trending period (1h, 6h, 24h)

Response (200):

json
{
  "items": [{ "id": "...", "headline": "...", "...": "..." }]
}

GET /api/v1/articles/search#

Full-text search across articles (requires Elasticsearch).

Query Parameters:

Parameter Type Default Description
q string -- Search query (required)
page int 1 Page number
pageSize int 20 Results per page (1-100)
category string -- Filter by category
source string -- Filter by source
lang string -- Filter by language

Response (200):

json
{
  "items": [...],
  "total": 1523,
  "page": 1,
  "pageSize": 20,
  "totalPages": 77
}

GET /api/v1/articles/suggest#

Autocomplete search suggestions.

Query Parameters:

Parameter Type Default Description
q string -- Prefix query (required)
limit int 5 Max suggestions (1-20)

Response (200):

json
{
  "suggestions": ["Ghana election", "Ghana economy", "Ghana football"]
}

GET /api/v1/articles/:id#

Get a single article by UUID.

Response (200):

json
{
  "id": "uuid",
  "slug": "...",
  "headline": "...",
  "summary": "...",
  "bodyHtml": "<p>Full article HTML...</p>",
  "bodyText": "Full article plain text...",
  "authors": ["Kwame Asante"],
  "publishedAt": "...",
  "languageTag": "en",
  "readTimeSeconds": 240,
  "source": { "name": "...", "domain": "..." },
  "politicalBiasScore": 0.15,
  "categories": [...],
  "topics": [...]
}

Errors: 404 (article not found)

GET /api/v1/articles/:id/related#

Get articles related to a specific article.

Query Parameters: limit (int, default: 5, max: 20)

Response (200):

json
{
  "items": [{ "id": "...", "headline": "...", "...": "..." }]
}

Stories#

Story clusters group related articles covering the same developing story.

GET /api/v1/stories#

List story clusters.

Query Parameters: limit, cursor

Response (200):

json
{
  "items": [
    {
      "id": "uuid",
      "title": "Ghana 2024 Election Coverage",
      "summary": "Ongoing coverage of...",
      "status": "active",
      "articleCount": 47,
      "createdAt": "...",
      "updatedAt": "...",
      "canonicalArticle": { "id": "...", "headline": "..." }
    }
  ],
  "nextCursor": "..."
}

GET /api/v1/stories/:id#

Get story cluster details.

GET /api/v1/stories/:id/articles#

Get all articles in a story cluster.

Query Parameters: limit, cursor


Claims & Fact-Checking#

GET /api/v1/claims#

List extracted claims with their verdicts.

Query Parameters: limit, cursor, verdict (filter by verdict type)

Response (200):

json
{
  "items": [
    {
      "id": "uuid",
      "text": "Ghana's GDP grew by 8% in 2025",
      "verdict": "mostly_true",
      "confidence": 0.85,
      "createdAt": "...",
      "sources": ["https://statsghana.gov.gh/..."]
    }
  ],
  "nextCursor": "..."
}

Verdict Values: true, mostly_true, half_true, mostly_false, false, unverifiable

GET /api/v1/claims/:id#

Get a specific claim with full evidence.

POST /api/v1/claims/fact-check#

Submit a claim for fact-checking. Requires authentication.

Request Body:

json
{
  "claim": "Ghana's cocoa production increased by 20% in 2025",
  "refresh": false,
  "maxResults": 10,
  "country": "GH",
  "language": "en",
  "freshness": "month"
}
Field Type Required Default Constraints
claim string Yes -- Max 500 chars
refresh boolean No false Force re-check
maxResults int No 10 1-20
country string No "GH" ISO 3166-1 alpha-2
language string No "en" Language code
freshness string No "month" day, week, month, year, any

Response (200):

json
{
  "claim": "Ghana's cocoa production increased by 20% in 2025",
  "verdict": "mostly_true",
  "confidence": 0.78,
  "summary": "While cocoa production did increase...",
  "evidence": [
    {
      "title": "Ghana Cocoa Board Annual Report 2025",
      "url": "https://cocobod.gh/reports/2025",
      "snippet": "Production volumes rose by 18.3%...",
      "publishedAt": "2025-12-15T00:00:00Z",
      "source": "cocobod.gh"
    }
  ]
}

GET /api/v1/claims/:id/articles#

Get articles that mention a specific claim.


Sources#

GET /api/v1/sources#

List news sources.

Query Parameters: limit, cursor, kind (newspaper, radio, tv, online, wire, government, blog)

Response (200):

json
{
  "items": [
    {
      "id": "uuid",
      "name": "GhanaWeb",
      "domain": "ghanaweb.com",
      "logoUrl": "https://...",
      "politicalLean": "center",
      "reliabilityScore": 0.72
    }
  ]
}

Political Lean Values: left, center-left, center, center-right, right

GET /api/v1/sources/bias-spectrum#

Get all sources plotted on the political bias spectrum.

Response (200):

json
{
  "spectrum": {
    "left": [{ "name": "...", "biasScore": -0.7 }],
    "center-left": [...],
    "center": [...],
    "center-right": [...],
    "right": [...]
  }
}

GET /api/v1/sources/media-groups#

Get media ownership group information.

GET /api/v1/sources/cross-ownership#

Analyze cross-ownership patterns among news sources.

GET /api/v1/sources/:id#

Get detailed source information.

GET /api/v1/sources/:id/transparency#

Get source transparency scores and methodology.

GET /api/v1/sources/:id/corrections#

Get correction history for a source.

GET /api/v1/sources/:id/bias#

Get detailed bias analysis for a source.

GET /api/v1/sources/:id/ownership#

Get ownership chain for a source.

GET /api/v1/sources/:id/regional-emphasis#

Get regional coverage emphasis for a source.


Bias Analysis#

POST /api/v1/bias/score#

Analyze political bias in a text passage.

Request Body:

json
{
  "text": "The government's economic policy has been remarkably successful..."
}
Field Type Required Constraints
text string Yes Max 20,000 chars

Response (200):

json
{
  "score": 0.35,
  "band": "positive",
  "confidence": 0.82
}
  • score: -1.0 (opposition-leaning) to 1.0 (government-leaning)
  • band: negative, neutral, positive
  • confidence: 0.0 to 1.0

Taxonomy#

GET /api/v1/taxonomy/categories#

List all content categories with their topics.

Response (200):

json
{
  "items": [
    {
      "slug": "politics",
      "name": "Politics",
      "description": "Political news and analysis",
      "topics": [
        {
          "slug": "elections",
          "name": "Elections",
          "categorySlug": "politics"
        },
        {
          "slug": "parliament",
          "name": "Parliament",
          "categorySlug": "politics"
        }
      ]
    }
  ]
}

GET /api/v1/taxonomy/topics#

List all topics.

Query Parameters: category (filter by category slug)


Preferences#

GET /api/v1/preferences#

Get user preferences. Requires authentication.

Response (200):

json
{
  "categories": ["politics", "business"],
  "topics": ["elections", "forex"],
  "sources": ["ghanaweb.com"],
  "languages": ["en", "tw"],
  "homeFeed": { "layout": "cards", "density": "comfortable" }
}

PUT /api/v1/preferences#

Update user preferences (full replace). Requires authentication.

PATCH /api/v1/preferences/home-feed#

Partially update home feed preferences. Requires authentication.


Tips#

POST /api/v1/tips#

Submit an anonymous tip. Tips are encrypted with AES-256-GCM before storage.

Request Body:

json
{
  "message": "I have information about corruption at...",
  "isAnonymous": true,
  "evidenceUrls": ["https://example.com/doc.pdf"],
  "contactEmail": "tipster@protonmail.com",
  "contactPhone": "+233201234567"
}
Field Type Required Constraints
message string Yes 20-20,000 characters
isAnonymous boolean No Default: true
evidenceUrls string[] No URLs to supporting docs
contactEmail string No Valid email format
contactPhone string No Phone number

Response (201):

json
{
  "id": "tip_2026012612000042",
  "submittedAt": "2026-01-26T12:00:00.000Z"
}

Writing Assistant#

POST /api/v1/writing-assistant/process#

AI-powered text processing for journalists. Requires authentication.

Request Body:

json
{
  "mode": "rewrite",
  "text": "The president spoke about the economy...",
  "instructions": "Make it more concise and formal",
  "tone": "journalistic",
  "languageTag": "en",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 500,
  "temperature": 0.3
}
Field Type Required Default Values
mode string Yes -- rewrite, shorten, expand, bulletize
text string Yes -- Max 20,000 chars
instructions string No -- Max 800 chars
tone string No -- Max 200 chars
languageTag string No -- Max 20 chars
provider string No "anthropic" anthropic, openai
model string No (default) Max 80 chars
maxTokens int No 500 120-1,800
temperature number No 0.3 0.0-1.0

Response (200):

json
{
  "result": "The president addressed economic developments...",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "tokensUsed": 285
}

Voice Profiles#

Manage ElevenLabs TTS voice profiles for audio article generation.

GET /api/v1/voice-profiles#

List all voice profiles.

GET /api/v1/voice-profiles/:id#

Get a specific voice profile.

POST /api/v1/voice-profiles#

Create a new voice profile. Requires authentication.

Request Body:

json
{
  "slug": "kwame-anchor",
  "providerVoiceId": "21m00Tcm4TlvDq8ikWAM",
  "displayName": "Kwame - News Anchor",
  "description": "Professional male voice for news reading",
  "languageTags": ["en", "tw"],
  "isActive": true
}

PUT /api/v1/voice-profiles/:id#

Update a voice profile. Requires authentication.

PATCH /api/v1/voice-profiles/:id/deactivate#

Deactivate a voice profile. Requires authentication.


Avatar Profiles#

Manage HeyGen avatar profiles for video article generation.

GET /api/v1/avatar-profiles#

List all avatar profiles.

GET /api/v1/avatar-profiles/:id#

Get a specific avatar profile.

POST /api/v1/avatar-profiles#

Create a new avatar profile. Requires authentication.

Request Body:

json
{
  "slug": "ama-presenter",
  "providerAvatarId": "heygen_avatar_abc123",
  "displayName": "Ama - News Presenter",
  "description": "Professional female presenter avatar",
  "isActive": true
}

PUT /api/v1/avatar-profiles/:id#

Update an avatar profile. Requires authentication.

PATCH /api/v1/avatar-profiles/:id/deactivate#

Deactivate an avatar profile. Requires authentication.


Subscriptions#

GET /api/v1/subscriptions/plans#

List available subscription plans with pricing.

Response (200):

json
{
  "plans": [
    {
      "id": "premium_monthly",
      "tier": "premium",
      "name": "Veritas Premium",
      "interval": "monthly",
      "prices": {
        "GHS": 29.99,
        "USD": 4.99,
        "EUR": 4.49,
        "GBP": 3.99
      },
      "features": [
        "ad-free",
        "audio-articles",
        "video-bulletins",
        "advanced-search"
      ]
    }
  ]
}

POST /api/v1/subscriptions#

Create a new subscription. Requires authentication.

GET /api/v1/subscriptions/current#

Get the user's current subscription. Requires authentication.

DELETE /api/v1/subscriptions/current#

Cancel the current subscription. Requires authentication.

GET /api/v1/subscriptions/usage#

Get current subscription usage metrics. Requires authentication.

GET /api/v1/subscriptions/access/:feature#

Check if user has access to a specific feature. Requires authentication.

POST /api/v1/subscriptions/family/invite#

Invite a family member (Family plan only). Requires authentication.

POST /api/v1/subscriptions/student/verify#

Verify student status for student pricing. Requires authentication.


Payments - MTN MoMo#

POST /api/v1/payments/momo/request#

Initiate an MTN Mobile Money payment.

Request Body:

json
{
  "amount": 29.99,
  "currency": "GHS",
  "phoneNumber": "0241234567",
  "description": "Veritas Premium - Monthly"
}

GET /api/v1/payments/momo/status/:referenceId#

Check payment status.

POST /api/v1/payments/momo/preapproval#

Set up recurring payment preapproval.

POST /api/v1/payments/momo/refund#

Initiate a refund.

POST /api/v1/payments/momo/validate#

Validate a phone number for MoMo eligibility.

GET /api/v1/payments/momo/balance#

Check MoMo account balance (admin only).

POST /api/v1/payments/momo/callback#

Webhook endpoint for MoMo payment notifications.

GET /api/v1/payments/transactions#

List payment transactions. Requires authentication.

GET /api/v1/payments/subscriptions#

List payment-linked subscriptions. Requires authentication.


Payments - Vodafone Cash#

POST /api/v1/payments/vodafone/initiate#

Initiate a Vodafone Cash payment.

GET /api/v1/payments/vodafone/status/:transactionId#

Check Vodafone Cash payment status.

POST /api/v1/payments/vodafone/refund#

Initiate a Vodafone Cash refund.

POST /api/v1/payments/vodafone/callback#

Webhook endpoint for Vodafone Cash notifications.


Payments - AirtelTigo Money#

POST /api/v1/payments/airteltigo/initiate#

Initiate an AirtelTigo Money payment.

GET /api/v1/payments/airteltigo/status/:transactionId#

Check AirtelTigo Money payment status.

POST /api/v1/payments/airteltigo/refund#

Initiate an AirtelTigo Money refund.

POST /api/v1/payments/airteltigo/callback#

Webhook endpoint for AirtelTigo Money notifications.


Payments - Stripe#

POST /api/v1/payments/stripe/create-checkout#

Create a Stripe Checkout session for international payments.

POST /api/v1/payments/stripe/create-portal#

Create a Stripe Customer Portal session for subscription management.

POST /api/v1/payments/stripe/webhook#

Stripe webhook endpoint for payment event processing.


Subscription Analytics#

GET /api/v1/subscription-analytics/overview#

Get subscription analytics overview. Requires admin authentication.

GET /api/v1/subscription-analytics/conversions#

Get conversion funnel metrics.

GET /api/v1/subscription-analytics/churn#

Get churn analysis data.

GET /api/v1/subscription-analytics/revenue#

Get revenue analytics (MRR, ARR, ARPU).

GET /api/v1/subscription-analytics/cohorts#

Get cohort retention analysis.


Paywall#

GET /api/v1/paywall/check/:articleId#

Check if an article is behind the paywall for the current user.

Response (200):

json
{
  "articleId": "uuid",
  "isPaywalled": true,
  "freeArticlesRemaining": 3,
  "freeArticlesTotal": 5,
  "requiredTier": "premium"
}

POST /api/v1/paywall/meter#

Record an article read for metering purposes.

GET /api/v1/paywall/meter#

Get current meter status for the user.


Reading Mode#

GET /api/v1/reading-mode/settings#

Get reading mode settings. Requires authentication.

PUT /api/v1/reading-mode/settings#

Update reading mode settings. Requires authentication.

Request Body:

json
{
  "fontSize": "large",
  "fontFamily": "serif",
  "lineSpacing": 1.6,
  "theme": "sepia",
  "textAlign": "justify"
}

POST /api/v1/reading-mode/progress/:articleId#

Save reading progress for an article.

GET /api/v1/reading-mode/progress/:articleId#

Get reading progress for an article.


Compliance (NMC)#

Ghana National Media Commission compliance endpoints.

GET /api/v1/compliance/status#

Get current NMC compliance status.

POST /api/v1/compliance/check#

Run a compliance check against NMC guidelines.

GET /api/v1/compliance/reports#

List compliance reports.


Data Protection#

Ghana Data Protection Act compliance endpoints.

GET /api/v1/data-protection/consent#

Get user's consent status. Requires authentication.

PUT /api/v1/data-protection/consent#

Update consent preferences. Requires authentication.

POST /api/v1/data-protection/export#

Request a data export (GDPR/DPA right of access). Requires authentication.

DELETE /api/v1/data-protection/account#

Request account deletion (right to erasure). Requires authentication.


Election Coverage#

Ghana election coverage compliance, implementing Constitutional provisions (Articles 45-46, 55, 162-164) and NMC guidelines.

GET /api/v1/election-coverage/balance#

Get political coverage balance analysis.

Response (200):

json
{
  "electionId": "2024-general",
  "periodStart": "2024-09-01",
  "periodEnd": "2024-12-07",
  "totalArticles": 2847,
  "parties": [
    {
      "partyName": "NPP",
      "articleCount": 982,
      "averageSentiment": 0.12,
      "proportionOfTotal": 0.345
    }
  ],
  "balanceScore": 0.78,
  "balanceGrade": "B",
  "violations": []
}

GET /api/v1/election-coverage/compliance#

Get election coverage compliance status.

GET /api/v1/election-coverage/silence-period#

Check if the 24-hour campaign silence period is active.


Ads#

GET /api/v1/ads/placements#

Get available ad placements for the current page.

POST /api/v1/ads/impression#

Record an ad impression.

POST /api/v1/ads/click#

Record an ad click.

GET /api/v1/ads/campaigns#

List ad campaigns (advertiser access). Requires authentication.


Ad Networks#

GET /api/v1/ad-networks#

List configured ad network integrations.

GET /api/v1/ad-networks/:id/config#

Get ad network configuration.

PUT /api/v1/ad-networks/:id/config#

Update ad network configuration. Requires admin authentication.

GET /api/v1/ad-networks/mediation#

Get ad mediation waterfall configuration.


B2B API#

White-label API for business partners. Requires API key authentication.

GET /api/v1/b2b/feed#

Get a curated article feed for partner integration.

GET /api/v1/b2b/search#

Search articles via B2B API.

GET /api/v1/b2b/fact-check#

Access fact-checking data via B2B API.

GET /api/v1/b2b/entities#

Access entity data from the knowledge graph.

GET /api/v1/b2b/usage#

Get API usage statistics for the current API key.


API Keys#

B2B API key lifecycle management.

GET /api/v1/api-keys#

List API keys for the authenticated account.

POST /api/v1/api-keys#

Generate a new API key. Requires authentication.

DELETE /api/v1/api-keys/:id#

Revoke an API key. Requires authentication.

POST /api/v1/api-keys/:id/rotate#

Rotate an API key (generate new key, invalidate old). Requires authentication.

GET /api/v1/api-keys/:id/usage#

Get usage statistics for a specific API key.


Schemas#

Core Data Types#

ArticleListItem#

typescript
{
  id: string;            // UUID
  slug: string;          // URL-friendly slug
  headline: string;      // Article headline
  summary: string;       // Brief summary
  publishedAt: string;   // ISO 8601 datetime
  languageTag: string;   // Language code (en, tw, ee, ga, ha, dag)
  readTimeSeconds: number;
  source: SourceRef;
  sourceUrl?: string;
  featuredImage?: Image;
  categories: CategoryRef[];
  topics: TopicRef[];
}

ArticleDetail#

Extends ArticleListItem with:

typescript
{
  bodyHtml: string;          // Full HTML content
  bodyText: string;          // Plain text content
  authors: string[];         // Author names
  politicalBiasScore?: number; // -1.0 to 1.0
}

Source#

typescript
{
  id: string;
  name: string;
  domain: string;
  logoUrl?: string;
  politicalLean?: 'left' | 'center-left' | 'center' | 'center-right' | 'right';
  reliabilityScore?: number; // 0.0 to 1.0
}

Claim#

typescript
{
  id: string;
  text: string;
  verdict: 'true' | 'mostly_true' | 'half_true' | 'mostly_false' | 'false' | 'unverifiable';
  confidence: number; // 0.0 to 1.0
  createdAt: string;
  sources: string[];  // Evidence URLs
}

StoryCluster#

typescript
{
  id: string;
  title: string;
  summary?: string;
  status: 'active' | 'archived';
  articleCount: number;
  createdAt: string;
  updatedAt: string;
  canonicalArticle?: ArticleListItem;
}

VoiceProfile#

typescript
{
  id: string;
  slug: string;
  provider: 'elevenlabs';
  providerVoiceId: string;
  displayName: string;
  description?: string;
  languageTags: string[];
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

AvatarProfile#

typescript
{
  id: string;
  slug: string;
  provider: 'heygen';
  providerAvatarId: string;
  displayName: string;
  description?: string;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

Environment Variables#

Server Configuration#

Variable Default Description
PORT 3001 HTTP server port
HOST 0.0.0.0 Bind address
NODE_ENV development Environment (development / production)
LOG_LEVEL info Logging level

CORS#

Variable Default Description
CORS_ENABLED true Enable CORS middleware
CORS_ORIGINS * Allowed origins (comma-separated)

Rate Limiting#

Variable Default Description
RATE_LIMIT_ENABLED true Enable rate limiting
RATE_LIMIT_MAX 120 Max requests per window
RATE_LIMIT_WINDOW_SECONDS 60 Window duration in seconds
RATE_LIMIT_PREFIX veritas:api:rate-limit Redis key prefix

API Key Authentication#

Variable Default Description
API_KEY_AUTH_ENABLED false Enable API key authentication
API_KEYS -- Valid API keys (comma-separated)
API_KEY_HEADER x-api-key Header name for API key

Database (PostgreSQL)#

Variable Default Description
DATABASE_URL -- PostgreSQL connection string
VERITAS_DATABASE_URL -- Override for Veritas-specific DB
DATABASE_POOL_MAX 20 Maximum pool connections
DATABASE_IDLE_TIMEOUT_MS 30000 Idle connection timeout
DATABASE_CONNECTION_TIMEOUT_MS 5000 Connection attempt timeout

Redis#

Variable Default Description
REDIS_URL -- Redis connection URL
VERITAS_REDIS_URL -- Override for Veritas Redis
REDIS_MAX_RETRIES 3 Max reconnection retries
REDIS_CONNECT_TIMEOUT_MS 10000 Connection timeout

Elasticsearch#

Variable Default Description
ELASTICSEARCH_URL -- Elasticsearch URL
ELASTICSEARCH_USERNAME -- Auth username
ELASTICSEARCH_PASSWORD -- Auth password
ELASTICSEARCH_MAX_RETRIES 3 Max retries
ELASTICSEARCH_REQUEST_TIMEOUT_MS 30000 Request timeout
ELASTICSEARCH_ARTICLES_INDEX veritas-articles Article search index

Security#

Variable Default Description
VERITAS_ACCESS_TOKEN_SECRET -- JWT signing secret (HMAC-SHA256)
NEXTAUTH_SECRET -- Fallback JWT secret
TIPS_ENCRYPTION_KEY -- AES-256-GCM key for tip encryption

OpenAPI#

Variable Default Description
OPENAPI_ENABLED true Enable OpenAPI docs endpoint

Last Updated: January 2026

Part of the Veritas domain API documentation