Catalayer API: Getting Started with Python

What the Catalayer API Provides

The Catalayer API gives developers programmatic access to the same data that powers the Catalayer platform: real-time financial news, AI Public Briefs, ticker-specific feeds, topic coverage, and market intelligence signals.

Two primary use cases:

• News ingestion: Pull structured, deduplicated financial news into your own systems, models, or dashboards
• AI intelligence: Access Public Brief summaries, event classifications, and relevance scores as structured JSON

The API is REST-based, returns JSON, and requires API key authentication. Base URL: https://api.catalayer.com

Authentication

All API requests require an Authorization header with your API key:

Authorization: Bearer YOUR_API_KEY

You can generate and manage API keys in your account settings at /account under the Developer section.

News API

GET /v1/news

Returns recent market-moving news stories with classification metadata and Public Brief data.

import requests

API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.catalayer.com"

headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get(
    f"{BASE_URL}/v1/news",
    headers=headers,
    params={
        "limit": 20,
        "source": "all",      # or specific source name
        "ticker": "NVDA",     # optional: filter by ticker
        "topic": "earnings",  # optional: filter by topic
    }
)

data = response.json()
stories = data.get("stories", [])

for story in stories:
    print(story["headline"])
    print(story["received_at"])
    print(story.get("ai_brief", {}).get("summary", ""))
    print("---")

{
  "stories": [
    {
      "story_id": "abc123",
      "headline": "NVDA Q1 Revenue Beats Estimates by 12%",
      "received_at": "2026-05-27T08:42:11Z",
      "source": "MarketWatch",
      "source_url": "https://example.com/article",
      "slug": "nvda-q1-revenue-beats-estimates",
      "tickers": ["NVDA"],
      "sectors": ["Technology"],
      "event_type": "earnings",
      "ai_brief": {
        "summary": "Nvidia reported Q1 revenue 12% above consensus estimates, driven by data center demand. Management raised full-year guidance.",
        "impact_direction": "bullish",
        "magnitude": "high",
        "affected_sectors": ["Technology", "Semiconductors"],
        "key_variables": ["data center demand", "AI chip supply", "forward guidance"]
      }
    }
  ],
  "total": 1,
  "page": 1
}

GET /v1/news/{slug}

Returns a single news story by its URL slug, including the full Public Brief.

slug = "nvda-q1-revenue-beats-estimates"

response = requests.get(
    f"{BASE_URL}/v1/news/{slug}",
    headers=headers
)

story = response.json()
brief = story.get("ai_brief", {})
print(brief.get("summary"))
print(brief.get("impact_direction"))

AI Market Intelligence API

GET /v1/intelligence

Returns the current AI-analyzed news stream with full classification metadata.

response = requests.get(
    f"{BASE_URL}/v1/intelligence",
    headers=headers,
    params={
        "min_relevance": 60,   # 0-100, filters low-signal stories
        "sector": "energy",    # optional sector filter
        "limit": 50,
    }
)

items = response.json().get("items", [])
for item in items:
    print(item["headline"], "|", item["relevance_score"])

Pagination

All list endpoints support cursor-based pagination via the cursor parameter:

cursor = None
all_stories = []

while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(f"{BASE_URL}/v1/news", headers=headers, params=params)
    data = response.json()
    all_stories.extend(data.get("stories", []))

    cursor = data.get("next_cursor")
    if not cursor:
        break

Error Handling

The API uses standard HTTP status codes:

def fetch_news(ticker=None, limit=20):
    try:
        response = requests.get(
            f"{BASE_URL}/v1/news",
            headers=headers,
            params={"ticker": ticker, "limit": limit},
            timeout=10
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Invalid API key. Check your credentials.")
        elif e.response.status_code == 402:
            print("This endpoint requires a Plus subscription.")
        elif e.response.status_code == 429:
            retry_after = int(e.response.headers.get("Retry-After", 60))
            print(f"Rate limited. Retry in {retry_after} seconds.")
        else:
            print(f"HTTP error: {e.response.status_code}")
        return None
    except requests.exceptions.Timeout:
        print("Request timed out.")
        return None

Rate Limits

• Free tier: 60 requests per minute
• Plus: 300 requests per minute
• Enterprise: custom

Rate limit headers are returned with every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1748300000

Webhooks

Instead of polling, you can configure Catalayer to push new stories to your endpoint in real time. Configure webhooks at /account under Developer Settings.

Webhook payload follows the same shape as the /v1/news/{slug} response, with an additional event field set to "story.published".

Next Steps

• Full API reference: /documentation
• Webhook setup: /account → Developer Settings
• Integration overview: /integrate
• Plans and API access tiers: /plans