openapi: 3.2.0
info:
  title: FX Macrodata Health API
  description: Official-source macroeconomic indicators, release calendars, central-bank policy rates, FX reference rates, COT positioning and commodities across 22 currencies. USD data is available without an API key; other currencies and datasets need an `X-API-Key` header.
  version: 1.0.0
servers:
- url: https://api.fxmacrodata.com
  description: FXMacroData API
security:
- {}
- APIKeyHeader: []
- HTTPBearer: []
tags:
- name: Health
  description: Service health status endpoint.
paths:
  /v1/health:
    get:
      tags:
      - Health
      summary: Ping the API
      description: Returns a simple OK status to verify the API is running.
      operationId: ping_v1_health_get
      responses:
        '200':
          description: Health-check response confirming API availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                status: ok
                service: fxmacrodata-api
  /v1/ping:
    get:
      tags:
      - Health
      summary: Ping the API
      description: Returns a simple OK status to verify the API is running.
      operationId: ping_v1_ping_get
      responses:
        '200':
          description: Health-check response confirming API availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                status: ok
                service: fxmacrodata-api
components:
  schemas:
    ServiceStatusResponse:
      properties:
        status:
          type: string
          title: Status
        service:
          type: string
          title: Service
      type: object
      required:
      - status
      - service
      title: ServiceStatusResponse
      description: Liveness payload shared by ``/v1/ping`` and ``/v1/health``.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'FXMacroData API key. Preferred transport for server-side clients: the key stays out of URLs and access logs.'
    HTTPBearer:
      type: http
      scheme: bearer
      description: 'FXMacroData API key or OAuth access token supplied as ``Authorization: Bearer <key>``.'
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
      x-deprecated: true
      description: 'Deprecated. FXMacroData API key as a query parameter. Still accepted so existing integrations keep working, but new integrations must use the X-API-Key header (APIKeyHeader) or Authorization: Bearer. The only exception is browser EventSource clients of the live-delivery streams, which cannot set request headers.'