# FinData OS — API quick start

Base URL: `https://findata.spboucher.ai/api/v1` · OpenAPI: `/api/v1/openapi.json` · Swagger UI: `/api/docs`
Auth: `Authorization: Bearer fd_<prefix>.<secret>` (create keys in the console → API keys). Browser sessions use the cookie + `X-CSRF-Token`.
Conventions: UTC ISO-8601 (`Z`), bars stamped at **bar open**, cursor pagination (`next_cursor`), structured errors `{"error":{"code","message","request_id"}}`, response headers `X-Request-ID`, `X-Dataset-Id`, `X-Dataset-Version`.

```bash
K=fd_xxx.yyy
curl -s -H "Authorization: Bearer $K" https://findata.spboucher.ai/api/v1/catalog/datasets | jq '.data[] | {id,status,license_class}'
curl -s -H "Authorization: Bearer $K" "https://findata.spboucher.ai/api/v1/market/bars?symbol=AAPL&interval=1m&start=2026-10-30&end=2026-10-30&limit=5" | jq .
curl -s -H "Authorization: Bearer $K" "https://findata.spboucher.ai/api/v1/fundamentals/AAPL?as_of=2025-01-01T00:00:00Z&metrics=rev,net_inc" | jq '.data[0], .meta'
curl -s -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -d '{"sql":"SELECT symbol_as_reported, count(*) FROM market_bars_stock_1m_raw GROUP BY 1 ORDER BY 2 DESC LIMIT 5"}' https://findata.spboucher.ai/api/v1/query | jq .rows
curl -s -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -d '{"dataset_id":"market_bars.stock.1m.raw","symbols":["AAPL","MSFT"],"start":"2026-10-01","end":"2026-10-30"}' https://findata.spboucher.ai/api/v1/exports   # 202 → poll /exports/{id} → /download
```

Python SDK (`packages/python-sdk`, `pip install -e packages/python-sdk`):
```python
from findata_sdk import FinData
fd = FinData("https://findata.spboucher.ai", api_key="fd_xxx.yyy")
bars = fd.bars("AAPL", "1m", "2026-10-26", "2026-10-30")        # pyarrow.Table (Arrow IPC pages)
df = bars.to_pandas()
path = fd.export(["AAPL", "MSFT"], "2024-01-01", "2026-10-30")     # async Parquet export → local file
facts = fd.fundamentals("AAPL", as_of="2025-01-01T00:00:00Z", metrics=["rev", "eps_d"])
```

Limits: 1m bars ≤ 31 days per call (5m ≤ 186 d, 1d ≤ 10 y), ≤ 10 000 rows per page → use exports for larger ranges. Query playground: one read-only statement, 30 s, ≤ 100 000 rows. Rate limit 600 req/min per key (configurable per key). License: FirstRate Data private use — do not redistribute raw data.