API

Corrlens API

Read-only endpoints for discovering supported IDs, checking stored coverage, and fetching stored 5Y correlation records.

Base/api/v1Version2026-05-09AuthNo key for public v1 reads

Start Here

Use universe first, coverage second, relationships third.

Find valid IDs
GET /api/v1/universe
Use this for the full requestable stock, crypto, and FRED catalog.
Check stored coverage
GET /api/v1/symbols
Use this for symbols that already have public correlation rows.
Fetch relationships
GET /api/v1/symbols/{provider}/{id}
Use this for top partners, or fetch a known pair directly.

Contract

Public v1 routes are stable, cached read routes. They return stored data only; they do not trigger fresh correlation computation.

Auth

No key for public reads.

Data

Stored correlations, currently 5Y.

IDs

Provider plus canonical id.

Format

JSON responses and JSON errors.

Choose An Endpoint

Pick the row that matches the question you are asking.

I need the complete accepted ID catalog

GET /api/v1/universe

I only want symbols with stored correlation rows

GET /api/v1/symbols

I want the top partners for one symbol

GET /api/v1/symbols/{provider}/{id}

I want the top partners for one stock ticker

GET /api/v1/stocks/{symbol}/top-correlations

I know both series and need one pair

GET /api/v1/pairs/{providerA}/{idA}/{providerB}/{idB}

I need to check up to 25 known pairs

POST /api/v1/pairs

I need field names, limits, and enum values

GET /api/v1/attributes

Endpoints

Inputs are query parameters unless marked as path or body fields.

GET/api/v1

API index

Discover the current public API version and route list.

Inputs: No query parameters.
Returns: object: "api", version, documentation, and endpoint paths.
Cache: Public cache.

GET/api/v1/attributes

Schema and limits

Read provider IDs, field meanings, alignment modes, and request limits.

Inputs: No query parameters.
Returns: object: "attributes" plus providers, pair fields, symbol fields, and limits.
Cache: Public cache.

GET/api/v1/universe

Requestable universe

Search everything Corrlens can request from its data providers.

Inputs: provider: optional stock, crypto, or fred.q: optional text search.
Returns: object: "data_universe", totals, filtered counts, sources, and grouped data arrays.
Cache: Public cache. Does not require database coverage.

GET/api/v1/symbols

Stored coverage

List only symbols that currently have stored public correlations.

Inputs: provider: optional stock, crypto, or fred.q: optional text search.limit: default 50, max 500.offset: default 0.
Returns: object: "list", data, total, limit, and offset.
Cache: Public cache. Uses stored coverage only.

GET/api/v1/symbols/{provider}/{id}

Symbol network

Fetch one symbol and its strongest stored correlation partners.

Inputs: provider: stock, crypto, or fred.id: canonical ticker or FRED series ID.limit: default 25, max 200.offset: default 0.
Returns: object: "symbol" plus a correlations list.
Cache: Public cache. Returns 404 when the symbol has no stored coverage.

GET/api/v1/stocks/{symbol}/top-correlations

Stock top correlations

Convenience route for one stock ticker.

Inputs: symbol: stock ticker, for example AAPL.limit: default 25, max 200.offset: default 0.
Returns: object: "stock_top_correlations", stock, and correlations.
Cache: Public cache. Same stored data as the symbol network route.

GET/api/v1/pairs/{providerA}/{idA}/{providerB}/{idB}

Single pair

Fetch one stored pair when you know both series.

Inputs: providerA, providerB: stock, crypto, or fred.idA, idB: canonical ticker or FRED series ID.preview: optional 1, true, or yes to include sampled chart points.
Returns: object: "correlation_pair" with series, stats, diagnostics, summary, and links.
Cache: Public cache. Returns 404 when the pair has not been stored.

POST/api/v1/pairs

Batch pair lookup

Check several known pairs with one request.

Inputs: JSON body with pairs, maximum 25.pairs accepts two-item arrays or objects with seriesA and seriesB.includePreview: optional boolean.
Returns: object: "list"; each row has found, requested, and pair.
Cache: No explicit cache header. POST requests are handled on demand.

Quick start

BASE="https://www.corrlens.com/api/v1"

curl -s "$BASE/universe?provider=fred&q=CPIAUCSL" | jq .

curl -s "$BASE/symbols?provider=stock&q=AAPL&limit=3" | jq .

curl -s "$BASE/symbols/stock/AAPL?limit=10" | jq .

curl -s "$BASE/pairs/stock/AAPL/stock/MSFT?preview=1" | jq .

Batch lookup

curl -s -X POST "https://www.corrlens.com/api/v1/pairs" \
  -H "Content-Type: application/json" \
  -d '{
    "includePreview": false,
    "pairs": [
      [
        { "provider": "stock", "id": "AAPL" },
        { "provider": "stock", "id": "MSFT" }
      ],
      {
        "seriesA": "stock:NVDA",
        "seriesB": "fred:CPIAUCSL"
      }
    ]
  }' | jq .

Fields And Errors

The field list below covers the values most integrations use. The full schema is available at /api/v1/attributes.

Symbol fields

provider: stock, crypto, or fred.
id: canonical ticker or series ID.
name: display name.
group: sector, asset category, FRED category, or FX group.
partnerCount: stored correlation coverage for that symbol.

Correlation fields

correlation: Pearson r from -1 to 1.
absCorrelation: absolute value used for ranking.
syncRate: fraction of periods moving in the same direction.
overlapPoints: aligned observation count.
dataThrough: latest data date used by the stored pair.

Error shape

invalid_provider: provider must be stock, crypto, or fred.
invalid_symbol: empty or malformed ID.
not_found: symbol or pair is not stored.
invalid_json, invalid_pairs, too_many_pairs: POST body problems.
internal_error: unexpected server failure.

Response Examples

Representative shapes. Numeric values and partner order change as stored data updates.

Show details

Universe response

{
  "object": "data_universe",
  "version": "2026-05-09",
  "filters": { "provider": "fred", "q": "CPIAUCSL" },
  "totals": { "stocks": 1371, "crypto": 25, "fred": 1214, "total": 2610 },
  "counts": { "stocks": 0, "crypto": 0, "fred": 1, "total": 1 },
  "data": {
    "stocks": [],
    "crypto": [],
    "fred": [{
      "object": "universe_symbol",
      "provider": "fred",
      "id": "CPIAUCSL",
      "name": "Consumer Price Index for All Urban Consumers",
      "group": "inflation"
    }]
  }
}

Symbol response

{
  "object": "symbol",
  "provider": "stock",
  "id": "AAPL",
  "name": "Apple Inc.",
  "group": "Technology",
  "partnerCount": 1240,
  "correlations": {
    "object": "list",
    "limit": 10,
    "offset": 0,
    "data": [{
      "object": "symbol_correlation",
      "partner": { "provider": "stock", "id": "MSFT", "name": "Microsoft Corporation" },
      "correlation": 0.59,
      "absCorrelation": 0.59,
      "syncRate": 0.58,
      "overlapPoints": 1258,
      "links": {
        "web": "/correlations/AAPL/MSFT",
        "api": "/api/v1/pairs/stock/AAPL/stock/MSFT"
      }
    }]
  }
}

Pair response

{
  "object": "correlation_pair",
  "seriesA": { "provider": "stock", "id": "AAPL", "name": "Apple Inc." },
  "seriesB": { "provider": "stock", "id": "MSFT", "name": "Microsoft Corporation" },
  "window": "5Y",
  "alignmentMode": "daily",
  "correlation": 0.59,
  "absCorrelation": 0.59,
  "syncRate": 0.58,
  "overlapPoints": 1258,
  "stats": { "r2": 0.35, "pValue": 0.001 },
  "links": {
    "web": "/correlations/AAPL/MSFT",
    "api": "/api/v1/pairs/stock/AAPL/stock/MSFT"
  }
}

Error response

{
  "error": {
    "code": "not_found",
    "message": "Pair was not found in stored Corrlens correlations."
  }
}

App Helper Routes

These routes power the Corrlens UI. Treat public v1 as the external integration contract.

Show details

Unified symbol search

/api/symbols/search

UI autocomplete helper. Prefer `/api/v1/universe` for stable external integrations.

Provider autocomplete

/api/stocks/search, /api/crypto/search, /api/fred/search

Provider-specific UI helpers. They can use provider fallbacks and are not the public contract.

Compute actions

/api/correlation, /api/correlation/matrix

App actions that can compute and persist correlations. These are not read-only public v1 routes.

Loading market view

BASE="https://www.corrlens.com/api/v1" curl -s "$BASE/universe?provider=fred&q=CPIAUCSL" | jq . curl -s "$BASE/symbols?provider=stock&q=AAPL&limit=3" | jq . curl -s "$BASE/symbols/stock/AAPL?limit=10" | jq . curl -s "$BASE/pairs/stock/AAPL/stock/MSFT?preview=1" | jq .

curl -s -X POST "https://www.corrlens.com/api/v1/pairs" \ -H "Content-Type: application/json" \ -d '{ "includePreview": false, "pairs": [ [ { "provider": "stock", "id": "AAPL" }, { "provider": "stock", "id": "MSFT" } ], { "seriesA": "stock:NVDA", "seriesB": "fred:CPIAUCSL" } ] }' | jq .

{ "object": "data_universe", "version": "2026-05-09", "filters": { "provider": "fred", "q": "CPIAUCSL" }, "totals": { "stocks": 1371, "crypto": 25, "fred": 1214, "total": 2610 }, "counts": { "stocks": 0, "crypto": 0, "fred": 1, "total": 1 }, "data": { "stocks": [], "crypto": [], "fred": [{ "object": "universe_symbol", "provider": "fred", "id": "CPIAUCSL", "name": "Consumer Price Index for All Urban Consumers", "group": "inflation" }] } }

{ "object": "symbol", "provider": "stock", "id": "AAPL", "name": "Apple Inc.", "group": "Technology", "partnerCount": 1240, "correlations": { "object": "list", "limit": 10, "offset": 0, "data": [{ "object": "symbol_correlation", "partner": { "provider": "stock", "id": "MSFT", "name": "Microsoft Corporation" }, "correlation": 0.59, "absCorrelation": 0.59, "syncRate": 0.58, "overlapPoints": 1258, "links": { "web": "/correlations/AAPL/MSFT", "api": "/api/v1/pairs/stock/AAPL/stock/MSFT" } }] } }

{ "object": "correlation_pair", "seriesA": { "provider": "stock", "id": "AAPL", "name": "Apple Inc." }, "seriesB": { "provider": "stock", "id": "MSFT", "name": "Microsoft Corporation" }, "window": "5Y", "alignmentMode": "daily", "correlation": 0.59, "absCorrelation": 0.59, "syncRate": 0.58, "overlapPoints": 1258, "stats": { "r2": 0.35, "pValue": 0.001 }, "links": { "web": "/correlations/AAPL/MSFT", "api": "/api/v1/pairs/stock/AAPL/stock/MSFT" } }