openapi: 3.1.0
info:
  title: ExchangeRate Enriched Data Historical Rates API
  description: ExchangeRate-API is a currency exchange rate API providing authoritative daily and intraday foreign exchange rates for 161 currencies. The v6 API surface includes Standard (Latest) rates, Pair conversion, Enriched data (locale, symbol, flag), Historical rates back to 1990, Supported codes, and an API request Quota endpoint. A separate no-key Open Access endpoint (open.er-api.com) provides once-daily rates with attribution.
  version: 6.0.0
  termsOfService: https://www.exchangerate-api.com/terms
  contact:
    name: ExchangeRate-API Support
    url: https://www.exchangerate-api.com/contact
    email: contact@exchangerate-api.com
  license:
    name: Proprietary
    url: https://www.exchangerate-api.com/terms
servers:
- url: https://v6.exchangerate-api.com/v6
  description: ExchangeRate-API v6 Production (API key required)
- url: https://open.er-api.com/v6
  description: ExchangeRate-API Open Access (no API key, attribution required)
security:
- apiKeyPath: []
tags:
- name: Historical Rates
  description: Historical exchange rates for a specific date back to 1990 (Pro / Business / Volume plans only).
paths:
  /{api_key}/history/{base_code}/{year}/{month}/{day}:
    get:
      tags:
      - Historical Rates
      summary: Get Historical Rates
      description: Returns historical exchange rates for the given base currency on the specified date. Full currency support from 2021-01-01 onward; 35 currencies are available from 1990-01-01 to 2020-12-31. Only available on Pro, Business, and Volume plans.
      operationId: getHistoricalRates
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/BaseCode'
      - $ref: '#/components/parameters/Year'
      - $ref: '#/components/parameters/Month'
      - $ref: '#/components/parameters/Day'
      responses:
        '200':
          description: Successful response with historical rates for the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
        '400':
          description: Error response (may include no-data-available, plan-upgrade-required).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{api_key}/history/{base_code}/{year}/{month}/{day}/{amount}:
    get:
      tags:
      - Historical Rates
      summary: Get Historical Rates With Amount
      description: Returns historical exchange rates plus converted amounts for the given base currency on the specified date.
      operationId: getHistoricalRatesWithAmount
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/BaseCode'
      - $ref: '#/components/parameters/Year'
      - $ref: '#/components/parameters/Month'
      - $ref: '#/components/parameters/Day'
      - $ref: '#/components/parameters/Amount'
      responses:
        '200':
          description: Successful response with historical rates and converted amounts for the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalAmountsResponse'
        '400':
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    Month:
      name: month
      in: path
      required: true
      description: Month for historical data (1-12, no leading zero).
      schema:
        type: integer
        minimum: 1
        maximum: 12
        example: 3
    Amount:
      name: amount
      in: path
      required: true
      description: Decimal amount to convert (xxxx.xxxx format).
      schema:
        type: number
        format: double
        example: 100.0
    ApiKey:
      name: api_key
      in: path
      required: true
      description: Your ExchangeRate-API dashboard API key.
      schema:
        type: string
    Day:
      name: day
      in: path
      required: true
      description: Day for historical data (1-31, no leading zero).
      schema:
        type: integer
        minimum: 1
        maximum: 31
        example: 15
    BaseCode:
      name: base_code
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the base currency (e.g. USD).
      schema:
        type: string
        pattern: ^[A-Z]{3}$
        example: USD
    Year:
      name: year
      in: path
      required: true
      description: Year for historical data (full four-digit year).
      schema:
        type: integer
        example: 2024
  schemas:
    HistoricalAmountsResponse:
      type: object
      description: Historical rates with converted amounts.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        year:
          type: integer
          description: Year of the historical record.
        month:
          type: integer
          description: Month of the historical record.
        day:
          type: integer
          description: Day of the historical record.
        base_code:
          type: string
          description: Base currency for the rates.
        requested_amount:
          type: number
          description: Amount supplied for conversion.
        conversion_amounts:
          type: object
          description: Mapping of currency codes to the converted amounts at the historical rate.
          additionalProperties:
            type: number
    ErrorResponse:
      type: object
      description: Standard error envelope returned when a request cannot be fulfilled.
      properties:
        result:
          type: string
          description: Status indicator (error).
          example: error
        error-type:
          type: string
          description: Machine-readable error code.
          enum:
          - unsupported-code
          - malformed-request
          - invalid-key
          - inactive-account
          - quota-reached
          - plan-upgrade-required
          - no-data-available
    HistoricalRatesResponse:
      type: object
      description: Historical rates response for a specific date.
      properties:
        result:
          type: string
          description: Status indicator.
        documentation:
          type: string
          format: uri
          description: Link to the documentation.
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use.
        year:
          type: integer
          description: Year of the historical record.
        month:
          type: integer
          description: Month of the historical record.
        day:
          type: integer
          description: Day of the historical record.
        base_code:
          type: string
          description: Base currency for the rates.
        conversion_rates:
          type: object
          description: Mapping of ISO 4217 currency codes to historical exchange rates.
          additionalProperties:
            type: number
  securitySchemes:
    apiKeyPath:
      type: apiKey
      in: path
      name: api_key
      description: ExchangeRate-API uses an API key embedded in the URL path (after /v6/).