Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PreReason Context API
version: 1.0.0
description: 'Financial market data for AI agents, paid per request with no API key (x402
or MPP, USDC on Base) or read with a key: economic indicators, Treasury
yields and rates, FX, commodities, listed companies'' financial statements
and Bitcoin, each served as a briefing with the interpretation done.
PreReason returns market briefings with the interpretation already done:
trends, regime classification and confidence scores. Markdown by default,
which costs about
40 percent fewer tokens than JSON. Add ?format=json for structured output.
Coverage is macro, rates, bonds, FX, commodities, listed companies and
Bitcoin: the Fed balance sheet, M2, net liquidity, Treasury yields and
auctions, the dollar, oil and gas inventories, metals and grains, company
briefings, Bitcoin price, network and ETF flows, and cross asset
correlations.
GET /api/briefings is the live catalogue, with the tier each briefing
needs, and GET /api/metrics lists the individual series. Neither needs a key.
Not every endpoint needs one. Each operation below declares its own rule,
and the catalogue endpoints, the health and status endpoints and POST
/api/mcp are open. A briefing needs either an API key, sent as
Authorization: Bearer or X-API-Key, or a payment for that single call:
request a priced endpoint without a key and the 402 quotes both x402 and
MPP, USDC on Base. Free keys at https://www.prereason.com/signup, and an
agent with no browser of its own can earn one through the claim flow at
https://www.prereason.com/auth.md. Full reference at
https://www.prereason.com/docs.
Briefings are built from these providers'' data: Federal Reserve Bank of
New York, Board of Governors of the Federal Reserve System, U.S. Department
of the Treasury, Treasury International Capital (TIC), U.S. Treasury Fiscal
Data, CFTC, EIA, BIS, SEC EDGAR, FRED, mempool.space and CoinGecko, and 24
more, each named with every value it supplies (every provider is listed at
https://www.prereason.com/data-sources). Freshness ranges from near real
time to monthly depending on the series, and ETF market data updates every
15 minutes during market hours. Powered by CoinGecko. This product uses the
FRED API but is not endorsed or certified by the
Federal Reserve Bank of St. Louis.'
contact:
name: API Support
url: https://www.prereason.com/docs
email: support@prereason.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
x-guidance: 'Pay per request with no account. Call a priced GET endpoint and read the 402: it offers MPP (WWW-Authenticate: Payment, method evm, USDC on Base) and x402 (PAYMENT-REQUIRED, USDC on Base or Solana). Pay with either and retry the same request carrying the credential. With an API key (X-API-Key) the same endpoints are served under your plan instead. Start with GET /api/btc ($0.02) for a Bitcoin briefing; /api/macro, /api/cross/regime and /api/fx cover macro, market regime and FX liquidity. Responses are markdown by default; add ?format=json for structured output.'
servers:
- url: https://api.prereason.com
description: Production API
security:
- BearerAuth: []
tags:
- name: Context
description: 'Briefing-based context endpoints. The primary way to consume PreReason data.
Each briefing bundles related metrics with trend analysis and confidence scores.'
paths:
/api/news:
get:
tags:
- Context
summary: Dated records of what companies filed and what federal agencies and the Federal…
description: 'Records PreReason stores, newest first, each with its source, its
date or time and a link: what companies filed (for the companies
PreReason covers: 8-K items in the USA, EDINET in Japan, DART in Korea)
and what federal agencies and the Federal Reserve published (the
Federal Register''s trade actions and export controls, Treasury buyback
operations, the Federal Reserve''s monetary policy releases). An answer
holding a source''s records carries that source''s required notice in
`notices`.
Name one company in `about` for its filings alone. Every answer names
the sources it read; it states records, not reasons.
A filed 8-K line names the filing''s substantive items in PreReason''s
fixed order of significance, at most three, with a count of the rest;
item 7.01 (Regulation FD disclosure) and item 9.01 (financial
statements and exhibits) are carriers, named only when a filing
carries nothing else.
Each record is in the window by the date it shows. A source that
dates by day prints that day with no clock time: EDGAR''s own filing
date, DART''s receipt date, the Federal Register''s publication date and
Treasury''s buyback operation date. EDINET''s submission and the Fed''s
release print their own clock.
The order: by the date each record shows, newest first; within one
date, the records that show a time first, newest first, then the
records dated by day alone; ties go by id.
Needs an API key on any plan, and each read counts as one call. A bad
date, kind or limit answers 400; a company PreReason does not cover
answers 404.'
operationId: getNews
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: about
in: query
required: false
description: One company, by its address (a ticker, CIK, securities code, stock code, ISIN or LEI). Left out, records of every company and agency read.
schema:
type: string
- name: kind
in: query
required: false
description: filed (company filings) or official (federal agency and Federal Reserve documents). Both when left out.
schema:
type: string
enum:
- filed
- official
- name: since
in: query
required: false
description: The first date of the window, YYYY-MM-DD. Seven days before until when left out.
schema:
type: string
format: date
- name: until
in: query
required: false
description: The last date of the window, YYYY-MM-DD. Today (UTC) when left out.
schema:
type: string
format: date
- name: as_of
in: query
required: false
description: Only records dated on or before this date, YYYY-MM-DD; in place of until.
schema:
type: string
format: date
- name: limit
in: query
required: false
description: Records one read returns, 1 to 25. Default 10.
schema:
type: integer
minimum: 1
maximum: 25
responses:
'200':
description: The records, the window and the sentence naming the sources read
content:
application/json:
schema:
type: object
required:
- about
- window
- records
- coverage
properties:
about:
type:
- object
- 'null'
window:
type: object
records:
type: array
items:
type: object
coverage:
type: string
notices:
type: array
items:
type: string
note:
type: string
not_read:
type: array
items:
type: string
'400':
description: A bad date, kind or limit, a window over 92 days, or kind official with about
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: A company PreReason does not cover, or one whose filings this version does not read
'503':
description: No source could be read
/api/context:
get:
tags:
- Context
summary: Get context briefing
description: 'The primary endpoint for consuming PreReason data. Returns a pre-computed context bundle
for the requested briefing, including metrics, trend analysis and confidence scores.
Briefings are tier-gated. GET /api/briefings lists every briefing with
the tier it needs, and needs no key itself.
Company briefings (live for the USA on Basic and above, and for Japan,
Korea, India, the UK, 24 European countries and Brazil on Pro and above)
are requested as `equities.company/`: the ticker or CIK of a
company filing with the SEC (`equities.company/NVDA`), a Japanese securities code
(`equities.company/7203`), a Korean stock code (`equities.company/005930`),
an Indian company''s ISIN (`equities.company/INE018A01030`), the LEI of a
company filing in the UK or of a European company
(`equities.company/2138002P5RNKC5W2JZ46`) or a Brazilian company''s B3
ticker or CNPJ (`equities.company/PETR4`). For a company filing with the
SEC a briefing gives its latest figures as filed (its 10-Q and 10-K, or a
foreign company''s 20-F or 40-F), each dated by its filing,
what changed, its situations, and how it is valued and financed. For a
Japanese company the same, from its annual securities report or, where it
has filed one since, its half year report, as filed on EDINET; for a
Korean company the same, from its annual business report or, where it
has filed one since, its half year or quarterly report, as filed on DART.
For an Indian company it gives the latest quarter''s results statement, a
share price, and a market capitalisation where a current share count is
read.
India: 354 Indian companies have figures, a median of 3 quarters each, as of 2026-10-28.
For a company filing in the UK or a European company, the briefing gives
the figures of its annual reports (UKSEF for a company filing in the UK,
ESEF for a European company), in the company''s own reporting currency,
each dated by the day its report reached filings.xbrl.org.
For a Brazilian company, the briefing gives the figures of its annual
and quarterly statements (DFP and ITR) as filed with CVM, in reais, each
dated by its filing, and what changed in its recent filings; no share
price is served for a Brazilian company. It ends with CVM''s source
citation under the Open Database License (ODbL) 1.0, whole. In JSON the
field `cik` carries its CNPJ.
That id carries a company, so it is not among the fixed ids listed
under the `briefing` parameter. In JSON a company briefing carries
`notCoveredYet`: the blocks and figures that cannot be seen for
that company, left out of the briefing and named there once (the
field''s name is historical and promises nothing).'
operationId: getContext
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: briefing
in: query
required: true
description: 'Briefing ID (dot-namespaced, e.g., btc.context). A company briefing
is `equities.company/<company>` (the ticker or CIK of a company filing
with the SEC, a Japanese securities code, a Korean stock code, an
Indian company''s ISIN, the LEI of a company filing in the UK or of a
European company, or a Brazilian company''s B3 ticker) and is accepted
beside the ids listed.
'
schema:
type: string
enum:
- btc.quick-check
- btc.context
- btc.pulse
- btc.grid-stress
- macro.snapshot
- cross.correlations
- btc.momentum
- btc.on-chain
- btc.miner-survival
- macro.liquidity
- cross.breadth
- btc.etf-flows
- btc.full
- btc.factors
- btc.energy
- btc.treasury
- cross.regime
- fx.liquidity
- macro.rates
- cross.ai-compute
- commodities.energy-basket
- macro.auctions
- bonds.context
- bonds.full
- eth.context
example: btc.context
- name: format
in: query
description: Response format. Default is markdown (LLM-optimized).
schema:
type: string
enum:
- json
- markdown
default: markdown
example: json
- name: date
in: query
description: 'Historical date (YYYY-MM-DD). Returns context as it would have appeared on that date:
each metric is its newest period released by the end of that day (UTC), at the value public then
where PreReason holds it as first published, and marked where it may be a later revision. It carries
`period` (what it describes), `known_since` (when it was public, at the latest) and
`known_basis` (released, fetched, release_schedule or unknown): `released` is the publisher''s
stated time; `fetched` is PreReason''s first read of the row; `release_schedule` is the row''s
stamp plus its series'' release lag (for a Treasury auction, the close plus one day), PreReason''s
rule for when it was public at the latest, used where PreReason first held the row later than
that; `unknown` means no time is stated (`known_since` is null, a revised series with no release
time and no read inside its schedule). The historical context
blocks and btc.treasury''s company holdings are dated the same way.
For a period''s latest figures, including later corrections, leave date out.
Tier-gated: Free 30d rolling; Basic 3 years back, Bitcoin briefings from Jan 2025; Pro all data.
'
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
example: '2026-02-01'
responses:
'200':
description: Context data for the requested briefing
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-PreReason-Tier:
$ref: '#/components/headers/X-PreReason-Tier'
content:
application/json:
schema:
type: object
description: Structure varies by briefing. All include generated_at timestamp.
text/markdown:
schema:
type: string
description: LLM-optimized markdown with sections, figures, and context.
'400':
description: Missing or invalid briefing parameter
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: VALIDATION_ERROR
message:
type: string
example: 'Missing required parameter: briefing'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Briefing not available on your tier, or date outside tier access
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- BRIEFING_RESTRICTED
- DATE_RESTRICTED
example: BRIEFING_RESTRICTED
message:
type: string
example: Briefing 'btc.full' requires Pro tier
details:
type: object
properties:
briefing:
type: string
example: btc.full
required_tier:
type: string
example: pro
your_tier:
type: string
example: free
upgrade_url:
type: string
example: /pricing?tier=pro
'404':
description: 'Briefing does not exist. For a company briefing, a listed company
whose results statements have not been read answers `NOT_COVERED_YET` with
this status: a flat body of `error` (`NOT_COVERED_YET`), `message`
and `market`. No plan changes that answer.
'
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: Briefing 'quick-check' does not exist
details:
type: object
properties:
briefing:
type: string
example: quick-check
available_briefings:
type: array
items:
type: string
example:
- btc.quick-check
- btc.context
- macro.snapshot
'410':
description: Briefing has been deprecated and merged into another
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: BRIEFING_DEPRECATED
message:
type: string
example: Briefing 'percentile-context' has been merged into 'btc.momentum'. Use briefing=btc.momentum instead.
replacement:
type: string
example: btc.momentum
'429':
$ref: '#/components/responses/RateLimitExceeded'
/api/briefings:
get:
tags:
- Context
summary: List available briefings (RESTful alias)
description: 'Same catalog as `GET /api/context/briefings`, at the path most callers
guess first. Each entry carries an `href` so the id you read is the
address you can fetch.'
operationId: listBriefingsAlias
security: []
responses:
'200':
description: List of briefings available to your tier
/api/briefings/{id}:
get:
tags:
- Context
summary: Get one briefing by id
description: 'Alias for `GET /api/context?briefing={id}`. Accepts the dotted ids the
catalog returns, e.g. `/api/briefings/macro.snapshot`. A `.md` or
`.json` suffix sets the format.
Requires an API key. Unlike the short URL aliases, this route is not
x402-payable — free tier is free of charge, not keyless, so sign up for
a key rather than paying per call.'
operationId: getBriefingById
security:
- BearerAuth: []
- ApiKeyAuth: []
parameters:
- name: id
in: path
required: true
description: Briefing ID as returned by the catalog (dot-namespaced).
schema:
type: string
example: macro.snapshot
- $ref: '#/components/parameters/FormatParam'
- $ref: '#/components/parameters/DateParam'
responses:
'200':
description: Briefing context
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Unknown briefing id; body lists the ids you can access
/api/context/briefings:
get:
tags:
- Context
summary: List available briefings
description: 'Returns all briefings available for your tier, with descriptions and metadata.
Useful for agents to discover what context is available before requesting it.'
operationId: listBriefings
security: []
responses:
'200':
description: List of briefings available to your tier
content:
application/json:
schema:
type: object
properties:
tier:
type: string
example: free
briefings:
type: array
items:
type: object
properties:
id:
type: string
example: btc.context
name:
type: string
example: Bitcoin Market Context
description:
type: string
example: Full Bitcoin market context with on-chain and macro indicators
tier:
type: string
enum:
- free
- basic
- pro
example: free
derivatives:
type: boolean
enum:
- true
description: Present, as true, on a briefing that serves any series that measures a futures, swap or options market (see `instrument` on a metric); absent otherwise.
accessible:
type: boolean
example: true
total:
type: integer
example: 17
accessible:
type: integer
example: 6
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
headers:
X-RateLimit-Reset:
description: Unix timestamp when window resets
schema:
type: integer
example: 1740200400
X-PreReason-Tier:
description: The plan of the API key the request was made with. Sent beside the rate limit headers on requests made with an API key, the short URLs included, and absent when the request carried no key or the plan could not be read.
schema:
type: string
enum:
- free
- basic
- pro
- enterprise
example: basic
X-RateLimit-Remaining:
description: Requests remaining in current window
schema:
type: integer
example: 55
X-RateLimit-Limit:
description: Maximum requests per hour for your tier
schema:
type: integer
example: 60
parameters:
DateParam:
name: date
in: query
description: 'A past date, YYYY-MM-DD: the briefing as of the end of that day (UTC; a company''s numbers at the end of the day in its own market), for the periods released by then. Each figure says when it was public, or that it may be a later revision PreReason holds in its place. For a period''s latest figures, including later corrections, leave date out. Tier-gated access.'
schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
FormatParam:
name: format
in: query
description: Response format (json or markdown). Default is markdown.
schema:
type: string
enum:
- json
- markdown
default: markdown
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: UNAUTHORIZED
message:
type: string
example: Authentication required. Provide a valid API key.
hint:
type: string
example: 'Use "Authorization: Bearer <api_key>" or curl -u <api_key>:'
signup:
type: string
example: https://www.prereason.com/signup
how_to_get_key:
type: object
description: 'What an agent can do about this 401 from where it stands: create a
claim, show one link to a human, poll until approved. REST only:
MCP tool results carry no key path.
'
properties:
summary:
type: string
claim_endpoint:
type: string
example: https://api.prereason.com/api/agent/claims
signup_url:
type: string
docs:
type: string
example: https://www.prereason.com/docs#agent-access
headers:
WWW-Authenticate:
schema:
type: string
example: Bearer realm="prereason"
Link:
schema:
type: string
example: <https://www.prereason.com/docs#agent-access>; rel="help"
RateLimitExceeded:
description: Rate limit exceeded
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
schema:
type: integer
example: 0
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-PreReason-Tier:
$ref: '#/components/headers/X-PreReason-Tier'
Retry-After:
description: Seconds until rate limit resets
schema:
type: integer
example: 3600
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: RATE_LIMITED
message:
type: string
example: Rate limit exceeded. Upgrade for higher limits.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'API key as Bearer token. Get your key at [prereason.com/signup](https://www.prereason.com/signup).
```
Authorization: Bearer pr_live_xxx
```
'
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'The same API key in its own header, for clients that cannot set `Authorization`.
```
X-API-Key: pr_live_xxx
```
'
x-service-info:
name: PreReason
url: https://api.prereason.com
documentation: https://www.prereason.com/docs
category: financial-data
audience: ai-agents
manifest: https://api.prereason.com/.well-known/mpp
categories:
- data
docs:
homepage: https://www.prereason.com
apiReference: https://www.prereason.com/docs
llms: https://www.prereason.com/llms.txt
x-payment-info:
mppVersion: '1.0'
intents:
- charge
protocol: x402-v2
methods:
- id: x402.exact.evm
kind: crypto
scheme: exact
asset: USDC
networks:
- eip155:8453
- eip155:84532
- id: x402.exact.svm
kind: crypto
scheme: exact
asset: USDC
networks:
- solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
- solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
pricing:
free: $0.02
basic: $0.03
pro: $0.05
mpp:
method: evm
intent: charge
network: eip155:8453
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
decimals: 6
realm: api.prereason.com
challengeHeader: WWW-Authenticate
credentialHeader: Authorization
receiptHeader: Payment-Receipt
challenge:
bodyHeader: PAYMENT-REQUIRED
legacyBodyHeader: X-Payment-Requirements
bodyCarriesQuote: unpaid-requests-only
paymentHeaders:
- payment-signature
- x-payment
preferredPaymentHeader: payment-signature
manifest: https://api.prereason.com/.well-known/mpp
references:
spec: https://mpp.dev
ietfDraft: https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/
stripeDocs: https://docs.stripe.com/payments/machine/mpp