API Documentation

Everything you need to integrate Synapse Discovery financial data into your applications.

🔑 Authentication

All API requests require an API key. Include your key in the X-API-Key header.

X-API-Key: sd_live_your_api_key_here

curl -H "X-API-Key: sd_live_xxx" \
  https://synapsediscovery.io/api/v1/entity/AAPL

🚀 Quick Start

import requests

# Set your API key
API_KEY = "sd_live_your_key"
BASE_URL = "https://synapsediscovery.io/api/v1"

headers = {"X-API-Key": API_KEY}

# Get Apple stock info
response = requests.get(f"{BASE_URL}/entity/AAPL", headers=headers)
data = response.json()
print(f"Company: {data['data']['name']}")

# Get historical prices
prices = requests.get(
    f"{BASE_URL}/prices/AAPL",
    headers=headers,
    params={"start": "2024-01-01", "limit": 30}
).json()

for price in prices['data'][:5]:
    print(f"{price['date']}: ${price['close']}")

const API_KEY = 'sd_live_your_key';
const BASE_URL = 'https://synapsediscovery.io/api/v1';

async function getStockData(ticker) {
  const response = await fetch(`${BASE_URL}/entity/${ticker}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return response.json();
}

// Get Apple data
const apple = await getStockData('AAPL');
console.log(apple.data.name); // "Apple Inc"

🏢 Entities

Entities represent securities in our universe. Each entity has a unique synapse_id that remains constant even when tickers change.

{
  "data": {
    "synapse_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Apple Inc",
    "current_ticker": "AAPL",
    "cik": "0000320193",
    "security_type": "common_stock",
    "status": "active",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "exchange": "NASDAQ"
  },
  "provenance": {...},
  "quality": {...},
  "cost": {...}
}

📈 Prices

Historical OHLCV price data with multiple adjustment types.

{
  "data": [
    {
      "date": "2026-01-24",
      "open": 195.50,
      "high": 198.75,
      "low": 194.20,
      "close": 198.42,
      "volume": 45892100
    }
  ],
  "provenance": {
    "source": "yahoo_finance",
    "adjustment_model": "split_adjusted"
  }
}

📊 Fundamentals

Standardized financial statements parsed from SEC filings (10-K, 10-Q).

📋 Corporate Actions

📦 Fund Holdings

{
  "data": [
    {
      "name": "Apple Inc",
      "ticker": "AAPL",
      "shares": 169547850,
      "market_value": 33659841250,
      "percentage": 7.12
    }
  ],
  "meta": {
    "fund_ticker": "SPY",
    "report_date": "2026-01-15"
  }
}

🏦 13F Institutional Holdings

{
  "data": [
    {
      "institution": "Vanguard Group Inc",
      "cik": "0000102909",
      "shares": 1234567890,
      "market_value": 245123456789,
      "change": 1500000,
      "change_pct": 0.12
    }
  ]
}

⚖️ Compare Entities

🏛️ Economic Series (FRED)

Access Federal Reserve economic data including interest rates, inflation, employment, and more.

📉 Yield Curve

{
  "data": {
    "date": "2026-01-24",
    "yields": {
      "1M": 5.25, "3M": 5.30, "6M": 5.20,
      "1Y": 5.00, "2Y": 4.50, "5Y": 4.20,
      "10Y": 4.10, "30Y": 4.30
    },
    "spread_2_10": -40,
    "is_inverted": true
  }
}

🌍 Market Context

🔮 Flexible Query (POST /query)

The "thick" endpoint for querying multiple entities with mixed data types in a single request.

{
  "universe": {
    "tickers": ["AAPL", "MSFT", "GOOGL"]
  },
  "fields": [
    "close_split_adj",
    "volume",
    "revenue",
    "eps_diluted"
  ],
  "range": {
    "start": "2024-01-01",
    "end": "2025-12-31"
  },
  "point_in_time": true,
  "asof": "2026-01-01T00:00:00Z"
}

⏰ Point-in-Time Queries

Query data as it was known at a specific historical date—essential for backtesting without look-ahead bias.

# What fundamentals were available on Jan 1, 2020?
GET /fundamentals/AAPL?as_of=2020-01-01&periods=4

# Returns only data that was filed BEFORE Jan 1, 2020
# No Q4 2019 data (filed in early 2020) - prevents look-ahead bias

🗃️ Data Lake Sync

Download complete datasets in Parquet format for local querying. Requires Quant tier or higher.

# Install the sync client
pip install synapse-discovery

# Initialize with your API key
synapse-discovery init --api-key sd_live_xxx

# Sync prices and fundamentals locally
synapse-discovery sync --to ./data --datasets prices,fundamentals

# Query with DuckDB
duckdb -c "SELECT * FROM './data/prices/NASDAQ/AAPL/*.parquet'"

🤖 AI-First Design

Every response includes metadata for AI agents: provenance, quality metrics, and cost tracking.

{
  "data": {...},
  
  // Where did this data come from?
  "provenance": {
    "source": "yahoo_finance",
    "collection_time": "2026-01-24T06:00:00Z",
    "adjustment_model": "split_adjusted"
  },
  
  // How reliable is this data?
  "quality": {
    "completeness": 0.98,
    "staleness_hours": 18
  },
  
  // Usage tracking
  "cost": {
    "units_consumed": 1,
    "cache_hit": true
  }
}

🔍 Discovery Endpoints

Self-describing endpoints for AI agents. No authentication required.

🔌 MCP Protocol Integration

Native Model Context Protocol support for Cursor, Claude Desktop, and other MCP-compatible AI tools.

{
  "mcpServers": {
    "synapse-discovery": {
      "url": "https://synapsediscovery.io/mcp",
      "headers": {
        "X-API-Key": "sd_live_your_key"
      }
    }
  }
}

Available MCP Tools

⚠️ Error Handling

Errors include structured codes, messages, and suggestions for AI agents.

{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "No entity found for identifier: APPL",
    "suggestion": "Did you mean one of these?",
    "similar": ["AAPL", "APL", "APLE"]
  }
}

HTTP Status Codes

⏱️ Rate Limits

📦 SDKs & Libraries

from synapse_discovery import SynapseClient

client = SynapseClient("your-key")
aapl = client.get("AAPL")
prices = client.prices("AAPL")

synapse-discovery init --api-key xxx
synapse-discovery sync --to ./data
synapse-discovery validate ./data