API Documentation

The API is organized around REST. It uses resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

Base URL: https://finance.alpevox.ai/api/v1

Authentication

All requests require an Authorization header with a Bearer token. Generate a key from your sign up after signing up.

Authorization: Bearer avx_your_api_key

Errors

Errors return { "error": { "message", "code" } } with a matching status: 401 invalid key, 403 tier restriction, 429 rate limit, 404 not found, 503 price cache not yet populated.

GET/companiesAll plans

Search companies by name/ticker, filter by sector, paginate.

Query params: sector, search, limit, offset

Request

curl https://finance.alpevox.ai/api/v1/companies?sector=Technology \
  -H "Authorization: Bearer avx_..."

GET/companies/{ticker}All plans

Single company profile: name, sector, CIK, coverage dates.

Request

curl https://finance.alpevox.ai/api/v1/companies/AAPL \
  -H "Authorization: Bearer avx_..."

GET/sectorsAll plans

Distinct sectors with company counts, for building filter UIs.

Request

curl https://finance.alpevox.ai/api/v1/sectors \
  -H "Authorization: Bearer avx_..."

GET/metricsAll plans

Catalog of all 52 fundamental metrics with descriptions.

Request

curl https://finance.alpevox.ai/api/v1/metrics \
  -H "Authorization: Bearer avx_..."

GET/fundamentals/{ticker}All plans

Time series of fundamentals. Filter by metric and fiscal period.

Query params: metric, period, limit

Request

curl "https://finance.alpevox.ai/api/v1/fundamentals/AAPL?metric=revenue&period=FY" \
  -H "Authorization: Bearer avx_..."

GET/fundamentals/{ticker}/latestAll plans

Most recent value for every metric - a single company snapshot.

Request

curl https://finance.alpevox.ai/api/v1/fundamentals/AAPL/latest \
  -H "Authorization: Bearer avx_..."

GET/compareAll plans

One metric, several tickers, side by side.

Query params: tickers, metric, period, limit

Request

curl "https://finance.alpevox.ai/api/v1/compare?tickers=AAPL,MSFT,GOOGL&metric=revenue" \
  -H "Authorization: Bearer avx_..."

GET/screenerPro+ only

Filter companies by a fundamental metric OR a valuation ratio (pe, pb, ps, ev_ebitda) against a threshold.

Query params: metric, op (gt/gte/lt/lte/eq), value, sector, limit

Request

# Valuation ratio (uses cached daily price)
curl "https://finance.alpevox.ai/api/v1/screener?metric=pe&op=lt&value=20" \
  -H "Authorization: Bearer avx_..."

GET/valuation/{ticker}All plans

Live P/E, P/B, P/S, EV/EBITDA for a single company. Price is fetched fresh from Alpaca on every request, not cached.

Request

curl https://finance.alpevox.ai/api/v1/valuation/AAPL \
  -H "Authorization: Bearer avx_..."

GET/ratios/{ticker}All plans

Liquidity, solvency, profitability ratios, and full DuPont ROE breakdown. No market data needed.

Request

curl https://finance.alpevox.ai/api/v1/ratios/AAPL \
  -H "Authorization: Bearer avx_..."

GET/growth/{ticker}All plans

YoY growth per year and CAGR across the window, for any metric. Annual (FY) figures only.

Query params: metric (default: revenue), years (default: 5, max: 15)

Request

curl "https://finance.alpevox.ai/api/v1/growth/AAPL?metric=revenue&years=5" \
  -H "Authorization: Bearer avx_..."

GET/insider-trades/{ticker}Pro+ only

Officer, director, and 10% owner stock transactions from Form 4 filings.

Query params: start, end, limit

Request

curl "https://finance.alpevox.ai/api/v1/insider-trades/AAPL?start=2025-01-01" \
  -H "Authorization: Bearer avx_..."

GET/filings/{ticker}All plans

List of SEC filings (10-K, 10-Q, 8-K, etc.) with dates and direct links to each document.

Query params: form, limit

Request

curl "https://finance.alpevox.ai/api/v1/filings/AAPL?form=10-K&limit=5" \
  -H "Authorization: Bearer avx_..."

GET/news/{ticker}Pro+ only

Recent company news headlines and articles, sourced from Alpaca.

Query params: limit, start, end

Request

curl "https://finance.alpevox.ai/api/v1/news/AAPL?limit=10" \
  -H "Authorization: Bearer avx_..."