Veritas provides official SDKs for JavaScript/TypeScript and Python.
JavaScript/TypeScript SDK#
Installation#
bash
npm install @veritas/b2b-sdk
# or
yarn add @veritas/b2b-sdk
# or
pnpm add @veritas/b2b-sdk
Quick Start#
typescript
import { VeritasClient } from '@veritas/b2b-sdk';
const client = new VeritasClient({
apiKey: 'sk_live_your_api_key',
});
// List articles
const { items, nextCursor } = await client.feed.list({ limit: 10 });
// Search articles
const results = await client.search.query({ q: 'climate change' });
// Iterate through all articles
for await (const article of client.feed.iterate({ category: 'politics' })) {
console.log(article.headline);
}
Configuration#
typescript
const client = new VeritasClient({
apiKey: 'sk_live_your_api_key', // Required
baseUrl: 'https://api.veritas.news', // Default
timeout: 30000, // 30 seconds (default)
retry: true, // Enable automatic retries (default)
maxRetries: 3, // Maximum retry attempts (default)
sandbox: false, // Force sandbox mode (auto-detected from key)
headers: {}, // Custom headers
fetch: fetch, // Custom fetch implementation
});
Resources#
| Resource | Description |
|---|---|
client.feed |
News Feed API |
client.search |
Search API |
client.claims |
Fact-Check API |
client.entities |
Entity API |
client.media |
Media API |
client.alerts |
Monitoring & Alerts API |
client.sandbox |
Sandbox management |
Feed API#
typescript
// List articles
const response = await client.feed.list({
limit: 20,
category: 'politics',
topic: 'elections',
lang: 'en',
from: '2024-01-01',
to: '2024-12-31',
});
// Get single article
const { article } = await client.feed.get('article-uuid');
// Get trending
const { items } = await client.feed.trending({ hours: 24, limit: 10 });
// Auto-pagination iterator
for await (const article of client.feed.iterate({ category: 'sports' })) {
console.log(article.headline);
}
// Collect all articles (with limit)
const allArticles = await client.feed.all({ category: 'tech' }, 500);
Search API#
typescript
// Search with filters
const results = await client.search.query({
q: 'climate change',
page: 1,
pageSize: 20,
category: ['science', 'politics'],
bias: ['center', 'center-left'],
sortBy: 'relevance',
});
// Access aggregations
console.log(results.aggregations.categories);
console.log(results.aggregations.biasDistribution);
// Autocomplete suggestions
const { suggestions } = await client.search.suggest({ q: 'presi', limit: 5 });
// Iterate through all search results
for await (const article of client.search.iterate({ q: 'election' })) {
console.log(article.headline);
}
Claims API#
typescript
// List claims
const claims = await client.claims.list({ verdict: 'false', limit: 10 });
// Get claim detail
const { claim } = await client.claims.get('claim-uuid');
// Search claims
const results = await client.claims.search({ q: 'vaccine safety' });
// Quick verify a statement
const claim = await client.claims.verify('The earth is flat');
if (claim) {
console.log(`Verdict: ${claim.verdict}`);
console.log(`Evidence: ${claim.evidenceSummary}`);
}
Entities API#
typescript
// Search entities
const { entities, total } = await client.entities.search({
q: 'Elon Musk',
type: 'person',
});
// Get entity with relationships
const { entity, relationships } =
await client.entities.getWithRelationships('entity-uuid');
// Create entity
const { entity: newEntity } = await client.entities.create({
name: 'New Organization',
type: 'organization',
description: 'Description...',
});
// Find or create
const { entity, created } = await client.entities.findOrCreate({
name: 'John Doe',
type: 'person',
});
// Get articles mentioning entity
const articles = await client.entities.articles('entity-uuid', { limit: 20 });
// Create relationship
await client.entities.createRelationship({
sourceEntityId: 'person-uuid',
targetEntityId: 'org-uuid',
relationType: 'works_for',
confidence: 0.95,
});
Media API#
typescript
// List media
const media = await client.media.list({
kind: 'image',
role: 'featured_image',
});
// Get media for article
const { items } = await client.media.forArticle('article-uuid');
// Search media
const results = await client.media.search({ q: 'parliament', kind: 'video' });
// Get best variant for responsive display
const url = client.media.getBestVariant(mediaAsset, 800);
// Convenience methods
const images = await client.media.images({ limit: 10 });
const videos = await client.media.videos({ limit: 10 });
Alerts API#
typescript
// Create keyword alert
const { subscription } = await client.alerts.createKeywordAlert(
'Election Alert',
['election', 'voting', 'ballot'],
{
categories: ['politics'],
webhookUrl: 'https://your-server.com/webhook',
frequency: 'instant',
}
);
// Create entity alert
await client.alerts.createEntityAlert('Track CEO', ['entity-uuid'], {
email: 'alerts@example.com',
});
// Create breaking news alert
await client.alerts.createBreakingNewsAlert('Breaking Politics', {
categories: ['politics'],
});
// List subscriptions
const subs = await client.alerts.list({ isActive: true });
// Update subscription
await client.alerts.update(subscriptionId, { frequency: 'daily' });
// Enable/disable
await client.alerts.enable(subscriptionId);
await client.alerts.disable(subscriptionId);
// Get notifications
const notifications = await client.alerts.notifications({ delivered: false });
// Get monitoring stats
const stats = await client.alerts.stats();
Sandbox API#
typescript
// Get status
const status = await client.sandbox.status();
// Configure
await client.sandbox.configure({
seed: 'my-test-seed',
simulatedLatencyMs: 500,
errorRate: 0.1,
});
// Reset
await client.sandbox.reset({ preserveConfig: true });
// Force error
await client.sandbox.forceError(503);
// Convenience methods
await client.sandbox.setSeed('new-seed');
await client.sandbox.setLatency(1000);
await client.sandbox.setErrorRate(0.05);
Error Handling#
typescript
import {
VeritasError,
AuthenticationError,
NotFoundError,
RateLimitError,
ValidationError,
ServerError,
TimeoutError,
NetworkError,
} from '@veritas/b2b-sdk';
try {
await client.feed.get('invalid-id');
} catch (error) {
if (error instanceof AuthenticationError) {
// Handle auth error
} else if (error instanceof NotFoundError) {
// Handle not found
} else if (error instanceof RateLimitError) {
// error.retryAfter - seconds to wait
// error.resetAt - when limit resets
} else if (error instanceof ValidationError) {
// error.details - validation error details
} else if (error instanceof ServerError) {
// Retry with backoff
} else if (error instanceof TimeoutError) {
// error.timeoutSeconds
} else if (error instanceof NetworkError) {
// Check connectivity
} else if (error instanceof VeritasError) {
// Generic API error
// error.code, error.message, error.status
}
}
TypeScript Types#
typescript
import type {
Article,
Entity,
Claim,
MediaAsset,
AlertSubscription,
SearchResponse,
PaginatedResponse,
EntityType,
ClaimVerdict,
} from '@veritas/b2b-sdk';
// Use types for type safety
function processArticle(article: Article): void {
const headline: string = article.headline;
const entities: EntityMention[] = article.entities;
}
Python SDK#
Installation#
bash
pip install veritas-sdk
Quick Start#
python
import asyncio
from veritas_sdk import VeritasClient
async def main():
async with VeritasClient(api_key="sk_live_your_api_key") as client:
# List articles
response = await client.feed.list(limit=10)
for article in response["items"]:
print(article["headline"])
# Search articles
results = await client.search.query(q="climate change")
print(f"Found {results['total']} articles")
asyncio.run(main())
Synchronous Client#
python
from veritas_sdk import SyncVeritasClient
with SyncVeritasClient(api_key="sk_live_your_api_key") as client:
response = client.feed.list(limit=10)
for article in response["items"]:
print(article["headline"])
Configuration#
python
client = VeritasClient(
api_key="sk_live_your_api_key", # Required
base_url="https://api.veritas.news", # Default
timeout=30.0, # 30 seconds (default)
retry=True, # Enable automatic retries (default)
max_retries=3, # Maximum retry attempts (default)
sandbox=False, # Force sandbox mode (auto-detected from key)
headers={}, # Custom headers
)
Feed API#
python
# List articles
response = await client.feed.list(
limit=20,
category="politics",
topic="elections",
lang="en",
from_date="2024-01-01",
to_date="2024-12-31",
)
# Get single article
result = await client.feed.get("article-uuid")
article = result["article"]
# Get trending
trending = await client.feed.trending(hours=24, limit=10)
# Auto-pagination iterator
async for article in client.feed.iterate(category="sports"):
print(article["headline"])
# Collect all articles (with limit)
all_articles = await client.feed.all(category="tech", max_items=500)
Search API#
python
# Search with filters
results = await client.search.query(
q="climate change",
page=1,
page_size=20,
category=["science", "politics"],
bias=["center", "center-left"],
sort_by="relevance",
)
# Access aggregations
print(results["aggregations"]["categories"])
# Autocomplete suggestions
suggestions = await client.search.suggest(q="presi", limit=5)
# Iterate through all search results
async for article in client.search.iterate(q="election"):
print(article["headline"])
Claims API#
python
# List claims
claims = await client.claims.list(verdict="false", limit=10)
# Get claim detail
result = await client.claims.get("claim-uuid")
claim = result["claim"]
# Search claims
results = await client.claims.search(q="vaccine safety")
# Quick verify a statement
claim = await client.claims.verify("The earth is flat")
if claim:
print(f"Verdict: {claim['verdict']}")
print(f"Evidence: {claim['evidenceSummary']}")
Entities API#
python
# Search entities
result = await client.entities.search(q="Elon Musk", type="person")
entities = result["entities"]
# Get entity with relationships
data = await client.entities.get_with_relationships("entity-uuid")
entity = data["entity"]
relationships = data["relationships"]
# Create entity
result = await client.entities.create(
name="New Organization",
type="organization",
description="Description...",
)
# Find or create
entity, created = await client.entities.find_or_create(
name="John Doe",
type="person",
)
# Get articles mentioning entity
articles = await client.entities.articles("entity-uuid", limit=20)
# Create relationship
await client.entities.create_relationship(
source_entity_id="person-uuid",
target_entity_id="org-uuid",
relation_type="works_for",
confidence=0.95,
)
Media API#
python
# List media
media = await client.media.list(kind="image", role="featured_image")
# Get media for article
result = await client.media.for_article("article-uuid")
items = result["items"]
# Search media
results = await client.media.search(q="parliament", kind="video")
# Get best variant for responsive display
url = client.media.get_best_variant(media_asset, target_width=800)
# Convenience methods
images = await client.media.images(limit=10)
videos = await client.media.videos(limit=10)
Alerts API#
python
# Create keyword alert
result = await client.alerts.create_keyword_alert(
name="Election Alert",
keywords=["election", "voting", "ballot"],
categories=["politics"],
webhook_url="https://your-server.com/webhook",
frequency="instant",
)
# Create entity alert
await client.alerts.create_entity_alert(
name="Track CEO",
entity_ids=["entity-uuid"],
email="alerts@example.com",
)
# Create breaking news alert
await client.alerts.create_breaking_news_alert(
name="Breaking Politics",
categories=["politics"],
)
# List subscriptions
subs = await client.alerts.list(is_active=True)
# Update subscription
await client.alerts.update(subscription_id, frequency="daily")
# Enable/disable
await client.alerts.enable(subscription_id)
await client.alerts.disable(subscription_id)
# Get notifications
notifications = await client.alerts.notifications(delivered=False)
# Get monitoring stats
stats = await client.alerts.stats()
Sandbox API#
python
# Get status
status = await client.sandbox.status()
# Configure
await client.sandbox.configure(
seed="my-test-seed",
simulated_latency_ms=500,
error_rate=0.1,
)
# Reset
await client.sandbox.reset(preserve_config=True)
# Force error
await client.sandbox.force_error(503)
# Convenience methods
await client.sandbox.set_seed("new-seed")
await client.sandbox.set_latency(1000)
await client.sandbox.set_error_rate(0.05)
Error Handling#
python
from veritas_sdk import (
VeritasError,
AuthenticationError,
NotFoundError,
RateLimitError,
ValidationError,
ServerError,
TimeoutError,
NetworkError,
)
try:
await client.feed.get("invalid-id")
except AuthenticationError as e:
# Handle auth error
print(f"Auth failed: {e.message}")
except NotFoundError as e:
# Handle not found
print(f"Resource not found: {e.resource_id}")
except RateLimitError as e:
# e.retry_after - seconds to wait
# e.reset_at - when limit resets
await asyncio.sleep(e.retry_after)
except ValidationError as e:
# e.details - validation error details
print(f"Validation failed: {e.details}")
except ServerError as e:
# Retry with backoff
print(f"Server error: {e.message}")
except TimeoutError as e:
# e.timeout_seconds
print(f"Request timed out after {e.timeout_seconds}s")
except NetworkError as e:
# Check connectivity
print(f"Network error: {e.message}")
except VeritasError as e:
# Generic API error
print(f"API error [{e.code}]: {e.message}")
Type Hints#
The Python SDK includes full TypedDict type hints:
python
from veritas_sdk import (
Article,
Entity,
Claim,
MediaAsset,
AlertSubscription,
SearchResponse,
PaginatedResponse,
EntityType,
ClaimVerdict,
)
def process_article(article: Article) -> None:
headline: str = article["headline"]
entities = article["entities"] # List[EntityMention]
Feature Comparison#
| Feature | JavaScript SDK | Python SDK |
|---|---|---|
| Async Support | Yes | Yes |
| Sync Support | No | Yes |
| Auto Pagination | Yes (async iterators) | Yes (async generators) |
| Type Safety | Full TypeScript | TypedDict hints |
| Retry Logic | Yes | Yes |
| Rate Limit Handling | Yes | Yes |
| Sandbox Detection | Yes | Yes |
| Custom HTTP Client | Yes (fetch) | No (httpx built-in) |
Requirements#
JavaScript SDK#
- Node.js 18+ or modern browser
- ES2020+ support
- Optional: TypeScript 4.7+
Python SDK#
- Python 3.9+
- httpx library (installed automatically)