API Guide

Excluded from the conditional-GET scheme carried by catalog, universe, symbols and symbols/<symbol>: no ETag, no If-None-Match handling.

200 — Cache-Control: no-store
{
  "data": {
    "user_id": 7,
    "is_premium": false,
    "credit_balance": 42,
    "permissions": ["stocksfast.read_market", "stocksfast.execute_scan"],
    "key": {"id": 41, "label": "mcp-laptop", "prefix": "9f2c1a04",
            "created_at": 1755683642, "expires_at": 1763453642,
            "last_used_at": 1755690118},
    "limits": {
      "execute": {"limit": 20, "window_seconds": 60},
      "validate": {"limit": 30, "window_seconds": 60},
      "read": {"limit": 120, "window_seconds": 60},
      "crud_read": {"limit": 90, "window_seconds": 60},
      "crud_write": {"limit": 40, "window_seconds": 60}
    }
  }
}

200
{
  "openapi": "3.0.3",
  "info": { … },
  "paths": { … },
  "components": { … }
}

The body is the document itself — openapi/info/paths/components at the top level, not the {"data": …} envelope every other route on this page answers with. Compiled-in reference data, fixed for the life of the server process. Every 200 carries ETag and Cache-Control: public, max-age=3600; send the ETag back as If-None-Match and a match answers 304 with no body.

200
{
  "data": {
    "functions": [
      {
        "name": "sma",
        "signature": "sma(source, length)",
        "summary": "Simple moving average over the last `length` bars.",
        "args": [{"name": "source", "type": "field", "required": true}],
        "kwargs": [],
        "examples": ["close > sma(close, 50);"]
      }
    ],
    "operators": [
      {
        "operator": ">",
        "description": "Greater than",
        "category": "comparison",
        "example": "close > 50",
        "function_equiv": "gt(a, b)"
      }
    ],
    "fields": [
      {"name": "close", "category": "Price & Volume"}
    ],
    "timeframes": [
      {"code": "1D", "label": "Daily"}
    ]
  }
}

Compiled-in reference data, fixed for the life of the server process. Every 200 carries ETag and Cache-Control: public, max-age=3600; send the ETag back as If-None-Match and a match answers 304 with no body.

200
{
  "data": {
    "universe_size": 8412,
    "last_available_date": "2026-08-19",
    "timeframes": [{"code": "1D", "label": "Daily"}]
  }
}

A strong ETag derived from the publish generation (universe_size, last_available_date) and the compiled-in timeframes table, rather than the rendered bytes, and Cache-Control: public, max-age=60; send the ETag back as If-None-Match and a match answers 304 with no body. Neither header appears on the 503 or the 500.

200
{
  "data": [
    {"symbol": "AAPL", "name": "Apple Inc.",
     "asset_type": "stock"}
  ],
  "page": {"limit": 2, "offset": 0, "total": 1}
}

A strong ETag that is a digest of the rendered response bytes, so it moves whenever a row's own content changes even with q/limit/offset held fixed, and Cache-Control: public, max-age=60; send the ETag back as If-None-Match and a match answers 304 with no body. Neither header appears on the 500.

200
{
  "data": {"symbol": "AAPL", "name": "Apple Inc.",
           "asset_type": "stock"}
}

A strong ETag that is a digest of the rendered response bytes, so it moves whenever the row's own content changes even with the symbol held fixed, and Cache-Control: public, max-age=60; send the ETag back as If-None-Match and a match answers 304 with no body. Neither header appears on the 404 or the 500.

200
{
  "data": {
    "expression": "close > sma(close, 50)",
    "timeframe": "1D",
    "scan_date": "2026-09-03"
  },
  "warnings": []
}

200
{
  "data": [
    {
      "symbol": "AAPL",
      "close": 231.40,
      "volume": 54210033,
      "dollar_volume": 12544400637.2
    }
  ],
  "page": {"limit": 2, "offset": 0, "total": 137},
  "warnings": [
    {"code": "W5001", "message": "Standalone nullable function 'pivothigh(...)' filters to non-NULL values. Use '== null' or '!= null' for explicit comparison.", "line": 1, "column": 25}
  ]
}

No server-side cutoff bounds how long this call can take — see Execution model for the measured worst case and what a timeout does and does not protect against.

200
{
  "data": [
    {
      "symbol": "AAPL",
      "close": 231.40,
      "volume": 54210033,
      "dollar_volume": 12544400637.2
    }
  ],
  "page": {"limit": 2, "offset": 0, "total": 137},
  "warnings": [
    {"code": "W5001", "message": "Standalone nullable function 'pivothigh(...)' filters to non-NULL values. Use '== null' or '!= null' for explicit comparison.", "line": 1, "column": 28}
  ]
}

200
{
  "data": [
    {"id": 41, "name": "Momentum breakout", "description": "",
           "expression": "close > sma(close, 50)", "is_favorite": false, "is_public": false,
           "created_at": 1755683642, "updated_at": 1755683642,
           "last_executed_at": 1755690118, "tags": ["momentum"]}
  ],
  "page": {"limit": 50, "offset": 0, "total": 3}
}

201
{
  "data": {"id": 41, "name": "Momentum breakout", "description": "",
           "expression": "close > sma(close, 50)", "is_favorite": false, "is_public": false,
           "created_at": 1755683642, "updated_at": 1755683642,
           "last_executed_at": null, "tags": ["momentum"]}
}

200
{
  "data": {"id": 41, "name": "Momentum breakout", "description": "",
           "expression": "close > sma(close, 50)", "is_favorite": false, "is_public": false,
           "created_at": 1755683642, "updated_at": 1755683642,
           "last_executed_at": 1755690118, "tags": ["momentum"]}
}

200
{
  "data": {"id": 41, "name": "Momentum breakout", "description": "",
           "expression": "close > sma(close, 50)", "is_favorite": false, "is_public": false,
           "created_at": 1755683642, "updated_at": 1755690118,
           "last_executed_at": 1755690118, "tags": ["momentum"]}
}

204

200
{
  "data": [{"id": 12, "name": "Momentum", "slug": "momentum", "created_at": 1755683642}],
  "page": {"limit": 50, "offset": 0, "total": 4}
}

201
{
  "data": {"id": 12, "name": "Momentum", "slug": "momentum", "created_at": 1755683642}
}

200
{
  "data": {"id": 12, "name": "Momentum", "slug": "momentum", "created_at": 1755683642}
}

200
{
  "data": {"id": 12, "name": "Momentum breakouts", "slug": "momentum-breakouts",
           "created_at": 1755683642}
}

204

200
{
  "data": [
    {"id": 7, "name": "Swing candidates",
     "created_at": 1755683642, "updated_at": 1755683642}
  ],
  "page": {"limit": 50, "offset": 0, "total": 2}
}

201
{
  "data": {"id": 7, "name": "Swing candidates",
           "created_at": 1755683642, "updated_at": 1755683642,
           "symbols": ["AAPL", "MSFT"]}
}

200
{
  "data": {"id": 7, "name": "Swing candidates",
           "created_at": 1755683642, "updated_at": 1755683642,
           "symbols": ["AAPL", "MSFT"]}
}

200
{
  "data": {"id": 7, "name": "Swing candidates",
           "created_at": 1755683642, "updated_at": 1755690118,
           "symbols": ["AAPL", "NVDA"]}
}

204

200 — the single-resource envelope
{
  "data": {
    "added_count": 2,
    "skipped_count": 1,
    "invalid_count": 0,
    "watchlist": {
      "id": 7, "user_id": 7, "name": "Swing candidates",
      "created_at": 1755683642,
      "updated_at": 1755690118,
      "symbols": ["AAPL", "MSFT", "NVDA"]
    }
  }
}

200 — the single-resource envelope
{
  "data": {
    "removed_count": 1,
    "watchlist": {
      "id": 7, "user_id": 7, "name": "Swing candidates",
      "created_at": 1755683642,
      "updated_at": 1755697451,
      "symbols": ["AAPL", "MSFT"]
    }
  }
}

200 — text/plain, outside the envelope, with Content-Disposition: attachment
NASDAQ:AAPL
NASDAQ:MSFT
NYSE:BRK.B

200 (add-to-existing) or 201 (create-new) — the single-resource envelope
{
  "data": {
    "watchlist": {
      "id": 9, "user_id": 7, "name": "tv-export",
      "created_at": 1755683642,
      "updated_at": 1755683642,
      "symbols": ["AAPL", "MSFT"]
    },
    "added_count": 2, "skipped_count": 0, "invalid_count": 1,
    "added_symbols": ["AAPL", "MSFT"], "invalid_symbols": ["ZZZZ"],
    "unsupported_count": 1, "unsupported_symbols": ["LSE:VOD"],
    "malformed_count": 1, "malformed_symbols": ["not a line"]
  }
}