Eve library

Veritas B2B API Reference

Guide

Revision 1

On this page

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": [ ... ]
  }
}
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