Eve library

Official SDKs

Guide

Revision 1

On this page

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)