Official Python SDK for the Veritas News B2B API. Provides comprehensive access to news articles, fact-checks, entities, media assets, and monitoring alerts.
Features#
- Full API Coverage: Access to all B2B API endpoints
- Async & Sync Support: Both async and synchronous clients
- Type Hints: Complete type annotations for IDE support
- Automatic Retries: Exponential backoff with jitter
- Rate Limit Handling: Built-in rate limit awareness
- Pagination Helpers: Async iterators for easy pagination
- Sandbox Support: Automatic test mode detection
Installation#
bash
pip install veritas-sdk
Quick Start#
Async Usage#
python
import asyncio
from veritas_sdk import VeritasClient
async def main():
# Create client (auto-detects sandbox mode from key prefix)
async with VeritasClient(api_key="sk_live_your_api_key") as client:
# List articles
response = await client.feed.list(limit=10, category="politics")
for article in response["items"]:
print(f"- {article['headline']}")
# Search articles
results = await client.search.query(
q="climate change",
category=["science", "politics"],
from_date="2024-01-01",
)
print(f"Found {results['total']} articles")
# Iterate through all results automatically
async for article in client.feed.iterate(category="sports"):
print(article["headline"])
asyncio.run(main())
Sync Usage#
python
from veritas_sdk import SyncVeritasClient
with SyncVeritasClient(api_key="sk_live_your_api_key") as client:
# List articles
response = client.feed.list(limit=10)
for article in response["items"]:
print(article["headline"])
# Verify a claim
claim = client.claims.verify("The earth is flat")
if claim:
print(f"Verdict: {claim['verdict']}")
API Resources#
Feed API#
Access news articles with filtering and pagination.
python
# List articles
response = await client.feed.list(
limit=20,
category="politics",
topic="elections",
lang="en",
from_date="2024-01-01",
)
# Get single article
article = await client.feed.get("article-uuid")
# Get trending articles
trending = await client.feed.trending(hours=24, limit=10)
# Iterate through all articles
async for article in client.feed.iterate(category="business"):
process(article)
Search API#
Full-text search with faceted results.
python
# Search with filters
results = await client.search.query(
q="artificial intelligence",
category=["technology", "business"],
bias=["center", "center-left", "center-right"],
sort_by="relevance",
)
# Access aggregations
for bucket in results["aggregations"]["categories"]:
print(f"{bucket['label']}: {bucket['count']}")
# Get autocomplete suggestions
suggestions = await client.search.suggest(q="pres", limit=5)
Fact-Check API#
Access fact-checked claims with ClaimReview structured data.
python
# List claims
claims = await client.claims.list(verdict="false", limit=10)
# Search claims
results = await client.claims.search(q="vaccine efficacy")
# Quick verify
claim = await client.claims.verify("COVID vaccines contain microchips")
if claim:
print(f"Verdict: {claim['verdict']}")
print(f"Evidence: {claim['evidenceSummary']}")
Entity API#
Knowledge graph operations for people, organizations, and locations.
python
# Search entities
results = await client.entities.search(
q="Nana Akufo-Addo",
type="person",
)
# Get entity with relationships
data = await client.entities.get_with_relationships("entity-uuid")
entity = data["entity"]
relationships = data["relationships"]
# Create entity
new_entity = await client.entities.create(
name="Ghana Revenue Authority",
type="organization",
description="Tax authority of Ghana",
aliases=["GRA"],
)
# Find or create
entity, created = await client.entities.find_or_create(
name="John Doe",
type="person",
)
Media API#
Access images, videos, and other media assets.
python
# List media
media = await client.media.list(kind="image", role="featured_image")
# Get media for article
article_media = await client.media.for_article("article-uuid")
# Search media
results = await client.media.search(q="parliament", kind="video")
# Get best variant for responsive images
url = client.media.get_best_variant(asset, target_width=800)
Alerts API#
Set up monitoring and notifications.
python
# Create keyword alert
subscription = await client.alerts.create_keyword_alert(
name="Elections Alert",
keywords=["election", "voting", "ballot"],
webhook_url="https://example.com/webhook",
frequency="instant",
)
# Create entity alert
await client.alerts.create_entity_alert(
name="Track Ghana President",
entity_ids=["entity-uuid"],
email="alerts@example.com",
)
# Create breaking news alert
await client.alerts.create_breaking_news_alert(
name="Breaking Politics",
categories=["politics"],
webhook_url="https://example.com/webhook",
)
# List subscriptions
subscriptions = await client.alerts.list(is_active=True)
# Get notifications
notifications = await client.alerts.notifications(delivered=False)
# Get monitoring stats
stats = await client.alerts.stats()
Sandbox API#
Manage test environment (test keys only).
python
# Create test client
client = VeritasClient(api_key="sk_test_your_test_key")
# Get sandbox status
status = await client.sandbox.status()
# Configure sandbox
await client.sandbox.configure(
seed="my-test-seed",
simulated_latency_ms=500,
)
# Reset sandbox
await client.sandbox.reset(preserve_config=True)
# Force error for testing
await client.sandbox.force_error(503)
Configuration#
python
client = VeritasClient(
api_key="sk_live_your_api_key",
base_url="https://api.veritas.news", # Optional: custom API URL
timeout=30.0, # Request timeout in seconds
retry=True, # Enable automatic retries
max_retries=3, # Maximum retry attempts
headers={"X-Custom-Header": "value"}, # Custom headers
)
Error Handling#
python
from veritas_sdk import (
VeritasError,
AuthenticationError,
RateLimitError,
NotFoundError,
ValidationError,
ServerError,
)
try:
article = await client.feed.get("article-uuid")
except AuthenticationError:
print("Invalid API key")
except NotFoundError as e:
print(f"Article not found: {e.resource_id}")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
print(f"Validation error: {e.details}")
except ServerError:
print("Server error, please retry")
except VeritasError as e:
print(f"API error: {e.message} (code: {e.code})")
Type Hints#
The SDK provides complete type hints for all API responses:
python
from veritas_sdk import Article, Claim, Entity, MediaAsset
async def process_article(article: Article) -> None:
headline: str = article["headline"]
categories = article["categories"] # List[Category]
entities = article["entities"] # List[EntityMention]
License#
MIT