Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: alphai REST Calendar API
version: 1.24.0
description: 'Public REST API for alphai''s relevance-scored, ticker-linked financial news.
All endpoints accept `Authorization: Bearer ak_live_…` (issued from your
`/account/api-keys`). Authenticated traffic is metered per account with two
layers — a per-minute burst cap and a per-day volume cap (Free 20/min +
100/day, Basic 60/min + 10,000/day, Pro 150/min + 100,000/day); a request
passes only if both are under budget. The Free tier is for evaluation /
personal non-commercial use; Basic is licensed for internal commercial use;
Pro adds redistribution of the enriched feed. Send all API traffic to
`api.alphai.io`; a key is required on every request.
Every keyed response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`
and `X-RateLimit-Reset`; these report the per-day volume layer (Reset =
epoch seconds of the next 00:00 UTC reset) so you can watch your daily budget
without provoking a 429. A per-minute burst surfaces only as a 429 with a
short `Retry-After`. A 429 body also names your tier, its caps and an
`upgrade` block. The headers reflect origin processing, so a response
served from a shared cache may omit them.
News-archive depth is tiered: Free keys can page the feeds back 30 days,
Basic 90 days, Pro 180 days. Paging past your horizon returns `403`
with an `extra.reason` of `archive_horizon` (see the ArchiveGated response).
Coverage note: our collectors expanded in June 2026, so archive months
before 2026-06 hold fewer articles per day than the current feed.
Insider data (SEC EDGAR Form 4) flows through the same news shape:
`category=insider` rows in the feed, a dedicated `/api/news/insider/`
route, and 30-day per-ticker rollups at
`/api/symbols/{ticker}/insider-summary/`. For charts and analysis there
is `/api/symbols/{ticker}/insider-trades/`: the complete per-ticker
event history with 3m/12m/all-time rollups, weekly and monthly dollar
buckets, and every event of the trailing 12 months in one response.
Market-wide macro coverage (central-bank decisions, CPI/jobs prints,
commodities, geopolitics) is in the feed too, under the `macro_economy`,
`commodities` and `geopolitics` categories and a dedicated
`/api/news/macro/` route. Macro rows are market-wide events, so most
carry an empty `tickers` list — filter them by category, not by symbol.
The forward half of the macro loop is `/api/calendar/`: the official
schedule of upcoming US macro releases (FOMC decisions and minutes, CPI,
PPI, jobs report, GDP estimates, PCE, retail sales, jobless claims,
JOLTS), each with a stable occurrence `uid` that survives reschedules.
Ask the calendar what''s coming, then read `/api/news/macro/` for what a
release meant once it''s out.
Query parameters are validated strictly. An unknown or misspelled
parameter returns 400 naming the field, and the error body carries
`extra.allowed_params` — every parameter that endpoint accepts — so you
never have to guess. Common mix-ups also get a did-you-mean (`limit` and
`per_page` point to `page_size`; `offset`, `page`, `skip` and the
`after_id`/`before_id` family point to `cursor`; `ticker` points to
`symbol`). Parameters that belong to the MCP server rather than to this
API — free-text `q`/`query`/`search`, and `min_actionability` — say so
instead of failing silently.
See https://alphai.io/developers for the score and sentiment legend, and
https://alphai.io/pricing for tier limits.
'
contact:
name: alphai support
email: support@alphai.io
url: https://alphai.io/contact
license:
name: Proprietary
servers:
- url: https://api.alphai.io
description: Production (API host — key required)
security:
- apiKey: []
tags:
- name: calendar
description: Scheduled US macro releases (FOMC, CPI, jobs, GDP, PCE…).
paths:
/api/calendar/:
get:
tags:
- calendar
summary: Scheduled US macro releases (economic calendar)
description: 'The official forward schedule of US macro releases: FOMC decisions
(with SEP and press-conference markers) and minutes, CPI, PPI, the
jobs report (nonfarm payrolls), GDP estimates (advance/second/third),
PCE, advance retail sales, weekly jobless claims and JOLTS — sourced
from the agencies'' own schedule pages (Fed, BLS, BEA, Census, DOL).
Each occurrence carries a stable `uid` (`US-CPI-2026-07`) that
survives reschedules: a moved release keeps its identity, updates
`scheduled_at` and reports `schedule_status`. `phase` says only
whether the scheduled moment has passed (`upcoming`/`elapsed`) — it
deliberately does not claim the agency actually published. Pair the
calendar with `/api/news/macro/` to read what a release meant once
it''s out.
The window is `[from_date, to_date)` — from inclusive, to exclusive;
date-only values mean UTC midnight; defaults are today (UTC) → +7
days; the span is capped at 400 days. No pagination: a full year of
every series is ~250 rows (hard cap 500), ordered by `scheduled_at`
ascending. Cancelled and postponed occurrences stay in the response
with their `schedule_status`.
'
parameters:
- in: query
name: from_date
description: 'Window start, inclusive. `YYYY-MM-DD` (UTC midnight) or an ISO datetime (naive = UTC). Default: today, UTC midnight.'
schema:
type: string
example: '2026-08-07'
- in: query
name: to_date
description: Window end, exclusive. Same formats. Default `from_date` + 7 days; span capped at 400 days.
schema:
type: string
example: '2026-08-14'
- in: query
name: event_key
description: Narrow to specific series, comma-separated. Unknown keys return 400.
schema:
type: string
example: cpi,nfp,fomc_decision
- in: query
name: importance
description: Narrow by importance tier.
schema:
type: string
enum:
- high
- medium
- low
- in: query
name: country
description: v1 covers US releases only.
schema:
type: string
enum:
- US
default: US
responses:
'200':
description: Occurrences within the window, `scheduled_at` ascending.
content:
application/json:
schema:
$ref: '#/components/schemas/CalendarEvents'
'400':
description: Unknown parameter or value, a malformed date, `to_date` not after `from_date`, or a window over 400 days.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Error:
type: object
properties:
message:
type: string
error:
type: string
detail:
type: string
extra:
type: object
description: 'Machine-readable context on capped responses: the 429 carries `tier`, `limit_per_minute`, `limit_per_day`, `retry_after_seconds`; the archive 403 carries `reason: archive_horizon`, `tier`, `archive_days`. Both include an `upgrade` object (higher tiers'' caps + `pricing_url`) for callers below Pro. A 400 caused by an unknown query parameter additionally carries `allowed_params` — the complete list this endpoint accepts, read straight off the endpoint''s own schema — plus `docs`, a link to the developer reference. Individual entries in `extra.fields` may carry a did-you-mean hint in their `msg`.'
CalendarEvent:
type: object
description: One scheduled occurrence of a US macro release. `uid` is a stable, opaque occurrence id — reschedules update the row in place, so the uid is safe to store and link. `phase` is computed against request time and only says whether the scheduled moment passed; check `schedule_status` first (a `cancelled` row's phase is meaningless).
properties:
uid:
type: string
example: US-CPI-2026-07
event_key:
type: string
enum:
- fomc_decision
- fomc_minutes
- cpi
- ppi
- nfp
- gdp
- pce
- retail_sales
- jobless_claims
- jolts
title:
type: string
example: CPI (Consumer Price Index)
reference_period:
type: string
description: 'What the release covers, machine-readable: a month (`2026-07`), a quarter (`2026-Q2`), or — for weekly claims — the reference week-ending Saturday (`2026-07-25`).'
example: 2026-07
release_stage:
type: string
nullable: true
description: GDP only — `advance`, `second` or `third`; null elsewhere.
scheduled_at:
type: string
format: date-time
description: Official release moment (UTC; 08:30 / 10:00 / 14:00 ET converted).
phase:
type: string
enum:
- upcoming
- elapsed
schedule_status:
type: string
enum:
- scheduled
- postponed
- cancelled
schedule_basis:
type: string
enum:
- official
- inferred
description: '`official`: the date is printed on the agency''s own schedule page. `inferred`: derived from the documented publication cadence — weekly jobless claims (DOL publishes no forward schedule) and FOMC minutes dates the Fed has not printed yet (three weeks after the meeting). Inferred dates flip to official once the agency lists them.'
importance:
type: string
enum:
- high
- medium
- low
category:
$ref: '#/components/schemas/NewsCategory'
country:
type: string
example: US
source_url:
type: string
format: uri
description: The agency's own schedule page for the series.
press_conference_at:
type: string
format: date-time
nullable: true
description: FOMC decisions only — the 14:30 ET press conference; null elsewhere.
has_sep:
type: boolean
description: FOMC decisions only — true when the meeting carries a Summary of Economic Projections (the "dot plot").
CalendarEvents:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/CalendarEvent'
NewsCategory:
type: string
description: '`market_movers` is for articles whose subject IS a notable price move ("AMD up 5% today"); `sector_analysis` is genuine sector-level analysis; `insider` covers SEC Form 4 insider transactions only. SEC 8-K filings categorize by their primary item: an earnings release (Item 2.02) is `earnings`, a completed acquisition or disposition (Item 2.01) is `mergers_acquisitions`, and the remaining events (material agreements, debt, executive changes, annual-meeting results) are `corporate_actions`.'
enum:
- earnings
- mergers_acquisitions
- regulation
- macro_economy
- sector_analysis
- market_movers
- technology
- commodities
- crypto
- ipo
- geopolitics
- insider
- corporate_actions
- other
responses:
RateLimited:
description: 'Rate limit exceeded — either the per-minute burst cap or the per-day
volume cap. The `Retry-After` header tells you how long to wait (a burst
block is short, ≤60s; a day-cap block is capped at 3600s — the true reset
is `X-RateLimit-Reset`). The `X-RateLimit-*` trio shows the daily volume
budget. The body''s `extra` names your tier, its `limit_per_minute` /
`limit_per_day`, `retry_after_seconds`, and — below Pro — an `upgrade`
block with the higher tiers'' caps and the pricing URL.
'
headers:
Retry-After:
description: Seconds to wait before retrying (burst ≤60s; day cap ≤3600s).
schema:
type: integer
X-RateLimit-Limit:
description: The tier's per-day request volume.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests left in today's volume budget.
schema:
type: integer
X-RateLimit-Reset:
description: Epoch seconds of the next 00:00 UTC reset.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: ak_live_*
description: 'Token of the form `ak_live_<random>`. Issued from
`/account/api-keys` on the website. Send as `Authorization: Bearer …`.
'