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
- Rate Limiting
- Error Responses
- Pagination
- Health Checks
- Articles
- Story Clusters
- Claims and Fact-Checking
- Political Bias
- Sources
- Taxonomy
- Tips
- Preferences
- Voice Profiles
- Avatar Profiles
- Writing Assistant
- Compliance (NMC)
- Data Protection (DPA)
- Election Coverage
- Payments (MTN MoMo)
- Payments (Vodafone Cash)
- Payments (AirtelTigo Money)
- Payments (Stripe)
- Subscriptions
- Paywall
- Subscription Analytics
- Ads
- Ad Networks
- Reading Mode
- API Keys (B2B)
- Sandbox
- B2B Partner API
- NLP Service
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.).
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.
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):
{
"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)#
{
"error": "Validation Error",
"issues": [
{ "path": "email", "message": "Invalid email" },
{
"path": "password",
"message": "String must contain at least 8 character(s)"
}
]
}
Unauthorized (401)#
{ "error": "Unauthorized" }
Forbidden (403)#
{ "error": "Forbidden" }
Not Found (404)#
{ "error": "Article not found" }
Conflict (409)#
{ "error": "Email already registered" }
Internal Server Error (500)#
{ "error": "Internal Server Error" }
In development mode, message and stack fields are included.
Service Unavailable (503)#
{ "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:
GET /api/v1/articles?limit=20&cursor=eyJwdWJsaXNoZWRBdCI6IjIwMjYtMDEtMTVUMTI6MDA6MDBaIiwiaWQiOiIuLi4ifQ
Response:
{
"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:
GET /api/v1/articles/search?q=election&page=2&pageSize=20
Response:
{
"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.
{
"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).
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"text": "The progressive reform includes welfare improvements and social justice..."
}
| Field | Type | Description |
|---|---|---|
text |
string (1-20000 chars) | Text to analyze |
Response:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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):
{
"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:
{
"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:
{
"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:
{
"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:
{
"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 |
Evidence Search#
| 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:
- Logger -- Request/response logging (when enabled)
- Timing -- Server-Timing header for performance monitoring
- Secure Headers -- Security response headers (CSP, HSTS, etc.)
- CORS -- Cross-origin resource sharing (when enabled)
- Rate Limiting -- Sliding window rate limiter on
/api/*routes - Sandbox Detection -- Detects
sk_test_*API keys and sets up sandbox context - API Key Auth -- Validates
X-API-Keyheader on/api/*routes - Error Handler -- Global error handler converting exceptions to JSON responses