# Veritas API Documentation

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

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

---

## Table of Contents

1. [Authentication](#authentication)
2. [Rate Limiting](#rate-limiting)
3. [Error Handling](#error-handling)
4. [Pagination](#pagination)
5. [Endpoints](#endpoints)
   - [Health](#health)
   - [Auth](#auth)
   - [Articles](#articles)
   - [Stories](#stories)
   - [Claims & Fact-Checking](#claims--fact-checking)
   - [Sources](#sources)
   - [Bias Analysis](#bias-analysis)
   - [Taxonomy](#taxonomy)
   - [Preferences](#preferences)
   - [Tips](#tips)
   - [Writing Assistant](#writing-assistant)
   - [Voice Profiles](#voice-profiles)
   - [Avatar Profiles](#avatar-profiles)
   - [Subscriptions](#subscriptions)
   - [Payments - MTN MoMo](#payments---mtn-momo)
   - [Payments - Vodafone Cash](#payments---vodafone-cash)
   - [Payments - AirtelTigo Money](#payments---airteltigo-money)
   - [Payments - Stripe](#payments---stripe)
   - [Subscription Analytics](#subscription-analytics)
   - [Paywall](#paywall)
   - [Reading Mode](#reading-mode)
   - [Compliance (NMC)](#compliance-nmc)
   - [Data Protection](#data-protection)
   - [Election Coverage](#election-coverage)
   - [Ads](#ads)
   - [Ad Networks](#ad-networks)
   - [B2B API](#b2b-api)
   - [API Keys](#api-keys)
6. [Schemas](#schemas)
7. [Environment Variables](#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/detailed`
- `GET /docs`, `GET /openapi.json`
- All public read endpoints (article listing, search, sources, taxonomy)

---

## Rate Limiting

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

**Defaults:**

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

**Client Identification:**

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

**Response Headers:**

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

**429 Response:**

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

---

## Error Handling

All errors return consistent JSON responses.

### Error Response Formats

**Standard Error:**

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

**Validation Error (400):**

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

**Rate Limit Error (429):**

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

### HTTP Status Codes

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

### Error Helper Functions

The API uses standardized error constructors:

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

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

---

## Pagination

### Cursor-Based Pagination

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

**Query Parameters:**

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

**Response:**

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

When `nextCursor` is `null`, there are no more items.

### 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:**

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

---

## Endpoints

### Health

Health check endpoints are exempt from authentication and rate limiting.

#### `GET /health`

Basic liveness check.

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

#### `GET /healthz`

Kubernetes liveness probe. Returns 200 with minimal body.

#### `GET /readyz`

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

**Response (healthy):**

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

**Response (degraded - 503):**

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

#### `GET /health/detailed`

Full health report with latency metrics for each dependency.

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

---

### Auth

#### `POST /api/v1/auth/register`

Register a new user account.

**Request Body:**

```json
{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "Kwame Asante"
}
```

| Field      | Type   | Required | Constraints        |
| ---------- | ------ | -------- | ------------------ |
| `email`    | string | Yes      | Valid email format |
| `password` | string | Yes      | Min 8 characters   |
| `name`     | string | No       | Display name       |

**Response (201):**

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

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

#### `POST /api/v1/auth/login`

Authenticate and receive a JWT token.

**Request Body:**

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

**Response (200):**

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

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

#### `GET /api/v1/auth/me`

Get the currently authenticated user's profile.

**Headers:** `Authorization: Bearer <token>` (required)

**Response (200):**

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

**Errors:** 401 (not authenticated)

---

### Articles

#### `GET /api/v1/articles`

List published articles with optional filtering.

**Query Parameters:**

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

**Response (200):**

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

#### `GET /api/v1/articles/trending`

Get trending articles based on view velocity.

**Query Parameters:**

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

**Response (200):**

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

#### `GET /api/v1/articles/search`

Full-text search across articles (requires Elasticsearch).

**Query Parameters:**

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

**Response (200):**

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

#### `GET /api/v1/articles/suggest`

Autocomplete search suggestions.

**Query Parameters:**

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

**Response (200):**

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

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

Get a single article by UUID.

**Response (200):**

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

**Errors:** 404 (article not found)

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

Get articles related to a specific article.

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

**Response (200):**

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

---

### Stories

Story clusters group related articles covering the same developing story.

#### `GET /api/v1/stories`

List story clusters.

**Query Parameters:** `limit`, `cursor`

**Response (200):**

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

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

Get story cluster details.

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

Get all articles in a story cluster.

**Query Parameters:** `limit`, `cursor`

---

### Claims & Fact-Checking

#### `GET /api/v1/claims`

List extracted claims with their verdicts.

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

**Response (200):**

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

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

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

Get a specific claim with full evidence.

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

Submit a claim for fact-checking. Requires authentication.

**Request Body:**

```json
{
  "claim": "Ghana's cocoa production increased by 20% in 2025",
  "refresh": false,
  "maxResults": 10,
  "country": "GH",
  "language": "en",
  "freshness": "month"
}
```

| Field        | Type    | Required | Default | Constraints                 |
| ------------ | ------- | -------- | ------- | --------------------------- |
| `claim`      | string  | Yes      | --      | Max 500 chars               |
| `refresh`    | boolean | No       | false   | Force re-check              |
| `maxResults` | int     | No       | 10      | 1-20                        |
| `country`    | string  | No       | "GH"    | ISO 3166-1 alpha-2          |
| `language`   | string  | No       | "en"    | Language code               |
| `freshness`  | string  | No       | "month" | day, week, month, year, any |

**Response (200):**

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

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

Get articles that mention a specific claim.

---

### Sources

#### `GET /api/v1/sources`

List news sources.

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

**Response (200):**

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

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

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

Get all sources plotted on the political bias spectrum.

**Response (200):**

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

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

Get media ownership group information.

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

Analyze cross-ownership patterns among news sources.

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

Get detailed source information.

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

Get source transparency scores and methodology.

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

Get correction history for a source.

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

Get detailed bias analysis for a source.

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

Get ownership chain for a source.

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

Get regional coverage emphasis for a source.

---

### Bias Analysis

#### `POST /api/v1/bias/score`

Analyze political bias in a text passage.

**Request Body:**

```json
{
  "text": "The government's economic policy has been remarkably successful..."
}
```

| Field  | Type   | Required | Constraints      |
| ------ | ------ | -------- | ---------------- |
| `text` | string | Yes      | Max 20,000 chars |

**Response (200):**

```json
{
  "score": 0.35,
  "band": "positive",
  "confidence": 0.82
}
```

- `score`: -1.0 (opposition-leaning) to 1.0 (government-leaning)
- `band`: `negative`, `neutral`, `positive`
- `confidence`: 0.0 to 1.0

---

### Taxonomy

#### `GET /api/v1/taxonomy/categories`

List all content categories with their topics.

**Response (200):**

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

#### `GET /api/v1/taxonomy/topics`

List all topics.

**Query Parameters:** `category` (filter by category slug)

---

### Preferences

#### `GET /api/v1/preferences`

Get user preferences. Requires authentication.

**Response (200):**

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

#### `PUT /api/v1/preferences`

Update user preferences (full replace). Requires authentication.

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

Partially update home feed preferences. Requires authentication.

---

### Tips

#### `POST /api/v1/tips`

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

**Request Body:**

```json
{
  "message": "I have information about corruption at...",
  "isAnonymous": true,
  "evidenceUrls": ["https://example.com/doc.pdf"],
  "contactEmail": "tipster@protonmail.com",
  "contactPhone": "+233201234567"
}
```

| Field          | Type     | Required | Constraints             |
| -------------- | -------- | -------- | ----------------------- |
| `message`      | string   | Yes      | 20-20,000 characters    |
| `isAnonymous`  | boolean  | No       | Default: true           |
| `evidenceUrls` | string[] | No       | URLs to supporting docs |
| `contactEmail` | string   | No       | Valid email format      |
| `contactPhone` | string   | No       | Phone number            |

**Response (201):**

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

---

### Writing Assistant

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

AI-powered text processing for journalists. Requires authentication.

**Request Body:**

```json
{
  "mode": "rewrite",
  "text": "The president spoke about the economy...",
  "instructions": "Make it more concise and formal",
  "tone": "journalistic",
  "languageTag": "en",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 500,
  "temperature": 0.3
}
```

| Field          | Type   | Required | Default     | Values                              |
| -------------- | ------ | -------- | ----------- | ----------------------------------- |
| `mode`         | string | Yes      | --          | rewrite, shorten, expand, bulletize |
| `text`         | string | Yes      | --          | Max 20,000 chars                    |
| `instructions` | string | No       | --          | Max 800 chars                       |
| `tone`         | string | No       | --          | Max 200 chars                       |
| `languageTag`  | string | No       | --          | Max 20 chars                        |
| `provider`     | string | No       | "anthropic" | anthropic, openai                   |
| `model`        | string | No       | (default)   | Max 80 chars                        |
| `maxTokens`    | int    | No       | 500         | 120-1,800                           |
| `temperature`  | number | No       | 0.3         | 0.0-1.0                             |

**Response (200):**

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

---

### Voice Profiles

Manage ElevenLabs TTS voice profiles for audio article generation.

#### `GET /api/v1/voice-profiles`

List all voice profiles.

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

Get a specific voice profile.

#### `POST /api/v1/voice-profiles`

Create a new voice profile. Requires authentication.

**Request Body:**

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

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

Update a voice profile. Requires authentication.

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

Deactivate a voice profile. Requires authentication.

---

### Avatar Profiles

Manage HeyGen avatar profiles for video article generation.

#### `GET /api/v1/avatar-profiles`

List all avatar profiles.

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

Get a specific avatar profile.

#### `POST /api/v1/avatar-profiles`

Create a new avatar profile. Requires authentication.

**Request Body:**

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

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

Update an avatar profile. Requires authentication.

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

Deactivate an avatar profile. Requires authentication.

---

### Subscriptions

#### `GET /api/v1/subscriptions/plans`

List available subscription plans with pricing.

**Response (200):**

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

#### `POST /api/v1/subscriptions`

Create a new subscription. Requires authentication.

#### `GET /api/v1/subscriptions/current`

Get the user's current subscription. Requires authentication.

#### `DELETE /api/v1/subscriptions/current`

Cancel the current subscription. Requires authentication.

#### `GET /api/v1/subscriptions/usage`

Get current subscription usage metrics. Requires authentication.

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

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

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

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

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

Verify student status for student pricing. Requires authentication.

---

### Payments - MTN MoMo

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

Initiate an MTN Mobile Money payment.

**Request Body:**

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

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

Check payment status.

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

Set up recurring payment preapproval.

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

Initiate a refund.

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

Validate a phone number for MoMo eligibility.

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

Check MoMo account balance (admin only).

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

Webhook endpoint for MoMo payment notifications.

#### `GET /api/v1/payments/transactions`

List payment transactions. Requires authentication.

#### `GET /api/v1/payments/subscriptions`

List payment-linked subscriptions. Requires authentication.

---

### Payments - Vodafone Cash

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

Initiate a Vodafone Cash payment.

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

Check Vodafone Cash payment status.

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

Initiate a Vodafone Cash refund.

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

Webhook endpoint for Vodafone Cash notifications.

---

### Payments - AirtelTigo Money

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

Initiate an AirtelTigo Money payment.

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

Check AirtelTigo Money payment status.

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

Initiate an AirtelTigo Money refund.

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

Webhook endpoint for AirtelTigo Money notifications.

---

### Payments - Stripe

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

Create a Stripe Checkout session for international payments.

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

Create a Stripe Customer Portal session for subscription management.

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

Stripe webhook endpoint for payment event processing.

---

### Subscription Analytics

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

Get subscription analytics overview. Requires admin authentication.

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

Get conversion funnel metrics.

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

Get churn analysis data.

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

Get revenue analytics (MRR, ARR, ARPU).

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

Get cohort retention analysis.

---

### Paywall

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

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

**Response (200):**

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

#### `POST /api/v1/paywall/meter`

Record an article read for metering purposes.

#### `GET /api/v1/paywall/meter`

Get current meter status for the user.

---

### Reading Mode

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

Get reading mode settings. Requires authentication.

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

Update reading mode settings. Requires authentication.

**Request Body:**

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

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

Save reading progress for an article.

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

Get reading progress for an article.

---

### Compliance (NMC)

Ghana National Media Commission compliance endpoints.

#### `GET /api/v1/compliance/status`

Get current NMC compliance status.

#### `POST /api/v1/compliance/check`

Run a compliance check against NMC guidelines.

#### `GET /api/v1/compliance/reports`

List compliance reports.

---

### Data Protection

Ghana Data Protection Act compliance endpoints.

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

Get user's consent status. Requires authentication.

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

Update consent preferences. Requires authentication.

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

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

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

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

---

### Election Coverage

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

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

Get political coverage balance analysis.

**Response (200):**

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

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

Get election coverage compliance status.

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

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

---

### Ads

#### `GET /api/v1/ads/placements`

Get available ad placements for the current page.

#### `POST /api/v1/ads/impression`

Record an ad impression.

#### `POST /api/v1/ads/click`

Record an ad click.

#### `GET /api/v1/ads/campaigns`

List ad campaigns (advertiser access). Requires authentication.

---

### Ad Networks

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

List configured ad network integrations.

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

Get ad network configuration.

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

Update ad network configuration. Requires admin authentication.

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

Get ad mediation waterfall configuration.

---

### B2B API

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

#### `GET /api/v1/b2b/feed`

Get a curated article feed for partner integration.

#### `GET /api/v1/b2b/search`

Search articles via B2B API.

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

Access fact-checking data via B2B API.

#### `GET /api/v1/b2b/entities`

Access entity data from the knowledge graph.

#### `GET /api/v1/b2b/usage`

Get API usage statistics for the current API key.

---

### API Keys

B2B API key lifecycle management.

#### `GET /api/v1/api-keys`

List API keys for the authenticated account.

#### `POST /api/v1/api-keys`

Generate a new API key. Requires authentication.

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

Revoke an API key. Requires authentication.

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

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

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

Get usage statistics for a specific API key.

---

## Schemas

### Core Data Types

#### ArticleListItem

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

#### ArticleDetail

Extends ArticleListItem with:

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

#### Source

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

#### Claim

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

#### StoryCluster

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

#### VoiceProfile

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

#### AvatarProfile

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

---

## Environment Variables

### Server Configuration

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

### CORS

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

### Rate Limiting

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

### API Key Authentication

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

### Database (PostgreSQL)

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

### Redis

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

### Elasticsearch

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

### Security

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

### OpenAPI

| Variable          | Default | Description                  |
| ----------------- | ------- | ---------------------------- |
| `OPENAPI_ENABLED` | true    | Enable OpenAPI docs endpoint |

---

_Last Updated: January 2026_

_Part of the Veritas domain API documentation_
