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#
- Authentication
- Rate Limiting
- Error Handling
- Pagination
- Endpoints
- Health
- Auth
- Articles
- Stories
- Claims & Fact-Checking
- Sources
- Bias Analysis
- Taxonomy
- Preferences
- Tips
- Writing Assistant
- Voice Profiles
- Avatar Profiles
- Subscriptions
- Payments - MTN MoMo
- Payments - Vodafone Cash
- Payments - AirtelTigo Money
- Payments - Stripe
- Subscription Analytics
- Paywall
- Reading Mode
- Compliance (NMC)
- Data Protection
- Election Coverage
- Ads
- Ad Networks
- B2B API
- API Keys
- Schemas
- 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:
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:
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/detailedGET /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:
{
"error": "Too Many Requests",
"retryAfterSeconds": 42
}
Error Handling#
All errors return consistent JSON responses.
Error Response Formats#
Standard Error:
{
"error": "Human-readable error message"
}
Validation Error (400):
{
"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):
{
"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:
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:
{
"items": [...],
"nextCursor": "eyJpZCI6Ijk5OSIsInB1Ymxpc2hlZEF0IjoiMjAyNi0wMS0yNSJ9"
}
When nextCursor is null, there are no more items.
Offset-Based Pagination (Search)#
Search endpoints use offset-based pagination:
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
int | 1 | Page number |
pageSize |
int | 20 | Items per page |
Response:
{
"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.
{ "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):
{
"status": "ok",
"service": "veritas-api",
"time": "2026-01-26T12:00:00.000Z",
"checks": {
"database": "ok",
"redis": "ok",
"elasticsearch": "ok"
}
}
Response (degraded - 503):
{
"status": "degraded",
"checks": {
"database": "ok",
"redis": "error",
"elasticsearch": "ok"
}
}
GET /health/detailed#
Full health report with latency metrics for each dependency.
{
"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:
{
"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):
{
"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:
{
"email": "user@example.com",
"password": "securepassword123"
}
Response (200):
{
"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):
{
"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):
{
"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):
{
"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):
{
"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):
{
"suggestions": ["Ghana election", "Ghana economy", "Ghana football"]
}
GET /api/v1/articles/:id#
Get a single article by UUID.
Response (200):
{
"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):
{
"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):
{
"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):
{
"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:
{
"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):
{
"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):
{
"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):
{
"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:
{
"text": "The government's economic policy has been remarkably successful..."
}
| Field | Type | Required | Constraints |
|---|---|---|---|
text |
string | Yes | Max 20,000 chars |
Response (200):
{
"score": 0.35,
"band": "positive",
"confidence": 0.82
}
score: -1.0 (opposition-leaning) to 1.0 (government-leaning)band:negative,neutral,positiveconfidence: 0.0 to 1.0
Taxonomy#
GET /api/v1/taxonomy/categories#
List all content categories with their topics.
Response (200):
{
"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):
{
"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:
{
"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):
{
"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:
{
"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):
{
"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:
{
"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:
{
"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):
{
"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:
{
"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):
{
"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:
{
"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):
{
"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#
{
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:
{
bodyHtml: string; // Full HTML content
bodyText: string; // Plain text content
authors: string[]; // Author names
politicalBiasScore?: number; // -1.0 to 1.0
}
Source#
{
id: string;
name: string;
domain: string;
logoUrl?: string;
politicalLean?: 'left' | 'center-left' | 'center' | 'center-right' | 'right';
reliabilityScore?: number; // 0.0 to 1.0
}
Claim#
{
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#
{
id: string;
title: string;
summary?: string;
status: 'active' | 'archived';
articleCount: number;
createdAt: string;
updatedAt: string;
canonicalArticle?: ArticleListItem;
}
VoiceProfile#
{
id: string;
slug: string;
provider: 'elevenlabs';
providerVoiceId: string;
displayName: string;
description?: string;
languageTags: string[];
isActive: boolean;
createdAt: string;
updatedAt: string;
}
AvatarProfile#
{
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