API reference overview

The David API is a REST API that returns JSON. Every endpoint is scoped to a scenario and reads like a conventional market-data API.

Each example shows cURL and Python. The Python tab uses the official SDK and assumes a configured client: from david_data import DavidData; dd = DavidData().

Base URL

https://api.davidhf.com

All requests go to this host over HTTPS.

Authentication

Send your key in the X-API-KEY header on every request. See Authentication.

curl -s "https://api.davidhf.com/scenarios" \
  -H "X-API-KEY: your-api-key"

dd.scenarios.list()

The `scenario_id` parameter

Almost every data endpoint requires a scenario_id query parameter identifying the world to read from. David generates and curates the scenarios; obtain a scenario_id by listing scenarios.

curl -s "https://api.davidhf.com/prices?scenario_id=<scenario_id>&ticker=AAPL" \
  -H "X-API-KEY: your-api-key"

dd.prices.get("AAPL", scenario_id="<scenario_id>")

Response shape

Responses are JSON objects keyed by the resource name, with the payload as a list or object:

{ "prices": [ { "ticker": "AAPL", "close": 183.6, "time": "2026-01-02" } ] }

List endpoints return their rows under a named key (prices, news, financials, companies, …). Detail endpoints return a single named object.

Shared query parameters

Parameter	Type	Description
`scenario_id`	string	Required on data endpoints. The world to read from.
`ticker`	string	Symbol to filter by. Case-insensitive; normalized (e.g. `BRK.B` → `BRK-B`).
`limit`	integer	Page size. Each endpoint documents its default and maximum.
`offset`	integer	Number of rows to skip, for pagination.
`as_of`	date	Point-in-time cutoff (`YYYY-MM-DD`). Returns only data visible on or before this date.
`start_date` / `end_date`	date	Inclusive window for time-series endpoints.

See Date semantics for how dates and visibility work.

Pagination

List endpoints page with limit and offset. To walk a full result set, increase offset by limit until a short page returns:

curl -s "https://api.davidhf.com/companies?scenario_id=<id>&limit=100&offset=0" \
  -H "X-API-KEY: your-api-key"
curl -s "https://api.davidhf.com/companies?scenario_id=<id>&limit=100&offset=100" \
  -H "X-API-KEY: your-api-key"

dd.company.list(scenario_id="<id>", limit=100, offset=0)
dd.company.list(scenario_id="<id>", limit=100, offset=100)

Rate limits & errors

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-Account-ID. See Errors & rate limits for status codes and handling.

Overview

Scenarios

Company

Prices

Financials

Earnings & estimates

Disclosures

Ownership

Market & macro

API reference overview

Base URL

Authentication

The `scenario_id` parameter

Response shape

Shared query parameters

Rate limits & errors

Endpoint groups

Scenarios

Company

Prices

Financial statements

Financial metrics

Search & screener

Earnings

KPIs & guidance

Analyst estimates

News & notes

SEC filings

Insider trades

Institutional holdings

Index funds

Macro & rates

Corporate actions

Events

​Base URL

​Authentication

​The scenario_id parameter

​Response shape

​Shared query parameters

​Pagination

​Rate limits & errors

​Endpoint groups

Scenarios

Company

Prices

Financial statements

Financial metrics

Search & screener

Earnings

KPIs & guidance

Analyst estimates

News & notes

SEC filings

Insider trades

Institutional holdings

Index funds

Macro & rates

Corporate actions

Events

Base URL

Authentication

The `scenario_id` parameter

Response shape

Shared query parameters

Pagination

Rate limits & errors

Endpoint groups