API Documentation

Access financial data, computed series, and market intelligence through a unified REST API.

Quick Start

All API endpoints require authentication via Bearer token. Get your API key from your dashboard.

# List all available series

curl -H "Authorization: Bearer de_live_..." \

/api/v1/series

# Fetch data for a series

curl -H "Authorization: Bearer de_live_..." \

/api/v1/series/CBDEO

# Get a summary (great for AI agents)

curl -H "Authorization: Bearer de_live_..." \

"/api/v1/series/CBDEO?summary=true"

Endpoints

GET/api/v1/series

List all available series. Supports filtering by category, source, and search.

categorystringFilter by category (e.g. "Central Bank", "Equities")

sourcestringFilter by source (e.g. "FRED", "DarklyEnergized")

searchstringSearch by name, ID, or description

GET/api/v1/series/:id

Fetch time-series data for a series. Supports date range, pagination, and summary mode.

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

limitintegerMax data points (default 500, max 10000)

afterdatePagination cursor — return data after this date

summarybooleanReturn statistical summary instead of raw data

POST/api/v1/series/batch

Fetch multiple series in one call. Up to 20 series per request.

idsstring[]Array of series IDs (required)

fromdateStart date (YYYY-MM-DD)

todateEnd date (YYYY-MM-DD)

summarybooleanReturn summaries instead of raw data

POST/api/v1/mcp

Model Context Protocol endpoint for AI agent integration. Connect Darkly Energized as an MCP server in Claude Desktop, Claude Code, or other MCP clients.

Response Format

All responses follow a consistent envelope with data and meta fields.

{
  "data": {
    "id": "CBDEO",
    "name": "Dark Energy Divergence Oscillator",
    "description": "CBDEO measures the divergence...",
    "category": "Liquidity",
    "frequency": "daily",
    "data": [
      { "time": "2026-02-14", "value": 1.23 },
      { "time": "2026-02-13", "value": 0.87 }
    ]
  },
  "meta": {
    "timestamp": "2026-02-16T12:00:00Z",
    "count": 540,
    "dataRange": { "from": "2024-01-01", "to": "2026-02-14" },
    "freshness": {
      "lastObservation": "2026-02-14",
      "frequency": "daily",
      "isStale": false
    },
    "pagination": {
      "hasMore": true,
      "cursor": "2025-01-15",
      "total": 540
    }
  }
}

MCP Integration

Connect Darkly Energized as an MCP server in any MCP-compatible client. Add this to your MCP configuration:

{
  "mcpServers": {
    "darklyenergized": {
      "serverUrl": "/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer de_live_..."
      }
    }
  }
}

Available Tools

de_list_series

Discover available data series. Filter by category, source, or search term.

de_get_series

Fetch data for any series. Returns context-efficient summaries by default (~200 bytes) or raw data points.

de_get_health

Check data freshness and staleness for monitoring data quality.

Rate Limits

Plan	Daily Limit
Basic	100 requests/day
Pro	1,000 requests/day
Enterprise	10,000 requests/day (contact us for more)

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Limits reset at midnight UTC.

OpenAPI Specification

The full OpenAPI 3.1 specification is available at /api/v1/openapi.json. Import it into your favorite API client (Postman, Insomnia, etc.) for testing.