HEDGR Health API

openapi: 3.2.0
info:
  title: HEDGR public Health API
  version: 1.0.0
  description: HEDGR is the AI FX agent for SME finance teams. This document covers the genuinely public, unauthenticated surface (health checks, public rates, OAuth discovery metadata) plus the MCP endpoint agents use to call Hedgr's read-only dashboard tools. The authenticated /api/* dashboard namespace used by the Hedgr web app is intentionally not enumerated here - see https://hedgr.app/developer-docs for why.
  contact:
    name: HEDGR support
    email: support@hedgr.app
    url: https://hedgr.app/support
  termsOfService: https://hedgr.app/terms
  x-logo:
    url: https://hedgr.app/hedgr-logo-icon.svg
  x-api-version: '2026-08-22'
  x-versioning-policy:
    strategy: header
    header: Hedgr-API-Version
    current_version: '2026-08-22'
    supported_versions:
    - '2026-08-22'
    response_header: Every /api response carries `Hedgr-API-Version` naming the contract that answered it.
    request_pinning: A client MAY pin by sending `Hedgr-API-Version`. An unrecognised value is rejected with 400 and a typed ApiError rather than silently served the current shape, so a pin is never quietly ignored.
    mcp: The MCP endpoint versions separately, per request, via the JSON-RPC `protocolVersion` field. GET /mcp lists every accepted version in `protocolVersions`; POST /mcp with method=initialize negotiates one and echoes the agreed value.
    deprecation: A version being retired is announced on its responses with the standard `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers before removal, and in CHANGELOG.md. Versions are added append-only; an older version keeps serving until its Sunset date passes.
    breaking_change_definition: Removing or renaming a field, narrowing a type, or changing an existing status code. Adding a new optional field is not breaking and does not bump the version.
servers:
- url: https://hedgr.app
  description: Production
security:
- mcpOAuth:
  - fx:read
tags:
- name: Health
  description: Public liveness and operational status checks.
paths:
  /api/health:
    get:
      operationId: getApiHealth
      tags:
      - Health
      summary: Public API liveness probe
      description: Returns a minimal payload for unauthenticated requests. An authenticated session (cookie) receives additional Xero/QuickBooks usage detail not documented here, since that detail is session-specific and not part of the public surface.
      security: []
      parameters:
      - name: Hedgr-API-Version
        in: header
        required: false
        description: Optional version pin. Send the version your integration was built against; an unrecognised value is rejected with 400 rather than silently served the current shape. Every response echoes the serving version in the header of the same name.
        schema:
          type: string
          enum:
          - '2026-08-22'
          example: '2026-08-22'
      responses:
        '200':
          description: Service is up.
          headers:
            Hedgr-API-Version:
              schema:
                type: string
                example: '2026-08-22'
              description: The API contract version that served this response.
            Deprecation:
              schema:
                type: string
              description: RFC 9745. Present only while this version is being retired.
            Sunset:
              schema:
                type: string
              description: RFC 8594. Present only while this version is being retired; the date after which it stops responding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiHealthStatus'
        '400':
          description: Unrecognised `Hedgr-API-Version` pin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message. Stable enough to match on for known cases (e.g. "Missing Bearer token"), but not a separate machine-readable error code today.
    ApiHealthStatus:
      type: object
      description: Public API liveness payload for an unauthenticated caller.
      required:
      - ok
      - authenticated
      - timestamp
      properties:
        ok:
          type: boolean
        authenticated:
          type: boolean
          example: false
        timestamp:
          type: string
          format: date-time
        uptime:
          type: number
        rateSource:
          type: string
          description: Current market data source (e.g. frankfurter).
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: OAuth 2.1 authorization-code flow with PKCE and dynamic client registration. See /.well-known/oauth-authorization-server.
      flows:
        authorizationCode:
          authorizationUrl: https://hedgr.app/mcp/oauth/authorize
          tokenUrl: https://hedgr.app/mcp/oauth/token
          scopes:
            fx:read: Read-only access to FX exposure, cash position, hedge portfolio, P&L, policy, and related dashboard data via MCP tools.
    partnerKey:
      type: http
      scheme: bearer
      bearerFormat: hpk_live_...
      description: 'Partner API key issued by Hedgr to a broker firm. Send as Authorization: Bearer <key>. See https://hedgr.app/partner-api.'
externalDocs:
  description: Developer boundary summary
  url: https://hedgr.app/developer-docs