Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: PreReason Company Briefings 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: Company Briefings
description: 'One listed company''s briefing bought per call, whole or one block at a
time, for a company of a market that is live. A key reads the same
briefing through GET /api/context when its plan reaches the market.'
paths:
/api/companies/{company}:
get:
tags:
- Company Briefings
summary: 'Stocks: one listed company''s financial statements and fundamentals, paid per…'
description: 'Stocks: one listed company''s financial statements and fundamentals,
paid per request with no API key: its latest reported figures, what
changed, and how it is valued and financed.
The whole briefing for one listed company in one call, as of today:
its latest reported figures, what changed, its situations, and how it
is valued and financed, each figure dated and sourced. It is the public
form `GET /api/context?briefing=equities.company/{company}` serves a
key whose plan reaches the company''s market. Sold for a company of a
market that is live; one block alone is
`GET /api/companies/{company}/{block}`.
The header''s next results line, for a date the company announced in
its own filing whose sentence also says when in the day, carries
`detail.timing` (`before-open`, `after-close`, or null where the
sentence states only a clock time) and
`detail.release_time` (the release''s clock time as the company wrote
it, or null). Neither is the call''s time; where the sentence says
neither, both are left out.
Refused before any price is quoted, so no payment is taken: a `date`
or `time` (400: the figures carry their own filing dates and the
ratios keep no earlier version, so the briefing is sold as of today),
a malformed address (400), and an address that names no company sold
here (404 `NOT_FOUND`) or one whose statements have not been read
(404 `NOT_COVERED_YET`). A key holder is never charged on this route:
the key''s plan decides, as on `/api/context`.'
operationId: getCompanyBriefing
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.35'
protocols:
- x402: {}
- mpp:
method: evm
intent: charge
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
offers:
- amount: '350000'
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
description: One listed company's briefing
intent: charge
method: evm
parameters:
- name: company
in: path
required: true
description: The company. For a company filing with the SEC, its ticker or CIK; for a Japanese company, its securities code; for a Korean company, its stock code; for an Indian company, its ISIN; the LEI of a company filing in the UK or of a European company (2138002P5RNKC5W2JZ46); and for a Brazilian company, its B3 ticker or CNPJ (PETR4). Case does not matter.
schema:
type: string
pattern: ^[A-Za-z0-9.-]{1,33}$
example: NVDA
- $ref: '#/components/parameters/FormatParam'
responses:
'200':
description: The company briefing, Markdown by default, JSON with format=json
'400':
description: A date or time was sent, or the address is malformed
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
description: A key whose plan does not reach the company's market
'404':
description: No company briefing is sold for this address, or none of its statements has been read
'503':
description: The company could not be checked; no price was quoted and no payment taken
/api/companies/{company}/{block}:
get:
tags:
- Company Briefings
summary: One block of a listed company's financial data, paid per call
description: 'One block of a listed company''s financial data, such as its reported
figures or its valuation, paid per request with no API key.
One block of the company''s briefing, as of today, from its public form,
with the company''s name, address, market and the time the briefing was
computed. Nothing of the header block comes with another block: the
header is a block of its own. The whole briefing is
`GET /api/companies/{company}`.
A block name outside the list the `block` parameter takes is refused
with a 404 before any price is quoted. A block left out for this
company answers 404 `BLOCK_NOT_COVERED_YET`, and nothing is charged.
The numbers block alone takes a `date` (YYYY-MM-DD): its figures as
known at the end of that day in the company''s market, each with
`knownBasis` (`filed`, `reported` or `deadline`) and `knownSince` (for
`deadline`, the date our deadline rule assumes). A period the store
cannot date is named and left out. Where the dated read is not
available the route answers 503 `DATED_READ_UNAVAILABLE`, and nothing
is charged.
Refused before any price is quoted, so no payment is taken: a `date`
on any other block, or a `time` (400: the figures carry their own
filing dates and the ratios keep no earlier version, so those blocks
are sold as of today), a malformed address (400), and an address
that names no company sold
here (404 `NOT_FOUND`) or one whose statements have not been read
(404 `NOT_COVERED_YET`). A key holder is never charged on this route:
the key''s plan decides, as on `/api/context`.'
operationId: getCompanyBriefingBlock
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.05'
protocols:
- x402: {}
- mpp:
method: evm
intent: charge
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
offers:
- amount: '50000'
currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
description: One block of a listed company's briefing
intent: charge
method: evm
parameters:
- name: company
in: path
required: true
description: The company. For a company filing with the SEC, its ticker or CIK; for a Japanese company, its securities code; for a Korean company, its stock code; for an Indian company, its ISIN; the LEI of a company filing in the UK or of a European company (2138002P5RNKC5W2JZ46); and for a Brazilian company, its B3 ticker or CNPJ (PETR4). Case does not matter.
schema:
type: string
pattern: ^[A-Za-z0-9.-]{1,33}$
example: NVDA
- name: block
in: path
required: true
description: The block of the company briefing to return.
schema:
type: string
enum:
- header
- what_changed
- situations
- against_guidance
- numbers
- segments
- valuation
- capital_structure
- quality
- profitability
- news
example: numbers
- name: date
in: query
required: false
description: The numbers block only. A past date (YYYY-MM-DD) whose figures to serve as known at the end of that day in the company's market. Refused on every other block. For a period's latest figures, including a later amendment's, leave date out.
schema:
type: string
format: date
example: '2025-06-30'
- $ref: '#/components/parameters/FormatParam'
responses:
'200':
description: The block, Markdown by default, JSON with format=json
'400':
description: A date or time was sent, or the address is malformed
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
description: A key whose plan does not reach the company's market
'404':
description: No such block, no company briefing sold for this address, none of its statements read, or the block is not covered for this company
'503':
description: The company could not be checked; no price was quoted and no payment taken
/api/companies:
get:
tags:
- Company Briefings
summary: The covered companies, by market (no key needed)
description: 'Every company PreReason serves a company briefing for, by market: its
address (what `GET /api/companies/{company}` and get_context''s entity
take), its name, its market, its briefing id and the blocks its
briefing serves. Sorted by market, then name. Each market carries the
day of its count (`as_of`), and the list follows the counts the site
prints. One page at a time: the answer''s `page.next_cursor` asks for
the next page.'
operationId: listCoveredCompanies
security: []
parameters:
- name: market
in: query
required: false
description: One market's code, as the answer's markets list names it.
schema:
type: string
example: gb
- name: q
in: query
required: false
description: Companies whose name holds these words, or the company whose address is this code.
schema:
type: string
maxLength: 80
example: toyota
- name: limit
in: query
required: false
description: Rows per page, from 1 to 1000.
schema:
type: integer
minimum: 1
maximum: 1000
default: 500
- name: cursor
in: query
required: false
description: The page.next_cursor of the previous answer.
schema:
type: string
responses:
'200':
description: One page of the covered companies, with each market and the day of its count
'400':
description: A market, limit or cursor the list does not take
'503':
description: The list could not be read just now; nothing is listed
components:
responses:
PaymentRequired:
description: 'Payment required. The body is an x402 v2 payment quote naming this
resource, its price in USDC, and the accepted networks. Pay and retry
with the payment header, or authenticate with an API key instead.
'
content:
application/json:
schema:
type: object
properties:
x402Version:
type: integer
example: 2
error:
type: string
example: Payment required
resource:
type: object
accepts:
type: array
items:
type: object
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"
parameters:
FormatParam:
name: format
in: query
description: Response format (json or markdown). Default is markdown.
schema:
type: string
enum:
- json
- markdown
default: markdown
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