prereason-com System API

openapi: 3.2.0
info:
  title: PreReason System 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: System
  description: Health, status, and version endpoints
paths:
  /api/health:
    get:
      tags:
      - System
      summary: Health check
      description: Returns API health status. No authentication required.
      operationId: getHealth
      security: []
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
                  version:
                    type: string
                    example: 1.0.0
                  endpoints:
                    type: object
  /api/health/ready:
    get:
      tags:
      - System
      summary: Readiness (database)
      description: 'Whether the database answered a read just now. 200 when it did, 503 when it

        did not or took longer than three seconds, so an uptime monitor can read the

        answer from the status code alone. A result is reused for up to ten seconds,

        and checked_at says when it was taken. No authentication required.'
      operationId: getHealthReady
      security: []
      responses:
        '200':
          description: The database answered
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  database:
                    type: string
                    enum:
                    - ok
                  latency_ms:
                    type: integer
                    example: 38
                  checked_at:
                    type: string
                    format: date-time
        '503':
          description: The database did not answer in time, or this instance is not reading it
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - down
                  database:
                    type: string
                    enum:
                    - error
                    - timeout
                    - demo_mode
                  checked_at:
                    type: string
                    format: date-time
  /api/status:
    get:
      tags:
      - System
      summary: System status
      description: 'Public system status page data. Returns operational status for API, database,

        and data pipeline components. No authentication required.'
      operationId: getStatus
      security: []
      responses:
        '200':
          description: System status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - operational
                    - degraded
                    - outage
                    example: operational
                  components:
                    type: object
                  lastChecked:
                    type: string
                    format: date-time
  /api/version:
    get:
      tags:
      - System
      summary: API version
      description: Returns current API version and supported versions. No authentication required.
      operationId: getVersionConfig
      security: []
      responses:
        '200':
          description: Version configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  currentVersion:
                    type: string
                    example: v1
                  supportedVersions:
                    type: array
                    items:
                      type: string
                    example:
                    - v1
  /api/headline:
    get:
      tags:
      - System
      summary: Headline metrics
      description: 'Returns a small set of key market metrics for display (e.g., login page, dashboards).

        Cached 5 minutes. No authentication required.'
      operationId: getHeadline
      security: []
      responses:
        '200':
          description: Headline metrics
          content:
            application/json:
              schema:
                type: object
  /api/openapi/spec.json:
    get:
      tags:
      - System
      summary: OpenAPI specification (JSON)
      description: Returns this OpenAPI specification in JSON format.
      operationId: getOpenApiJson
      security: []
      responses:
        '200':
          description: OpenAPI 3.0 specification
          content:
            application/json:
              schema:
                type: object
  /api/openapi/spec.yaml:
    get:
      tags:
      - System
      summary: OpenAPI specification (YAML)
      description: Returns this OpenAPI specification in YAML format.
      operationId: getOpenApiYaml
      security: []
      responses:
        '200':
          description: OpenAPI 3.0 specification
          content:
            text/yaml:
              schema:
                type: string
  /api/openapi/ui:
    get:
      tags:
      - System
      summary: Interactive API reference
      description: 'Browsable API reference rendered from this specification, with

        try-it-out. Unauthenticated, like the specification itself.'
      operationId: getOpenApiUi
      security: []
      responses:
        '200':
          description: HTML documentation page
          content:
            text/html:
              schema:
                type: string
  /api/openapi/status:
    get:
      tags:
      - System
      summary: Specification metadata
      description: 'Version, endpoint count and last-modified time for this specification.

        Use it to detect that the contract changed without downloading it.'
      operationId: getOpenApiStatus
      security: []
      responses:
        '200':
          description: Specification metadata
  /api/mcp:
    post:
      tags:
      - System
      summary: MCP server (Model Context Protocol)
      description: 'Stateless Streamable HTTP transport for MCP-compatible AI agents.

        The tools are get_context, get_metric, list_briefings, list_metrics and

        get_health, every one read only. Call tools/list for the set this server

        is serving now.


        No key is needed to connect, which is why this operation declares no

        security requirement. list_briefings, list_metrics and get_health answer

        an anonymous caller. get_context and get_metric need a key, sent as the

        header below. No MCP answer hands out a key or asks for one; see the

        Agent access tag for how an agent gets one.


        Configure in your MCP client:

        ```json

        {

        "mcpServers": {

        "prereason": {

        "url": "https://api.prereason.com/api/mcp",

        "headers": { "Authorization": "Bearer YOUR_API_KEY" }

        }

        }

        }

        ```'
      operationId: mcpEndpoint
      security: []
      responses:
        '200':
          description: MCP response
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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"
  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