API

Corrlens API reference

A small JSON API for stored Corrlens data: discover available symbols, fetch one symbol network, fetch one pair, or post a batch of pairs for correlation lookup.

Base

/api/v1

Auth

None

Window

5Y

Endpoints

GET/api/v1/attributes

Attributes reference

Provider names, alignment modes, pair attributes, symbol attributes, and API limits.

GET/api/v1/symbols

Available symbols

Paginated list of symbols with stored correlations. Filter by provider, search text, limit, and offset.

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

Symbol data

Symbol metadata plus top correlation partners from the stored Corrlens universe.

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

Pair data

Fetch one stored correlation pair. Add preview=1 when you need the sampled chart points.

POST/api/v1/pairs

Batch pair lookup

Post up to 25 pairs and receive found/not-found results without computing new data.

Symbols

Use GET /symbols for the available symbols list. Supported query parameters are provider, q, limit, and offset.

Providers are stock, crypto, and fred. Stock and crypto IDs are uppercase symbols. FRED IDs are uppercase series IDs.

Symbol response shape

{
  "object": "symbol",
  "provider": "stock",
  "id": "AAPL",
  "name": "Apple Inc.",
  "group": "Technology",
  "partnerCount": 1240,
  "correlations": {
    "object": "list",
    "data": [
      {
        "object": "symbol_correlation",
        "partner": { "provider": "stock", "id": "MSFT" },
        "correlation": 0.59,
        "absCorrelation": 0.59,
        "syncRate": 0.58,
        "overlapPoints": 1258,
        "alignmentMode": "daily"
      }
    ]
  }
}

POST /api/v1/pairs request

{
  "pairs": [
    {
      "a": { "provider": "stock", "id": "AAPL" },
      "b": { "provider": "stock", "id": "MSFT" }
    },
    ["stock:AAPL", "stock:SPY"]
  ],
  "includePreview": false
}

POST /api/v1/pairs response

{
  "object": "list",
  "data": [
    {
      "object": "pair_lookup",
      "requested": {
        "seriesA": { "provider": "stock", "id": "AAPL" },
        "seriesB": { "provider": "stock", "id": "MSFT" }
      },
      "found": true,
      "pair": {
        "object": "correlation_pair",
        "correlation": 0.59,
        "absCorrelation": 0.59,
        "overlapPoints": 1258,
        "dateRange": { "start": "2021-05-05", "end": "2026-05-05" }
      }
    }
  ]
}

Attributes

Pair fields

  • correlation: Pearson r from -1 to 1
  • absCorrelation: ranking strength
  • syncRate: same-direction move share
  • overlapPoints: aligned sample count
  • dateRange: aligned start and end
  • stats: regression and lag summary

Symbol fields

  • provider: stock, crypto, or fred
  • id: canonical symbol or series ID
  • name: display name
  • group: sector or category
  • country: FRED country code when present
  • partnerCount: stored pair count

Limits

  • GET /symbols default limit: 50
  • GET /symbols max limit: 500
  • GET /symbols/{provider}/{id} default limit: 25
  • Symbol partner max limit: 200
  • POST /pairs max batch: 25

The full machine-readable reference is available at /api/v1/attributes.

Testing

Start the app with npm run dev, then run these smoke tests against localhost.

A missing stored pair returns 404 not_found. Batch lookups return found: false for individual misses.

Smoke tests

curl -s http://localhost:3000/api/v1/attributes | jq .

curl -s "http://localhost:3000/api/v1/symbols?provider=stock&q=AAPL&limit=3" | jq .

curl -s "http://localhost:3000/api/v1/symbols/stock/AAPL?limit=5" | jq .

curl -s "http://localhost:3000/api/v1/pairs/stock/AAPL/stock/MSFT?preview=1" | jq .

curl -s -X POST http://localhost:3000/api/v1/pairs \
  -H "Content-Type: application/json" \
  -d '{"pairs":[{"a":{"provider":"stock","id":"AAPL"},"b":{"provider":"stock","id":"MSFT"}}]}' | jq .