Eve library

Veritas B2B API SDK for Python

Other

Revision 1

On this page

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