fAlpha Health API

openapi: 3.2.0
info:
  title: fAlpha.ai Health API
  description: 'Welcome to the fAlpha.ai API. Access trading signals, daily sentiment scores, and scraped news articles for S&P 500 tickers and beyond. API access is currently available to enterprise users only. Please contact info@bam.money to request access. By using the API, you consent to the Terms of Service and Privacy Policy. ## Interactive Docs Guidance


    Use `/docs` for quick, small validation requests. For larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy. Current date-range and size caps are:


    - `GET /signals-history/{ticker}`: up to **365 days**

    - `GET /signals-history-batched`: up to **90 days**

    - `GET /signals-history-all`: up to **30 days**

    - `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)

    - `GET /screener`: up to **50 rows** per call


    After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive. ## Data Dictionary


    The API currently returns the following response fields:


    | Field | Meaning |

    | --- | --- |

    | `ticker` | Security ticker symbol, for example `AAPL`. |

    | `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |

    | `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |

    | `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |

    | `signal` | Trading direction returned by the model: `buy` or `sell`. |

    | `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |

    | `sentiment` | News sentiment paired with the signal: the **previous calendar day''s** finalized average score (news is crawled overnight — including weekends — so day D''s sentiment isn''t ready when the day-D signal is produced; the most recent finalized reading is D-1''s). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a "not computed" sentinel and is always surfaced as `null`). |

    | `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |

    | `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |

    | `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |

    | `quality.iis_score` | Information-strength score for the signal at this horizon. |

    | `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |

    | `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |

    | `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |

    | `performance.pnl` | Realized signal-following PnL for the row''s horizon. |

    | `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |

    | `performance.release_date` | When realized returns were backfilled for the row. |

    | `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |

    | `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |

    | `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved.'
  termsOfService: https://bam.money/terms
  contact:
    name: fAlpha.ai
    url: https://bam.money/contact
    email: info@bam.money
  version: 0.2.0
servers:
- url: https://api.falpha.ai
  description: fAlpha.ai API server
tags:
- name: Health
paths:
  /health:
    get:
      tags:
      - Health
      summary: Health
      description: Liveness/readiness probe. No authentication and no rate limit. Reports API status and Mongo reachability.
      operationId: health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
x-topics:
- title: Getting Started
  content: '

    To get started, contact the fAlpha.ai team to provision enterprise API access and an API key.


    1. Contact [info@bam.money](mailto:info@bam.money)

    2. Receive your enterprise API credentials

    3. Use your API key to access the API

    '
- title: Authentication
  content: '

    The fAlpha.ai API uses API keys to authenticate requests. Send your key in the `X-API-Key` request header (preferred):


    ```

    curl -H "X-API-Key: YOUR_KEY" https://api.falpha.ai/signals/NVDA

    ```


    The legacy `api_key` query parameter is still accepted for backward compatibility. Prefer the header: query strings tend to be captured in proxy/server logs and browser history. When both are sent, the header wins.


    > info

    > Your API keys carry many privileges, so be sure to keep them secure! **Do not share your API keys** in publicly accessible areas such as GitHub, client-side code, and so forth.

    '
- title: Rate Limits
  content: '

    The fAlpha.ai API enforces rate limits per API key:


    - **10 requests per second** (burst cap)

    - **300 requests per minute** (sustained cap)


    If you exceed either limit, you will receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying.


    The official Python SDK and Excel add-in pace themselves within these limits automatically (client-side token buckets, request batching, and `Retry-After`-aware retries), so a 100-ticker watchlist still resolves in a single request via `GET /signals-batched`.

    '
- title: Client Surfaces (SDK & Excel)
  content: '

    Three first-party client surfaces wrap this API:


    - **Python SDK (`falpha`)** — a typed client with client-side rate limiting, retries, pandas integration, analytics helpers (screener, signal flips, regime consensus, pre-trade validation), and a CLI.

    - **Excel add-in** — `=FALPHA.*` custom functions (single cells, spilled history, watchlists, screener) plus a task pane with account, usage, and pre-trade validation panels.

    - **Google Sheets add-on** — `FALPHA_*` custom functions and a sidebar with the same watchlist / validator / screener / usage workflows.


    Each sends an `X-Falpha-Surface` header (`sdk-python` / `excel` / `sheets`) so `GET /account/usage` can meter usage per surface. Direct integrations may omit the header (metered as `api`).

    '
- title: Interactive Docs Guidance
  content: '

    ## Interactive Docs Guidance


    Use `/docs` for quick, small validation requests.


    For larger batched queries or longer date ranges, prefer the generated `curl` command or call the endpoint URL directly from your browser or API client. Large JSON responses can make the interactive Swagger UI sluggish even when the API itself is healthy.


    Current date-range and size caps are:


    - `GET /signals-history/{ticker}`: up to **365 days**

    - `GET /signals-history-batched`: up to **90 days**

    - `GET /signals-history-all`: up to **30 days**

    - `GET /signals-batched`: up to **100 tickers** per call (latest signal per ticker)

    - `GET /screener`: up to **50 rows** per call


    After a large test, click **Clear** for that operation or refresh the page to keep the interactive docs responsive.

    '
- title: Enterprise Access
  content: '

    The API is currently available to enterprise users only. To access data (including sentiment scores and summaries) for our full corpus of 16,000+ tickers, please contact [info@falpha.ai](mailto:info@falpha.ai).

    '
- title: Data Timing
  content: '

    - **Signal dates** reflect the model run date (UTC). A signal dated 2026-04-14 uses market data available as of that date; prices in the signal correspond to the previous trading day''s close.

    - **Sentiment scores** and **articles** correspond to the crawl calendar day (UTC midnight). The crawl runs overnight (including weekends), so a signal''s paired `sentiment` is the **previous calendar day''s** finalized score, not the signal date''s. Up to 10 articles per ticker per day are scraped.

    - **Realized performance fields** (`include_performance=true`) are backfilled after each horizon completes, so the most recent history rows return `null` values until returns are realized.

    - All timestamps in API responses are in UTC.

    '
- title: Data Dictionary
  content: '

    ## Data Dictionary


    The API currently returns the following response fields:


    | Field | Meaning |

    | --- | --- |

    | `ticker` | Security ticker symbol, for example `AAPL`. |

    | `date` | For signals: the model run date in UTC. For articles: the crawl date in UTC. |

    | `period` | Signal forecast horizon. Current supported values are `5d`, `15d`, and `2m`. |

    | `regime` | Market regime used for the signal model: `neutral`, `bear`, or `bull`. |

    | `signal` | Trading direction returned by the model: `buy` or `sell`. |

    | `confidence` | Absolute value of the signal score used to rank signal strength. Recent rows use the index-adjusted score; older historical rows may fall back to the raw score when adjusted data is unavailable. |

    | `sentiment` | News sentiment paired with the signal: the **previous calendar day''s** finalized average score (news is crawled overnight — including weekends — so day D''s sentiment isn''t ready when the day-D signal is produced; the most recent finalized reading is D-1''s). Returns `null` when that reading is unavailable (internally, a stored score of `10.0` is a "not computed" sentinel and is always surfaced as `null`). |

    | `quality` | Optional block of signal quality metrics. `null` unless the request sets `include_quality=true`; individual metrics may still be `null` when unavailable for a row. |

    | `quality.sharpe_ratio` | Risk-adjusted measure of the signal''s recent strength (a Sharpe-ratio proxy). Higher is better; can be negative. |

    | `quality.sortino_ratio` | Downside-risk-adjusted counterpart to the Sharpe ratio. |

    | `quality.iis_score` | Information-strength score for the signal at this horizon. |

    | `quality.normalized_iis` | IIS score normalized for cross-ticker comparison. |

    | `quality.percent_positive_pnl` | Percentage of recent signal-following outcomes with positive PnL (0–100). |

    | `performance` | Optional realized-performance block on history rows. `null` unless the request sets `include_performance=true`. Values are backfilled once returns are realized, so recent rows return `null` fields. |

    | `performance.pnl` | Realized signal-following PnL for the row''s horizon. |

    | `performance.ticker_return` / `performance.index_return` | Realized gross-return ratios over the horizon for the ticker and the benchmark index (`1.05` = +5%). |

    | `performance.release_date` | When realized returns were backfilled for the row. |

    | `as_of` | Screener responses: the model-run date of the screened signal cube (the latest available). |

    | `surface` | Usage metering: originating client surface — `excel`, `sheets`, `sdk-python`, `zapier`, or `api` (default) — attributed via the optional `X-Falpha-Surface` request header. |

    | `by_client` | Usage metering: split by anonymous install id (optional `X-Falpha-Client` header; each add-in install / spreadsheet generates its own). No user accounts involved. |

    | `predictions` | Historical array of signal rows for a ticker. |

    | `count` | Number of articles returned in an articles response. |

    | `articles` | Array of article objects returned by the articles endpoint. |

    | `title` | Article headline. |

    | `score` | Sentiment score for an individual article. |

    | `source` | Source domain or publisher for the article. |

    | `summary` | AI-generated summary for the article when available. |

    | `link` | Canonical article URL. |

    | `account` | Role, access, and subscription metadata for the caller. Returned by `GET /account` and available to any authenticated API key, including non-enterprise ones. |

    '