# Veritas API Reference

Complete endpoint reference for the Veritas news intelligence platform API.

**Base URL:** `/api/v1` **Framework:** [Hono](https://hono.dev/) **Validation:**
[Zod](https://zod.dev/) **Database:** PostgreSQL (via `pg` connection pool)
**Search:** Elasticsearch **Cache / Rate Limiting:** Redis

---

## Table of Contents

- [Authentication](#authentication)
- [Rate Limiting](#rate-limiting)
- [Error Responses](#error-responses)
- [Pagination](#pagination)
- [Health Checks](#health-checks)
- [Articles](#articles)
- [Story Clusters](#story-clusters)
- [Claims and Fact-Checking](#claims-and-fact-checking)
- [Political Bias](#political-bias)
- [Sources](#sources)
- [Taxonomy](#taxonomy)
- [Tips](#tips)
- [Preferences](#preferences)
- [Voice Profiles](#voice-profiles)
- [Avatar Profiles](#avatar-profiles)
- [Writing Assistant](#writing-assistant)
- [Compliance (NMC)](#compliance-nmc)
- [Data Protection (DPA)](#data-protection-dpa)
- [Election Coverage](#election-coverage)
- [Payments (MTN MoMo)](#payments-mtn-momo)
- [Payments (Vodafone Cash)](#payments-vodafone-cash)
- [Payments (AirtelTigo Money)](#payments-airteltigo-money)
- [Payments (Stripe)](#payments-stripe)
- [Subscriptions](#subscriptions)
- [Paywall](#paywall)
- [Subscription Analytics](#subscription-analytics)
- [Ads](#ads)
- [Ad Networks](#ad-networks)
- [Reading Mode](#reading-mode)
- [API Keys (B2B)](#api-keys-b2b)
- [Sandbox](#sandbox)
- [B2B Partner API](#b2b-partner-api)
- [NLP Service](#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):**

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

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

```
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](#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](../../../veritas/b2b-api/).

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

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
