# Veritas B2B API Reference

Complete reference documentation for all API endpoints.

**Base URL**: `https://api.veritas.news`

**API Version**: v1

**All endpoints require authentication via API key.**

---

## News Feed API

Access B2B-enriched news articles with engagement metrics and entity mentions.

### List Articles

```http
GET /api/v1/b2b/feed
```

Returns a paginated list of articles.

**Query Parameters:**

| Parameter  | Type    | Default | Description                           |
| ---------- | ------- | ------- | ------------------------------------- |
| `limit`    | integer | 20      | Items per page (1-100)                |
| `cursor`   | string  | -       | Pagination cursor                     |
| `category` | string  | -       | Filter by category slug               |
| `topic`    | string  | -       | Filter by topic slug                  |
| `lang`     | string  | -       | Filter by language (e.g., "en", "fr") |
| `source`   | string  | -       | Filter by source ID                   |
| `from`     | string  | -       | Filter by publish date (ISO 8601)     |
| `to`       | string  | -       | Filter by publish date (ISO 8601)     |

**Response:**

```json
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "climate-summit-reaches-agreement",
      "headline": "Climate Summit Reaches Historic Agreement",
      "summary": "World leaders agree on emission reduction targets...",
      "bodyHtml": null,
      "bodyText": null,
      "publishedAt": "2024-01-15T14:30:00Z",
      "languageTag": "en",
      "readTimeSeconds": 180,
      "source": {
        "id": "src_001",
        "name": "Global News Network",
        "domain": "gnn.com",
        "url": "https://gnn.com"
      },
      "sourceUrl": "https://gnn.com/climate-summit",
      "featuredImage": {
        "url": "https://cdn.veritas.news/images/climate.jpg",
        "alt": "World leaders at climate summit",
        "width": 1200,
        "height": 630
      },
      "authors": ["John Smith", "Jane Doe"],
      "categories": [{ "slug": "politics", "name": "Politics" }],
      "topics": [
        {
          "slug": "climate-change",
          "name": "Climate Change",
          "categorySlug": "environment"
        }
      ],
      "politicalBiasScore": 0.1,
      "engagement": {
        "viewCount": 15420
      },
      "entities": [
        {
          "id": "ent_001",
          "name": "United Nations",
          "type": "organization",
          "mentionCount": 5
        }
      ]
    }
  ],
  "nextCursor": "eyJpZCI6IjU1MGU4..."
}
```

### Get Article

```http
GET /api/v1/b2b/feed/{id}
```

Returns a single article with full body content.

**Path Parameters:**

| Parameter | Type   | Description  |
| --------- | ------ | ------------ |
| `id`      | string | Article UUID |

**Response:**

```json
{
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "climate-summit-reaches-agreement",
    "headline": "Climate Summit Reaches Historic Agreement",
    "summary": "World leaders agree on emission reduction targets...",
    "bodyHtml": "<p>In a landmark decision...</p>",
    "bodyText": "In a landmark decision...",
    "publishedAt": "2024-01-15T14:30:00Z",
    "languageTag": "en",
    "readTimeSeconds": 180,
    "source": { ... },
    "sourceUrl": "https://gnn.com/climate-summit",
    "featuredImage": { ... },
    "authors": ["John Smith", "Jane Doe"],
    "categories": [ ... ],
    "topics": [ ... ],
    "politicalBiasScore": 0.1,
    "engagement": { "viewCount": 15420 },
    "entities": [ ... ]
  }
}
```

### Get Trending Articles

```http
GET /api/v1/b2b/feed/trending
```

Returns trending articles based on engagement metrics.

**Query Parameters:**

| Parameter | Type    | Default | Description                  |
| --------- | ------- | ------- | ---------------------------- |
| `limit`   | integer | 10      | Number of articles (1-50)    |
| `hours`   | integer | 72      | Time window in hours (1-720) |

**Response:**

```json
{
  "items": [
    { ... }
  ]
}
```

---

## Search API

Full-text search with faceted aggregations.

### Search Articles

```http
POST /api/v1/b2b/search
```

Search articles with filters and get faceted aggregations.

**Request Body:**

```json
{
  "q": "climate change",
  "page": 1,
  "pageSize": 20,
  "from": "2024-01-01",
  "to": "2024-12-31",
  "category": ["politics", "science"],
  "topic": ["climate-change"],
  "source": ["src_001"],
  "lang": ["en"],
  "bias": ["center", "center-left", "center-right"],
  "sortBy": "relevance"
}
```

**Body Parameters:**

| Parameter  | Type     | Required | Description                              |
| ---------- | -------- | -------- | ---------------------------------------- |
| `q`        | string   | Yes      | Search query (1-500 chars)               |
| `page`     | integer  | No       | Page number (default: 1)                 |
| `pageSize` | integer  | No       | Results per page (default: 20, max: 100) |
| `from`     | string   | No       | Start date (ISO 8601)                    |
| `to`       | string   | No       | End date (ISO 8601)                      |
| `category` | string[] | No       | Filter by categories                     |
| `topic`    | string[] | No       | Filter by topics                         |
| `source`   | string[] | No       | Filter by source IDs                     |
| `lang`     | string[] | No       | Filter by languages                      |
| `bias`     | string[] | No       | Filter by bias bands                     |
| `sortBy`   | string   | No       | Sort by "relevance" or "publishedAt"     |

**Bias Bands:** `left`, `center-left`, `center`, `center-right`, `right`,
`unknown`

**Response:**

```json
{
  "items": [ ... ],
  "total": 1234,
  "page": 1,
  "pageSize": 20,
  "totalPages": 62,
  "aggregations": {
    "categories": [
      { "key": "politics", "count": 450, "label": "Politics" }
    ],
    "topics": [
      { "key": "climate-change", "count": 320, "label": "Climate Change" }
    ],
    "sources": [
      { "key": "src_001", "count": 180, "label": "Global News Network" }
    ],
    "biasDistribution": [
      { "key": "center", "count": 500 },
      { "key": "center-left", "count": 300 }
    ],
    "languageDistribution": [
      { "key": "en", "count": 1000 }
    ],
    "dateHistogram": [
      { "date": "2024-01-15", "count": 45 }
    ]
  }
}
```

### Get Suggestions

```http
GET /api/v1/b2b/search/suggest
```

Get autocomplete suggestions for search.

**Query Parameters:**

| Parameter | Type    | Required | Description                   |
| --------- | ------- | -------- | ----------------------------- |
| `q`       | string  | Yes      | Partial query                 |
| `limit`   | integer | No       | Max suggestions (default: 10) |

**Response:**

```json
{
  "suggestions": [
    {
      "text": "President announces new policy",
      "articleId": "550e8400-e29b-41d4-a716-446655440000",
      "articleSlug": "president-announces-new-policy"
    }
  ]
}
```

---

## Fact-Check API

Claim verification with ClaimReview schema.org structured data.

### List Claims

```http
GET /api/v1/b2b/fact-check/claims
```

Returns a paginated list of fact-checked claims.

**Query Parameters:**

| Parameter | Type    | Default | Description               |
| --------- | ------- | ------- | ------------------------- |
| `limit`   | integer | 20      | Items per page (1-100)    |
| `cursor`  | string  | -       | Pagination cursor         |
| `verdict` | string  | -       | Filter by verdict         |
| `from`    | string  | -       | Filter by date (ISO 8601) |
| `to`      | string  | -       | Filter by date (ISO 8601) |

**Verdict Values:** `true`, `mostly_true`, `mixed`, `misleading`,
`mostly_false`, `false`, `unverifiable`, `satire`

**Response:**

```json
{
  "items": [
    {
      "id": "claim_001",
      "text": "COVID-19 vaccines contain microchips",
      "normalizedText": "COVID-19 vaccines contain microchips",
      "verdict": "false",
      "confidence": 0.98,
      "evidenceSummary": "Multiple independent analyses have found no microchips...",
      "claimReview": {
        "@context": "https://schema.org",
        "@type": "ClaimReview",
        "claimReviewed": "COVID-19 vaccines contain microchips",
        "reviewRating": {
          "@type": "Rating",
          "ratingValue": 1,
          "bestRating": 5,
          "worstRating": 1,
          "alternateName": "False"
        },
        "author": {
          "@type": "Organization",
          "name": "Veritas Fact-Check",
          "url": "https://veritas.news/fact-check"
        },
        "datePublished": "2024-01-10T12:00:00Z",
        "url": "https://veritas.news/fact-check/vaccine-microchips",
        "itemReviewed": {
          "@type": "Claim",
          "author": {
            "@type": "Person",
            "name": "Unknown"
          },
          "datePublished": "2024-01-05",
          "appearance": [
            {
              "@type": "CreativeWork",
              "url": "https://example.com/post",
              "headline": "Viral Post"
            }
          ]
        }
      },
      "relatedArticles": [
        {
          "id": "article_001",
          "headline": "Fact Check: Vaccine Microchip Claims",
          "publishedAt": "2024-01-10T12:00:00Z",
          "sourceUrl": "https://veritas.news/article"
        }
      ],
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-10T12:00:00Z"
    }
  ],
  "nextCursor": null
}
```

### Get Claim

```http
GET /api/v1/b2b/fact-check/claims/{id}
```

Returns a single claim with full details.

**Response:**

```json
{
  "claim": { ... }
}
```

### Search Claims

```http
POST /api/v1/b2b/fact-check/search
```

Search and verify claims.

**Request Body:**

```json
{
  "q": "vaccine safety",
  "limit": 10,
  "language": "en"
}
```

**Response:**

```json
{
  "items": [ ... ],
  "total": 25
}
```

---

## Entity API

Knowledge graph operations with relationship tracking.

### Entity Types

- `person` - Individual people
- `organization` - Companies, governments, NGOs
- `location` - Cities, countries, regions
- `event` - Conferences, elections, disasters
- `product` - Products and services
- `legislation` - Laws and regulations
- `concept` - Abstract concepts and topics

### Relationship Types

- `leads` - Person leads organization
- `member_of` - Member of organization/group
- `located_in` - Located in place
- `founded` - Founded organization
- `works_for` - Employed by
- `related_to` - General relationship
- `opposes` - Opposition/conflict
- `allies_with` - Alliance/cooperation
- `subsidiary_of` - Child company
- `parent_of` - Parent company

### Search Entities

```http
GET /api/v1/b2b/entities/search
```

**Query Parameters:**

| Parameter | Type    | Required | Description               |
| --------- | ------- | -------- | ------------------------- |
| `q`       | string  | Yes      | Search query              |
| `type`    | string  | No       | Filter by entity type     |
| `limit`   | integer | No       | Max results (default: 20) |
| `offset`  | integer | No       | Results to skip           |

**Response:**

```json
{
  "entities": [
    {
      "id": "ent_001",
      "name": "United Nations",
      "type": "organization",
      "description": "International organization...",
      "aliases": ["UN", "U.N."],
      "imageUrl": "https://cdn.veritas.news/entities/un.png",
      "metadata": {
        "founded": 1945,
        "headquarters": "New York City"
      },
      "articleCount": 5420,
      "lastMentionedAt": "2024-01-15T14:30:00Z",
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 1
}
```

### Get Entity

```http
GET /api/v1/b2b/entities/{id}
```

**Response:**

```json
{
  "entity": { ... }
}
```

### Create Entity

```http
POST /api/v1/b2b/entities
```

**Request Body:**

```json
{
  "name": "New Organization",
  "type": "organization",
  "description": "Description of the organization",
  "aliases": ["Alias 1", "Alias 2"],
  "imageUrl": "https://example.com/logo.png",
  "metadata": {
    "founded": 2024
  }
}
```

**Response:**

```json
{
  "entity": { ... }
}
```

### Update Entity

```http
PATCH /api/v1/b2b/entities/{id}
```

**Request Body:**

```json
{
  "description": "Updated description",
  "aliases": ["New Alias"]
}
```

### Get Entity Articles

```http
GET /api/v1/b2b/entities/{id}/articles
```

Returns articles mentioning the entity.

**Query Parameters:**

| Parameter | Type    | Description           |
| --------- | ------- | --------------------- |
| `limit`   | integer | Max results           |
| `offset`  | integer | Results to skip       |
| `from`    | string  | Start date (ISO 8601) |
| `to`      | string  | End date (ISO 8601)   |

**Response:**

```json
{
  "articles": [ ... ],
  "total": 150
}
```

### Get Entity Relationships

```http
GET /api/v1/b2b/entities/{id}/relationships
```

**Query Parameters:**

| Parameter      | Type    | Description                 |
| -------------- | ------- | --------------------------- |
| `relationType` | string  | Filter by relationship type |
| `limit`        | integer | Max results                 |
| `offset`       | integer | Results to skip             |

**Response:**

```json
{
  "relationships": [
    {
      "id": "rel_001",
      "sourceEntityId": "ent_001",
      "targetEntityId": "ent_002",
      "relationType": "leads",
      "confidence": 0.95,
      "metadata": {},
      "sourceEntityName": "John Doe",
      "targetEntityName": "Acme Corp",
      "sourceEntityType": "person",
      "targetEntityType": "organization",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 5
}
```

### Record Entity Mention

```http
POST /api/v1/b2b/entities/mentions
```

Record an entity mention in an article.

**Request Body:**

```json
{
  "entityId": "ent_001",
  "articleId": "article_001",
  "mentionCount": 5,
  "sentiment": 0.3,
  "context": "The United Nations announced..."
}
```

### Create Relationship

```http
POST /api/v1/b2b/entities/relationships
```

**Request Body:**

```json
{
  "sourceEntityId": "ent_001",
  "targetEntityId": "ent_002",
  "relationType": "leads",
  "confidence": 0.95,
  "metadata": {}
}
```

---

## Media API

Access images, videos, and other media assets.

### Media Types

**Kinds:** `image`, `video`, `audio`, `document`, `embed`

**Roles:** `featured_image`, `thumbnail`, `gallery`, `inline`, `background`,
`avatar`, `logo`, `other`

**Transcode Status:** `pending`, `processing`, `completed`, `failed`

### List Media

```http
GET /api/v1/b2b/media
```

**Query Parameters:**

| Parameter   | Type    | Description           |
| ----------- | ------- | --------------------- |
| `limit`     | integer | Max results (1-100)   |
| `cursor`    | string  | Pagination cursor     |
| `articleId` | string  | Filter by article     |
| `kind`      | string  | Filter by media kind  |
| `role`      | string  | Filter by media role  |
| `from`      | string  | Start date (ISO 8601) |
| `to`        | string  | End date (ISO 8601)   |

**Response:**

```json
{
  "items": [
    {
      "id": "media_001",
      "articleId": "article_001",
      "kind": "image",
      "role": "featured_image",
      "originalUrl": "https://source.com/image.jpg",
      "cdnUrl": "https://cdn.veritas.news/media/image.jpg",
      "mimeType": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "durationSeconds": null,
      "sizeBytes": 245000,
      "altText": "Climate summit participants",
      "caption": "World leaders at the climate summit",
      "credit": "AFP",
      "transcodeStatus": "completed",
      "variants": [
        {
          "id": "var_001",
          "name": "thumbnail",
          "width": 320,
          "height": 180,
          "bitrate": null,
          "format": "webp",
          "codec": null,
          "quality": "low",
          "url": "https://cdn.veritas.news/media/image_320.webp",
          "sizeBytes": 15000
        },
        {
          "id": "var_002",
          "name": "medium",
          "width": 800,
          "height": 450,
          "bitrate": null,
          "format": "webp",
          "codec": null,
          "quality": "medium",
          "url": "https://cdn.veritas.news/media/image_800.webp",
          "sizeBytes": 65000
        }
      ],
      "metadata": {},
      "createdAt": "2024-01-15T14:30:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "nextCursor": null
}
```

### Get Media

```http
GET /api/v1/b2b/media/{id}
```

**Response:**

```json
{
  "media": { ... }
}
```

### Get Article Media

```http
GET /api/v1/b2b/media/article/{articleId}
```

Returns all media assets for an article.

**Response:**

```json
{
  "items": [ ... ]
}
```

### Search Media

```http
POST /api/v1/b2b/media/search
```

**Request Body:**

```json
{
  "q": "parliament",
  "kind": "image",
  "from": "2024-01-01",
  "to": "2024-12-31",
  "limit": 20,
  "offset": 0
}
```

**Response:**

```json
{
  "items": [ ... ],
  "total": 150,
  "limit": 20,
  "offset": 0
}
```

---

## Monitoring & Alerts API

Create and manage alert subscriptions.

### Alert Types

- `keyword` - Match specific keywords
- `topic` - Match specific topics
- `entity_mention` - Entity is mentioned
- `breaking_news` - Breaking news in categories
- `fact_check` - New fact-checks
- `source` - Articles from specific sources
- `sentiment_change` - Sentiment shift detection

### Alert Frequency

- `instant` - Immediate delivery
- `hourly` - Hourly digest
- `daily` - Daily digest
- `weekly` - Weekly digest

### List Subscriptions

```http
GET /api/v1/b2b/alerts
```

**Query Parameters:**

| Parameter   | Type    | Description                    |
| ----------- | ------- | ------------------------------ |
| `limit`     | integer | Max results (1-100)            |
| `cursor`    | string  | Pagination cursor              |
| `alertType` | string  | Filter by alert type           |
| `isActive`  | string  | Filter active ("true"/"false") |

**Response:**

```json
{
  "items": [
    {
      "id": "sub_001",
      "apiKeyId": "key_001",
      "name": "Breaking Politics Alert",
      "description": "Alert for breaking political news",
      "alertType": "breaking_news",
      "filters": {
        "categories": ["politics"]
      },
      "webhookUrl": "https://example.com/webhook",
      "email": null,
      "isActive": true,
      "frequency": "instant",
      "lastTriggered": "2024-01-15T10:00:00Z",
      "triggerCount": 45,
      "metadata": {},
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "nextCursor": null
}
```

### Create Subscription

```http
POST /api/v1/b2b/alerts
```

**Request Body:**

```json
{
  "name": "Keyword Alert",
  "alertType": "keyword",
  "filters": {
    "keywords": ["election", "voting"],
    "categories": ["politics"],
    "languages": ["en"]
  },
  "description": "Track election-related news",
  "webhookUrl": "https://example.com/webhook",
  "email": "alerts@example.com",
  "frequency": "instant",
  "metadata": {
    "team": "news-desk"
  }
}
```

**Filter Options:**

| Field          | Type     | Description             |
| -------------- | -------- | ----------------------- |
| `keywords`     | string[] | Keywords to match       |
| `topics`       | string[] | Topic slugs             |
| `entityIds`    | string[] | Entity UUIDs            |
| `sourceIds`    | string[] | Source UUIDs            |
| `categories`   | string[] | Category slugs          |
| `languages`    | string[] | Language codes          |
| `minSentiment` | number   | Min sentiment (-1 to 1) |
| `maxSentiment` | number   | Max sentiment (-1 to 1) |
| `verdicts`     | string[] | Fact-check verdicts     |

**Response:**

```json
{
  "subscription": { ... }
}
```

### Get Subscription

```http
GET /api/v1/b2b/alerts/{id}
```

### Update Subscription

```http
PATCH /api/v1/b2b/alerts/{id}
```

**Request Body:**

```json
{
  "name": "Updated Name",
  "isActive": false
}
```

### Delete Subscription

```http
DELETE /api/v1/b2b/alerts/{id}
```

**Response:**

```json
{
  "success": true
}
```

### List Notifications

```http
GET /api/v1/b2b/alerts/notifications
```

**Query Parameters:**

| Parameter        | Type    | Description                       |
| ---------------- | ------- | --------------------------------- |
| `limit`          | integer | Max results                       |
| `cursor`         | string  | Pagination cursor                 |
| `subscriptionId` | string  | Filter by subscription            |
| `delivered`      | string  | Filter delivered ("true"/"false") |

**Response:**

```json
{
  "items": [
    {
      "id": "notif_001",
      "subscriptionId": "sub_001",
      "articleId": "article_001",
      "entityId": null,
      "claimId": null,
      "notificationType": "keyword",
      "title": "New article matches your keywords",
      "summary": "Article about election results...",
      "payload": {
        "articleId": "article_001",
        "headline": "Election Results Announced"
      },
      "delivered": true,
      "deliveredAt": "2024-01-15T10:05:00Z",
      "deliveryAttempts": 1,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "nextCursor": null
}
```

### Get Monitoring Stats

```http
GET /api/v1/b2b/monitoring/stats
```

**Response:**

```json
{
  "stats": {
    "totalAlerts": 150,
    "activeSubscriptions": 12,
    "alertsTriggeredToday": 45,
    "alertsTriggeredThisWeek": 280,
    "topAlertTypes": [
      { "type": "keyword", "count": 120 },
      { "type": "breaking_news", "count": 80 }
    ],
    "recentNotifications": [ ... ]
  }
}
```

---

## Response Headers

All API responses include these headers:

| Header                  | Description                |
| ----------------------- | -------------------------- |
| `X-Request-ID`          | Unique request identifier  |
| `X-RateLimit-Limit`     | Rate limit ceiling         |
| `X-RateLimit-Remaining` | Remaining requests         |
| `X-RateLimit-Reset`     | Reset timestamp (ISO 8601) |
| `X-Sandbox`             | "true" if sandbox mode     |
