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#
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:
{
"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#
GET /api/v1/b2b/feed/{id}
Returns a single article with full body content.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Article UUID |
Response:
{
"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#
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:
{
"items": [
{ ... }
]
}
Search API#
Full-text search with faceted aggregations.
Search Articles#
POST /api/v1/b2b/search
Search articles with filters and get faceted aggregations.
Request Body:
{
"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:
{
"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#
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:
{
"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#
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:
{
"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#
GET /api/v1/b2b/fact-check/claims/{id}
Returns a single claim with full details.
Response:
{
"claim": { ... }
}
Search Claims#
POST /api/v1/b2b/fact-check/search
Search and verify claims.
Request Body:
{
"q": "vaccine safety",
"limit": 10,
"language": "en"
}
Response:
{
"items": [ ... ],
"total": 25
}
Entity API#
Knowledge graph operations with relationship tracking.
Entity Types#
person- Individual peopleorganization- Companies, governments, NGOslocation- Cities, countries, regionsevent- Conferences, elections, disastersproduct- Products and serviceslegislation- Laws and regulationsconcept- Abstract concepts and topics
Relationship Types#
leads- Person leads organizationmember_of- Member of organization/grouplocated_in- Located in placefounded- Founded organizationworks_for- Employed byrelated_to- General relationshipopposes- Opposition/conflictallies_with- Alliance/cooperationsubsidiary_of- Child companyparent_of- Parent company
Search Entities#
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:
{
"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#
GET /api/v1/b2b/entities/{id}
Response:
{
"entity": { ... }
}
Create Entity#
POST /api/v1/b2b/entities
Request Body:
{
"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:
{
"entity": { ... }
}
Update Entity#
PATCH /api/v1/b2b/entities/{id}
Request Body:
{
"description": "Updated description",
"aliases": ["New Alias"]
}
Get Entity Articles#
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:
{
"articles": [ ... ],
"total": 150
}
Get Entity Relationships#
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:
{
"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#
POST /api/v1/b2b/entities/mentions
Record an entity mention in an article.
Request Body:
{
"entityId": "ent_001",
"articleId": "article_001",
"mentionCount": 5,
"sentiment": 0.3,
"context": "The United Nations announced..."
}
Create Relationship#
POST /api/v1/b2b/entities/relationships
Request Body:
{
"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#
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:
{
"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#
GET /api/v1/b2b/media/{id}
Response:
{
"media": { ... }
}
Get Article Media#
GET /api/v1/b2b/media/article/{articleId}
Returns all media assets for an article.
Response:
{
"items": [ ... ]
}
Search Media#
POST /api/v1/b2b/media/search
Request Body:
{
"q": "parliament",
"kind": "image",
"from": "2024-01-01",
"to": "2024-12-31",
"limit": 20,
"offset": 0
}
Response:
{
"items": [ ... ],
"total": 150,
"limit": 20,
"offset": 0
}
Monitoring & Alerts API#
Create and manage alert subscriptions.
Alert Types#
keyword- Match specific keywordstopic- Match specific topicsentity_mention- Entity is mentionedbreaking_news- Breaking news in categoriesfact_check- New fact-checkssource- Articles from specific sourcessentiment_change- Sentiment shift detection
Alert Frequency#
instant- Immediate deliveryhourly- Hourly digestdaily- Daily digestweekly- Weekly digest
List Subscriptions#
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:
{
"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#
POST /api/v1/b2b/alerts
Request Body:
{
"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:
{
"subscription": { ... }
}
Get Subscription#
GET /api/v1/b2b/alerts/{id}
Update Subscription#
PATCH /api/v1/b2b/alerts/{id}
Request Body:
{
"name": "Updated Name",
"isActive": false
}
Delete Subscription#
DELETE /api/v1/b2b/alerts/{id}
Response:
{
"success": true
}
List Notifications#
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:
{
"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#
GET /api/v1/b2b/monitoring/stats
Response:
{
"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 |