Eve library

Veritas API Reference

Guide

Revision 1

On this page

Complete endpoint reference for the Veritas news intelligence platform API.

Base URL: /api/v1 Framework: Hono Validation: Zod Database: PostgreSQL (via pg connection pool) Search: Elasticsearch Cache / Rate Limiting: Redis


Table of Contents#


Authentication#

The API supports two authentication mechanisms.

JWT Bearer Tokens (User Authentication)#

Used for consumer-facing endpoints that require a logged-in user (preferences, saved articles, etc.).

text
Authorization: Bearer <access_token>

Tokens are issued by POST /auth/register and POST /auth/login. They are JWTs signed with the configured accessTokenSecret.

API Key Authentication (Service Authentication)#

Used for machine-to-machine access. The middleware validates a static API key sent in the X-API-Key header.

text
X-API-Key: <api_key>

The middleware uses timing-safe string comparison to prevent timing attacks. Health check (/health*) and documentation (/docs, /openapi.json) endpoints are exempt.

B2B Managed API Keys#

The B2B API uses a separate managed key system with scoped permissions and tier-based rate limits. Keys prefixed with sk_test_ automatically activate sandbox mode.


Rate Limiting#

Sliding-window rate limiting is applied to all /api/* routes when Redis is available. Falls back to an in-memory store when Redis is unavailable.

Algorithm: Redis sorted sets with timestamps as scores.

Response Headers:

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

Rate-limited response (HTTP 429):

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

Client identification is resolved from X-Forwarded-For, then X-Real-IP, falling back to "unknown".


Error Responses#

All errors follow a consistent JSON structure.

Validation Error (400)#

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

Unauthorized (401)#

json
{ "error": "Unauthorized" }

Forbidden (403)#

json
{ "error": "Forbidden" }

Not Found (404)#

json
{ "error": "Article not found" }

Conflict (409)#

json
{ "error": "Email already registered" }

Internal Server Error (500)#

json
{ "error": "Internal Server Error" }

In development mode, message and stack fields are included.

Service Unavailable (503)#

json
{ "error": "Database unavailable" }

Pagination#

Cursor-Based (Articles, Claims, Stories)#

Used for feeds where new content is continuously inserted. Cursors are base64url-encoded JSON objects containing a timestamp and UUID.

Request:

text
GET /api/v1/articles?limit=20&cursor=eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDEtMTVUMTI6MDA6MDBaIiwiaWQiOiIuLi4ifQ

Response:

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

nextCursor is null when there are no more pages.

Offset-Based (Search, B2B Endpoints)#

Used for search results and some B2B endpoints.

Request:

text
GET /api/v1/articles/search?q=election&page=2&pageSize=20

Response:

json
{
  "items": [ ... ],
  "total": 142,
  "page": 2,
  "pageSize": 20,
  "totalPages": 8
}

Health Checks#

Health check routes are registered at the root level (not under /api/v1).

GET /health#

Simple health check for load balancers.

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

GET /healthz#

Kubernetes liveness probe. Returns { "status": "ok" }.

GET /readyz#

Kubernetes readiness probe. Checks database, Redis, and Elasticsearch connectivity. Returns HTTP 503 when all dependencies are down, HTTP 200 otherwise (including degraded state).

json
{
  "status": "degraded",
  "service": "veritas-api",
  "time": "2026-02-14T12:00:00.000Z",
  "checks": {
    "database": { "status": "ok", "latencyMs": 2 },
    "redis": { "status": "error", "error": "Connection refused" },
    "elasticsearch": { "status": "ok", "latencyMs": 15 }
  }
}

Status values: ok, degraded (some dependencies down), unhealthy (all dependencies down).

GET /health/detailed#

Same as /readyz but always returns HTTP 200. Intended for monitoring dashboards.


Articles#

GET /api/v1/articles#

List articles with cursor-based pagination.

Query Parameters:

Param Type Default Description
limit integer (1-50) 20 Number of articles per page
cursor string -- Cursor from a previous response
match any | all any How to combine filters (OR vs AND)
category string | string[] -- Filter by category slug(s), max 10
topic string | string[] -- Filter by topic slug(s), max 10
lang string | string[] -- Filter by language tag(s), max 5
source string | string[] -- Filter by source UUID(s), max 10

Response:

json
{
  "items": [
    {
      "id": "uuid",
      "slug": "article-slug",
      "headline": "Article Headline",
      "summary": "Article summary text...",
      "publishedAt": "2026-02-14T12:00:00.000Z",
      "languageTag": "en",
      "readTimeSeconds": 180,
      "source": {
        "name": "Daily Graphic",
        "domain": "graphic.com.gh",
        "url": "https://graphic.com.gh"
      },
      "sourceUrl": "https://graphic.com.gh/article/...",
      "featuredImage": {
        "url": "https://cdn.example.com/image.jpg",
        "alt": "Description",
        "width": 1200,
        "height": 630
      },
      "categories": [],
      "topics": []
    }
  ],
  "nextCursor": "base64url-encoded-cursor-or-null"
}

GET /api/v1/articles/trending#

Get trending articles by view count within a time window.

Query Parameters:

Param Type Default Description
limit integer (1-50) 10 Number of articles
hours integer (1-720) 72 Lookback window in hours

GET /api/v1/articles/search#

Full-text search powered by Elasticsearch. Uses multi_match across headline (boost 3x), summary (boost 2x), and body_text with fuzzy matching.

Query Parameters:

Param Type Default Description
q string "" Search query
page integer (1-1000) 1 Page number
pageSize integer (1-50) 20 Results per page
from string (ISO date) -- Published after this date
to string (ISO date) -- Published before this date
category string | string[] -- Filter by category slug(s)
topic string | string[] -- Filter by topic slug(s)
lang string | string[] -- Filter by language tag(s)
source string | string[] -- Filter by source UUID(s)
bias string | string[] -- Filter by bias band(s)

Response: Offset-based pagination (see Pagination).

GET /api/v1/articles/search/suggest#

Autocomplete suggestions using match_phrase_prefix with fuzzy fallback.

Query Parameters:

Param Type Default Description
q string "" Partial search query
limit integer (1-20) 10 Maximum suggestions

Response:

json
{
  "suggestions": [{ "id": "uuid", "headline": "Matching headline..." }]
}

GET /api/v1/articles/:id#

Get a single article by UUID. Returns full content including bodyHtml, bodyText, politicalBiasScore, and authors.

Response:

json
{
  "id": "uuid",
  "slug": "article-slug",
  "headline": "Article Headline",
  "summary": "Summary...",
  "bodyHtml": "<p>Full HTML...</p>",
  "bodyText": "Full plain text...",
  "publishedAt": "2026-02-14T12:00:00.000Z",
  "languageTag": "en",
  "readTimeSeconds": 180,
  "source": { "name": "...", "domain": "...", "url": "..." },
  "sourceUrl": "https://...",
  "featuredImage": { "url": "...", "alt": "...", "width": 1200, "height": 630 },
  "politicalBiasScore": 0.15,
  "authors": ["Author Name"],
  "categories": [],
  "topics": []
}

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

Get articles related by shared categories and topics, ranked by relevance score.

Query Parameters:

Param Type Default Description
limit integer (1-50) 10 Maximum related articles

Story Clusters#

Story clusters group related articles covering the same news story.

GET /api/v1/stories#

List story clusters with cursor-based pagination.

Query Parameters:

Param Type Default Description
limit integer (1-50) 20 Number of clusters per page
cursor string -- Cursor from previous response
status active | archived | any active Filter by cluster status
method string (1-64 chars) embedding_v1 Filter by clustering method

Response:

json
{
  "items": [
    {
      "id": "uuid",
      "title": "Cluster Title",
      "summary": "Cluster summary...",
      "status": "active",
      "method": "embedding_v1",
      "score": 0.85,
      "createdAt": "2026-02-14T12:00:00.000Z",
      "updatedAt": "2026-02-14T12:00:00.000Z",
      "archivedAt": null,
      "articleCount": 12,
      "canonicalArticle": {
        "id": "uuid",
        "headline": "Canonical article headline",
        "summary": "Summary...",
        "publishedAt": "2026-02-14T12:00:00.000Z"
      }
    }
  ],
  "nextCursor": "base64url-encoded-cursor-or-null"
}

GET /api/v1/stories/:id#

Get a single story cluster by UUID.

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

List articles belonging to a story cluster.

Query Parameters:

Param Type Default Description
limit integer (1-200) 50 Maximum articles

Claims and Fact-Checking#

GET /api/v1/claims#

List claims with cursor-based pagination.

Query Parameters:

Param Type Default Description
limit integer (1-50) 20 Number of claims per page
cursor string -- Cursor from previous response

Response:

json
{
  "items": [
    {
      "id": "uuid",
      "text": "Original claim text",
      "normalizedText": "normalized claim text",
      "verdict": "true",
      "confidence": 0.78,
      "createdAt": "2026-02-14T12:00:00.000Z",
      "updatedAt": "2026-02-14T12:00:00.000Z"
    }
  ],
  "nextCursor": "base64url-encoded-cursor-or-null"
}

GET /api/v1/claims/:id#

Get a single claim with associated articles.

Response:

json
{
  "id": "uuid",
  "text": "Original claim text",
  "normalizedText": "normalized claim text",
  "verdict": "true",
  "confidence": 0.78,
  "evidenceSummary": "Evidence review summary...",
  "createdAt": "2026-02-14T12:00:00.000Z",
  "updatedAt": "2026-02-14T12:00:00.000Z",
  "articles": [
    {
      "id": "uuid",
      "headline": "Article mentioning this claim",
      "publishedAt": "2026-02-14T12:00:00.000Z"
    }
  ]
}

POST /api/v1/fact-check#

Fact-check a claim using web search evidence analysis. Results are cached for 7 days unless refresh is set.

Request Body:

json
{
  "claim": "The president announced free education",
  "refresh": false,
  "maxResults": 10,
  "country": "GH",
  "language": "en",
  "freshness": "month"
}
Field Type Default Description
claim string (1-500 chars) required The claim to verify
refresh boolean false Skip cache and re-check
maxResults integer (1-20) 10 Max evidence items
country string (2 chars) "GH" Country code for search
language string (2-12 chars) "en" Language code
freshness day | week | month | year | any "month" Evidence recency filter

Response:

json
{
  "claim": "The president announced free education",
  "verdict": "true",
  "confidence": 0.72,
  "summary": "Evidence review found 4 supporting, 1 refuting, and 2 neutral sources.",
  "evidence": [
    {
      "title": "Source article title",
      "snippet": "Relevant excerpt...",
      "url": "https://source.example.com/article",
      "source": "Source Name",
      "publishedAt": "2026-02-10T00:00:00.000Z",
      "stance": "supporting",
      "relevance": 0.85,
      "score": 0.65
    }
  ],
  "cached": false
}

Verdict values: true, false, mixed, unverifiable. Evidence stance values: supporting, refuting, neutral.

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

Get articles mentioning a specific claim (max 25).


Political Bias#

POST /api/v1/bias/score#

Score arbitrary text for political bias using keyword-based analysis.

Request Body:

json
{
  "text": "The progressive reform includes welfare improvements and social justice..."
}
Field Type Description
text string (1-20000 chars) Text to analyze

Response:

json
{
  "score": -0.45,
  "band": "negative",
  "confidence": 0.62
}

Score range: -1 (left-leaning) to +1 (right-leaning). Band values: negative (< -0.2), neutral (-0.2 to 0.2), positive (> 0.2).

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

Get the stored political bias score for an article.

POST /api/v1/articles/:id/bias#

Analyze an article's body_text for political bias and persist the score.


Sources#

GET /api/v1/sources#

List all news sources.

Query Parameters:

Param Type Description
active boolean Filter by active/inactive status

Response:

json
{
  "items": [
    {
      "id": "uuid",
      "name": "Daily Graphic",
      "domain": "graphic.com.gh",
      "homepageUrl": "https://graphic.com.gh",
      "logoUrl": "https://cdn.example.com/logo.png",
      "politicalLean": "center",
      "reliabilityScore": 0.88,
      "isActive": true,
      "articleCount": 5432
    }
  ]
}

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

Get all sources plotted on the NPP/NDC political bias spectrum.

Response:

json
{
  "items": [
    {
      "sourceId": "uuid",
      "sourceName": "Source Name",
      "score": -1.5,
      "band": -2,
      "bandLabel": "NDC-leaning",
      "bandColor": "#ef4444",
      "confidence": 0.75,
      "ownershipName": "Media Group Name"
    }
  ],
  "scale": {
    "min": -3,
    "max": 3,
    "ndcLabel": "NDC-aligned",
    "nppLabel": "NPP-aligned",
    "centerLabel": "Center"
  },
  "count": 45
}

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

Get media groups with their affiliated outlets.

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

Get alerts for cross-ownership relationships between media outlets.

GET /api/v1/sources/:id#

Get a single source by UUID with full details including description, transparencyScore, createdAt, and updatedAt.

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

Get transparency metrics: correction count, correction frequency, and disclosure flags (methodology, ownership, funding).

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

Get correction history for a source.

Query Parameters:

Param Type Default Description
limit integer (1-100) 25 Maximum corrections

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

Get the NPP/NDC political bias profile for a source, including scale labels and ownership context.

Response:

json
{
  "sourceId": "uuid",
  "sourceName": "Source Name",
  "canonicalDomain": "source.com.gh",
  "politicalScore": -1.2,
  "band": -1,
  "bandLabel": "Slightly NDC-leaning",
  "bandColor": "#f97316",
  "confidence": 0.68,
  "methodology": "lexicon_v2",
  "lastAssessedAt": "2026-01-15T00:00:00.000Z",
  "ownershipName": "Group Name",
  "ownershipType": "private",
  "mediaGroup": "Media Group Name",
  "scale": {
    "min": -3,
    "max": 3,
    "labels": {
      "-3": "Strongly NDC-aligned",
      "-2": "NDC-leaning",
      "-1": "Slightly NDC-leaning",
      "0": "Center / Balanced",
      "1": "Slightly NPP-leaning",
      "2": "NPP-leaning",
      "3": "Strongly NPP-aligned"
    }
  }
}

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

Get the ownership profile for a source.

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

Get the regional coverage profile for a source.

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

Compare a source's regional coverage against the national average.

Response:

json
{
  "items": [
    {
      "region": "Greater Accra",
      "sourcePercent": 45.2,
      "nationalAverage": 30.1,
      "status": "over_represented"
    }
  ],
  "summary": {
    "totalRegions": 16,
    "blindSpots": 2,
    "overRepresented": 3,
    "underRepresented": 5,
    "balanced": 6
  }
}

Status values: balanced, over_represented, under_represented, blind_spot.


Taxonomy#

GET /api/v1/categories#

List all categories with their grouped topics.

Response:

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

GET /api/v1/topics#

List all topics, optionally filtered by category.

Query Parameters:

Param Type Description
category string Filter by category slug

Tips#

POST /api/v1/tips#

Submit an anonymous tip for investigative journalism. Tips are encrypted at rest when tipsEncryptionKey is configured (AES-256-GCM).

Request Body:

json
{
  "message": "I have evidence of corruption in the ministry...",
  "isAnonymous": true,
  "evidenceUrls": ["https://example.com/document.pdf"],
  "contactEmail": "whistleblower@example.com",
  "contactPhone": "+233201234567"
}
Field Type Default Description
message string (20-20000) required Tip content
isAnonymous boolean true Whether the tip is anonymous
evidenceUrls string[] (max 10) [] Supporting evidence URLs (HTTP/S)
contactEmail string -- Optional contact email
contactPhone string -- Optional contact phone

Response (201):

json
{
  "id": "TIP-M1AB2C3D-E4F5G6H7",
  "submittedAt": "2026-02-14T12:00:00.000Z",
  "message": "Thank you for your tip. Our editorial team will review it."
}

Preferences#

All preferences endpoints require a Bearer token (Authorization: Bearer <token>).

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

Get the current user's home feed preferences.

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

Fully replace the user's home feed preferences.

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

Partially update the user's home feed preferences (merge semantics).


Voice Profiles#

CRUD for text-to-speech voice profiles.

GET /api/v1/voice-profiles#

List all active voice profiles.

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

Get a single voice profile by UUID.

POST /api/v1/voice-profiles#

Create a new voice profile.

Request Body:

json
{
  "slug": "accra-female-1",
  "provider": "elevenlabs",
  "providerVoiceId": "abc123",
  "displayName": "Ama - Accra Female",
  "description": "Clear female voice with Ghanaian English accent",
  "languageTags": ["en", "tw"],
  "defaultSettings": { "stability": 0.7, "similarity_boost": 0.8 },
  "defaultFormat": "mp3_44100_128"
}

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

Update a voice profile.

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

Soft-delete a voice profile (sets isActive to false).


Avatar Profiles#

CRUD for AI avatar profiles used in video rendering.

GET /api/v1/avatar-profiles#

List all active avatar profiles.

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

Get a single avatar profile by UUID.

POST /api/v1/avatar-profiles#

Create a new avatar profile.

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

Update an avatar profile.

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

Soft-delete an avatar profile (sets isActive to false).


Writing Assistant#

POST /api/v1/writing-assistant#

AI-powered writing assistance with deterministic fallback transformations.

Request Body:

json
{
  "mode": "rewrite",
  "text": "The text to transform...",
  "instructions": "Use active voice",
  "tone": "formal",
  "languageTag": "en",
  "provider": "anthropic",
  "model": "claude-3-sonnet",
  "maxTokens": 800,
  "temperature": 0.7
}
Field Type Default Description
mode rewrite | shorten | expand | bulletize required Transformation mode
text string (1-20000) required Input text
instructions string (max 800) -- Additional instructions
tone string (max 200) -- Desired tone (formal, friendly)
languageTag string (max 20) -- Output language tag
provider anthropic | openai anthropic AI provider
model string (max 80) auto Model name
maxTokens integer (120-1800) -- Max output tokens
temperature number (0-1) -- Sampling temperature

Response:

json
{
  "result": "The transformed text...",
  "provider": "anthropic",
  "model": "claude-3-sonnet",
  "tokensUsed": 200,
  "mode": "rewrite"
}

Compliance (NMC)#

National Media Commission (NMC) compliance endpoints for Ghana media regulation.

GET /api/v1/compliance/nmc/guidelines#

Get NMC guidelines, violation categories, remedies, and complaint stages.

POST /api/v1/compliance/nmc/check#

Check content against NMC guidelines.

POST /api/v1/compliance/nmc/check/batch#

Batch-check multiple content items.

GET /api/v1/compliance/nmc/complaints#

List NMC complaints with pagination and filtering.

POST /api/v1/compliance/nmc/complaints#

File a new NMC complaint.

GET /api/v1/compliance/nmc/complaints/:id#

Get a single complaint by UUID.

PATCH /api/v1/compliance/nmc/complaints/:id#

Update complaint status (stage transitions).

GET /api/v1/compliance/nmc/sources/:id/score#

Get compliance score for a source.

GET /api/v1/compliance/nmc/statistics#

Get compliance statistics.

GET /api/v1/compliance/gja/code-of-ethics#

Get the Ghana Journalists Association Code of Ethics.


Data Protection (DPA)#

Ghana Data Protection Act 2012 (Act 843) compliance endpoints.

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

Get DPA principles, data subject rights, and processing purposes.

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

Get user consents (requires Bearer auth).

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

Grant or withdraw consent for a processing purpose.

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

Submit a data subject request (access, correction, erasure, etc.).

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

List user's data subject requests.

GET /api/v1/data-protection/requests/:id#

Get status of a specific request.

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

Request a data export.

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

Request account deletion.

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

Get the user's overall data protection status.


Election Coverage#

Ghana election coverage compliance endpoints.

GET /api/v1/election-coverage/constitutional-provisions#

Get constitutional provisions governing election coverage.

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

Get election coverage guidelines.

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

Get election offences defined in law.

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

Get registered political parties.

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

Get the current election phase.

POST /api/v1/election-coverage/check#

Check content for election coverage compliance.

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

Get the active election.

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

List election coverage violations.

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

Get coverage balance across parties.


Payments (MTN MoMo)#

MTN Mobile Money payment integration for Ghana.

POST /api/v1/payments/mtn/request#

Initiate a payment request (collection).

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

Check payment status.

POST /api/v1/payments/mtn/preapproval#

Request pre-approval for recurring payments.

POST /api/v1/payments/mtn/refund#

Process a refund.

POST /api/v1/payments/mtn/validate#

Validate an MTN phone number.

GET /api/v1/payments/mtn/balance#

Check the MTN MoMo account balance.

POST /api/v1/payments/mtn/callback#

Webhook callback from MTN.

GET /api/v1/payments/mtn/transactions#

List payment transactions.

GET /api/v1/payments/mtn/subscriptions#

List payment subscriptions.


Payments (Vodafone Cash)#

Vodafone Cash payment integration for Ghana.

Routes follow the same pattern as MTN MoMo under /api/v1/payments/vodafone/.


Payments (AirtelTigo Money)#

AirtelTigo Money payment integration for Ghana.

Routes follow the same pattern as MTN MoMo under /api/v1/payments/airteltigo/.


Payments (Stripe)#

Stripe payment integration for international payments.

Routes follow standard Stripe integration patterns under /api/v1/payments/stripe/.


Subscriptions#

GET /api/v1/subscriptions/plans#

List available subscription plans.

POST /api/v1/subscriptions/subscribe#

Subscribe to a plan.

POST /api/v1/subscriptions/upgrade#

Upgrade to a higher-tier plan.

POST /api/v1/subscriptions/downgrade#

Downgrade to a lower-tier plan.

POST /api/v1/subscriptions/cancel#

Cancel a subscription.

POST /api/v1/subscriptions/resume#

Resume a cancelled subscription.

POST /api/v1/subscriptions/pause#

Pause a subscription.

GET /api/v1/subscriptions/usage#

Get subscription usage data.

GET /api/v1/subscriptions/access#

Check subscription access for a feature.

POST /api/v1/subscriptions/family#

Manage family membership.

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

Verify student status for student plan eligibility.


Paywall#

Article metering and access control.

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

Check if the user has access to a specific article.

POST /api/v1/paywall/read#

Record a metered read event.

GET /api/v1/paywall/events#

Get metering events.

GET /api/v1/paywall/status#

Get current metering status (reads remaining, etc.).

GET /api/v1/paywall/config#

Get paywall configuration.

GET /api/v1/paywall/premium#

List premium articles.

GET /api/v1/paywall/analytics#

Get paywall analytics.


Subscription Analytics#

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

Get conversion funnel data.

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

Get churn metrics.

GET /api/v1/subscription-analytics/at-risk#

Get at-risk subscribers.

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

Get revenue analytics.

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

Get monthly recurring revenue.

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

Get historical snapshots.

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

Get lifetime value metrics.

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

Get cohort analysis data.

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

Get plan transition data.


Ads#

GET /api/v1/ads/config#

Get ad serving configuration.

GET /api/v1/ads/placements#

List ad placements.

POST /api/v1/ads/impressions#

Record ad impressions.

POST /api/v1/ads/clicks#

Record ad clicks.

GET /api/v1/ads/units#

List ad units.

GET /api/v1/ads/campaigns#

List ad campaigns.

GET /api/v1/ads/creatives#

List ad creatives.

GET /api/v1/ads/analytics#

Get ad analytics.

GET /api/v1/ads/eligibility#

Check user eligibility for ad-free experience.


Ad Networks#

Routes under /api/v1/ad-networks/#

Ad network management for third-party ad integration.


Reading Mode#

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

Get reading mode status.

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

Get reading mode settings.

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

Update reading mode settings.

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

Get typography settings.

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

Get theme/color settings.

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

Get reading progress for an article.

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

Update reading progress.

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

Get reading history.

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

Get reading statistics.

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

Get estimated reading time.


API Keys (B2B)#

Managed API key lifecycle for B2B partners.

POST /api/v1/api-keys#

Create a new API key.

Request Body:

json
{
  "name": "Partner Integration",
  "scopes": ["articles:read", "search:read", "claims:read"],
  "tier": "standard",
  "rateLimit": 1000,
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

GET /api/v1/api-keys#

List all API keys for the authenticated user.

GET /api/v1/api-keys/:keyId#

Get a single API key by ID.

PATCH /api/v1/api-keys/:keyId#

Update an API key (name, scopes, rate limit, active status).

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

Revoke an API key.

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

Rotate an API key (generates a new secret, old key is revoked).

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

Get usage statistics for an API key.

GET /api/v1/api-keys/:keyId/billing#

Get billing information for an API key.

GET /api/v1/api-keys/usage/summary#

Get aggregated usage summary across all keys.

POST /api/v1/api-keys/validate#

Validate an API key and return its scopes.

POST /api/v1/api-keys/rate-limit/check#

Check rate limit status for an API key.


Sandbox#

The sandbox environment is activated when a test API key (sk_test_*) is detected. Sandbox routes are mounted at /api/v1/sandbox.

GET /api/v1/sandbox/status#

Get current sandbox status and configuration.

PATCH /api/v1/sandbox/config#

Update sandbox configuration (latency simulation, error rates, etc.).

POST /api/v1/sandbox/reset#

Reset the sandbox to its default state.

DELETE /api/v1/sandbox#

Delete the sandbox environment.

POST /api/v1/sandbox/scenario#

Load a predefined test scenario.

DELETE /api/v1/sandbox/scenario#

Clear the current scenario.

GET /api/v1/sandbox/history#

Get sandbox operation history.

GET /api/v1/sandbox/stats#

Get sandbox usage statistics.

The sandbox also mirrors key B2B API endpoints at /api/v1/sandbox/b2b/* (feed, search, entities, claims, sources, media, alerts, monitoring) returning deterministic mock data.


B2B Partner API#

Partner integration API mounted at /api/v1/b2b. Requires a managed API key with appropriate scopes. For full B2B API documentation, see the B2B API docs.

Authentication#

B2B endpoints validate the X-API-Key header against managed API keys stored in the database. Each key has:

  • Scopes: articles:read, search:read, claims:read, claims:search, entities:read, entities:write, analytics:read
  • Tiers: free, standard, premium, enterprise (each with different rate limits)

Feed API#

Method Path Scope Description
GET /b2b/feed articles:read List articles
GET /b2b/feed/trending articles:read Get trending articles
GET /b2b/feed/:id articles:read Get article by ID

Search API#

Method Path Scope Description
POST /b2b/search search:read Search articles
GET /b2b/search/suggest search:read Autocomplete suggestions

Fact-Check API#

Method Path Scope Description
GET /b2b/fact-check/claims claims:read List claims
GET /b2b/fact-check/claims/:id claims:read Get claim by ID
POST /b2b/fact-check/search claims:search Search claims

Entity API#

Method Path Scope Description
GET /b2b/entities/search entities:read Search entities
GET /b2b/entities/:id entities:read Get entity by ID
POST /b2b/entities entities:write Create entity
PATCH /b2b/entities/:id entities:write Update entity
GET /b2b/entities/:id/articles entities:read Entity's articles
GET /b2b/entities/:id/relationships entities:read Entity's relationships
POST /b2b/entities/mentions entities:write Record entity mentions
POST /b2b/entities/relationships entities:write Create entity relationships

Media API#

Method Path Scope Description
GET /b2b/media articles:read List media assets
GET /b2b/media/:id articles:read Get media asset by ID
GET /b2b/media/article/:articleId articles:read Article's media assets
POST /b2b/media/search search:read Search media

Alerts API#

Method Path Scope Description
GET /b2b/alerts articles:read List alerts
POST /b2b/alerts articles:read Create alert
GET /b2b/alerts/:id articles:read Get alert by ID
PATCH /b2b/alerts/:id articles:read Update alert
DELETE /b2b/alerts/:id articles:read Delete alert
GET /b2b/alerts/notifications articles:read Get alert notifications
GET /b2b/monitoring/stats analytics:read Get monitoring stats

NLP Service#

The NLP service runs as a separate Hono server (not under /api/v1). It provides natural language processing capabilities.

Sentiment Analysis#

Method Path Description
POST /sentiment Analyze text sentiment
POST /sentiment/batch Batch sentiment analysis

Topic Classification#

Method Path Description
POST /topics/classify Classify text topics
POST /topics/classify/batch Batch topic classification

Keyword Extraction#

Method Path Description
POST /keywords/extract Extract keywords
POST /keywords/extract/batch Batch keyword extraction

Summarization#

Method Path Description
POST /summarize/extractive Extractive summarization
POST /summarize/abstractive Abstractive summarization

Claim Extraction#

Method Path Description
POST /claims/extract Extract claims from text
POST /claims/extract/batch Batch claim extraction

Language Processing#

Method Path Description
POST /language/detect Detect language
POST /language/code-switch Detect code-switching in text
POST /language/normalize Normalize text (diacritics, etc.)

Embeddings#

Method Path Description
POST /embeddings/embed Generate text embedding
POST /embeddings/embed/batch Batch embedding

Similarity#

Method Path Description
POST /similarity/compare Compare text similarity
Method Path Description
POST /evidence/search Search for evidence supporting/refuting a claim

Ghana NLP#

Method Path Description
POST /ghana/translate Translate between Ghanaian languages
POST /ghana/tts Text-to-speech for Ghanaian languages
POST /ghana/ner Named entity recognition for Ghanaian text

OpenAPI / Swagger#

When enabled in the server configuration, interactive API documentation is available at:

  • Swagger UI: GET /docs
  • OpenAPI JSON: GET /openapi.json

CORS#

When CORS is enabled, the following configuration applies:

  • Allowed Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
  • Allowed Headers: Content-Type, Authorization, X-API-Key, X-Request-ID, X-Sandbox-Mode, X-Sandbox-Scenario, X-Sandbox-Seed, X-Sandbox-Latency-Ms, X-Sandbox-Force-Error, X-Sandbox-Error-Rate
  • Exposed Headers: X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Sandbox-Mode
  • Max Age: 600 seconds
  • Credentials: Allowed

Middleware Stack#

Requests pass through middleware in this order:

  1. Logger -- Request/response logging (when enabled)
  2. Timing -- Server-Timing header for performance monitoring
  3. Secure Headers -- Security response headers (CSP, HSTS, etc.)
  4. CORS -- Cross-origin resource sharing (when enabled)
  5. Rate Limiting -- Sliding window rate limiter on /api/* routes
  6. Sandbox Detection -- Detects sk_test_* API keys and sets up sandbox context
  7. API Key Auth -- Validates X-API-Key header on /api/* routes
  8. Error Handler -- Global error handler converting exceptions to JSON responses