API and MCP docs

Base URL https://api.veritasdata.dev. Full schema at /openapi.json; a plain-text guide for language models at /llms.txt.

Endpoints

Base URL https://api.veritasdata.dev. Every endpoint takes an X-API-Key header; sign in for a free key (100 calls) or a plan. Full schema at /openapi.json; a plain-text guide for language models at /llms.txt.

Endpoint	Returns	Key
`GET /v1/next/{ticker}`	Next event: date, BMO/AMC, status, confidence, call time, webcast, source	required
`GET /v1/history/{ticker}`	Past releases with weekday, timing, days after period end, 8-K link	required
`GET /v1/company/{ticker}`	CIK, exchange, market-cap bucket, EDGAR link	required
`GET /v1/calendar?from=&to=&status=&cap=`	Events in a window of up to 120 days, filterable by status and cap (small, mid, large, mega)	required
`GET /v1/changes?since=&ticker=`	Dates that moved, were confirmed, conflicted or were reported since a timestamp	required

First call

# free key: sign in at veritasdata.dev/login/
curl -H "X-API-Key: vt_live_..." \
  https://api.veritasdata.dev/v1/next/ACME

Python

import httpx

r = httpx.get("https://api.veritasdata.dev/v1/next/ACME",
              headers={"X-API-Key": "vt_live_..."})
e = r.json()
print(e["report_date"], e["timing"], e["status"])
# 2026-11-04 AMC confirmed
if e["status"] != "confirmed":
    print("not confirmed yet; see", e["source_url"])

What status means

confirmed	The company announced this date. `source_url` is the announcement.
estimated	Projected from filing cadence. Not company-confirmed. `confidence` is 0 to 1.
conflict	Two company sources disagree. `report_date` is the last confirmed one; verify before relying on it.
reported	Results are out. `report_date` is the actual release date from the 8-K.

Changes feed

curl -H "X-API-Key: vt_live_..." \
  "https://api.veritasdata.dev/v1/changes?since=2026-10-01T00:00:00Z"

# each change: ticker, fiscal_period, old_date, new_date,
# old_status, new_status, change_type, source_url

Keys and limits

Send your key in an X-API-Key header (or Authorization: Bearer). Sign in with GitHub or Google for a free key: every company, 100 calls in total. Plans raise that to a daily allowance.

Response	Meaning
`401`	No key, or a revoked one.
`402`	A free account's 100 calls are used. The body links to `/pricing/`.
`400`	An unknown `cap` value; the body lists the buckets.
`429`	Your plan's daily limit is reached.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; free keys add X-RateLimit-Scope: lifetime. Public, no key: /v1/packages (prices), /v1/coverage (coverage and accuracy), /health, /status.

Status meanings

`confirmed`	The company announced the date; `source_url` is the announcement. Cite it.
`estimated`	Projected from the company's filing cadence, with a `confidence` (probability of landing within a day). Not company-confirmed; never present it as fact.
`conflict`	Company sources disagree; `report_date` is the last confirmed date. Verify before relying on it.
`reported`	Results are out; `report_date` is the actual release date from the filing.
`unknown`	Not enough history (or a foreign issuer not yet supported); no date rather than a guess.

In Claude, Cursor and other MCP clients

The same data as four tools: get_next_earnings, list_earnings, get_date_changes, get_earnings_history. The tool descriptions tell the model that an estimated date is a projection and to cite source_url, so the answers it gives you carry the same caveats the API does.

Ask things like "when does ACME report next and is it confirmed?" or "which small caps moved their earnings date this week?"

Remote server

{
  "mcpServers": {
    "veritas": {
      "type": "http",
      "url": "https://api.veritasdata.dev/mcp",
      "headers": { "X-API-Key": "vt_live_..." }
    }
  }
}

Local (stdio)

pip install veritas-earnings

{ "mcpServers": { "veritas": { "command": "veritas", "args": ["mcp"] } } }

Quickstart

Sign in with GitHub or Google. Your free key (every company, 100 calls) is shown once and listed in your account.
Call GET https://api.veritasdata.dev/v1/next/AAPL with header X-API-Key: vt_live_….
Read status before you use report_date: only confirmed is a company statement. Cite source_url.
Need more than 100 calls? Plans start at $19 a month; every plan covers every company.

Parsed results beta

GET /v1/results/{ticker}?limit=8 returns the last releases read from the company's own press release (the 8-K Item 2.02 exhibit): revenue and EPS (GAAP and non-GAAP) with the sentence each came from, guidance sentences verbatim, call time, webcast and the EDGAR exhibit URL. When the 10-Q or 10-K is filed, the XBRL figure sits next to ours and any disagreement is flagged rather than resolved. Null means the release did not state it in a form we read. Beta: we publish the read rate and match rate against XBRL before calling it stable; until both pass our bar (read ≥ 80%, match ≥ 97% for revenue and EPS) treat each number as something to verify against the cited sentence.

Connect from Claude, ChatGPT or Cursor

The MCP endpoint https://api.veritasdata.dev/mcp accepts either an X-API-Key header or OAuth 2.1 (authorization code with PKCE, dynamic client registration). Connector directories use OAuth: add the server URL in your client, sign in when asked, and choose which of your keys the connector should use. The connector then has exactly that key's limits; revoke the key to disconnect it.

Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Scope: earnings:read. Tokens live one hour and refresh for thirty days.

Accuracy methodology

Every past release in the window is replayed: we rewind to five days after the quarter ended, run the estimator on only the filings visible then, and compare the projected date with the actual 8-K date. Percentages are of all releases, so a release we gave no estimate for counts as a miss. The run repeats weekly and is served at /v1/coverage; the figures on the home page come from it. confidence is calibrated to this test: in each band, the mean confidence tracks the share of estimates that landed within one day.

Changelog

2026-11-08 Data packages retired: every plan sees the whole universe. Universe widened to every US-listed operating company worth $300M or more (3,216 companies). Accounts with GitHub and Google sign-in; free tier is 100 calls in total. OAuth 2.1 for the MCP endpoint. Parsed earnings releases (/v1/results). Public coverage and accuracy figures. Company IR sites read for date announcements.
2026-11-07 Data packages by company size; self-serve checkout; MCP tool annotations and registry manifest; full EDGAR history back to 2004.