openapi: "3.0.3"
info:
  title: ExchangeRate-API
  description: >
    ExchangeRate-API provides real-time and historical currency exchange rates for 165
    currencies across 200 countries. Operating since 2010, the service delivers reliable
    currency conversion data via simple HTTP GET requests. Authentication is supported
    via API key embedded in the URL path or via Bearer token header. A free tier is
    available with 1,500 monthly requests and daily updates; paid plans offer hourly or
    5-minute update frequencies and higher quotas. Historical data is available back to 1990.
  version: "6"
  termsOfService: https://www.exchangerate-api.com/terms
  contact:
    name: ExchangeRate-API Support
    email: support@exchangerate-api.com
  x-api-id: exchangerate:exchangerate-api
  x-provider-name: ExchangeRate-API
externalDocs:
  description: ExchangeRate-API Documentation
  url: https://www.exchangerate-api.com/docs/overview
servers:
  - url: https://v6.exchangerate-api.com/v6
    description: ExchangeRate-API v6 endpoint (API key in URL path)
  - url: https://v6.exchangerate-api.com/v6
    description: ExchangeRate-API v6 endpoint (Bearer token auth — omit key from path)
security:
  - BearerAuth: []
tags:
  - name: Exchange Rates
    description: Real-time and historical currency exchange rate endpoints
  - name: Currencies
    description: Supported currency codes and metadata
  - name: Account
    description: API quota and account information
paths:
  /{apiKey}/latest/{baseCurrency}:
    get:
      operationId: getLatestRates
      summary: Get latest exchange rates
      description: >
        Returns the latest exchange rates for all supported currencies relative to the
        supplied base currency. Available on all plans including the free tier.
      tags:
        - Exchange Rates
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/baseCurrency'
      responses:
        '200':
          description: Successful response with latest exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: "Fri, 27 Mar 2020 00:00:00 +0000"
                time_next_update_unix: 1585353600
                time_next_update_utc: "Sat, 28 Mar 2020 00:00:00 +0000"
                base_code: USD
                conversion_rates:
                  USD: 1
                  EUR: 0.8876
                  GBP: 0.7901
                  JPY: 107.53
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authentication error (invalid key, inactive account, quota reached)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /latest/{baseCurrency}:
    get:
      operationId: getLatestRatesBearer
      summary: Get latest exchange rates (Bearer token auth)
      description: >
        Returns the latest exchange rates for all supported currencies relative to the
        supplied base currency. Uses Bearer token authentication via the Authorization header
        rather than an API key in the URL path.
      tags:
        - Exchange Rates
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/baseCurrency'
      responses:
        '200':
          description: Successful response with latest exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/pair/{baseCurrency}/{targetCurrency}:
    get:
      operationId: getPairRate
      summary: Get conversion rate for a currency pair
      description: >
        Returns the conversion rate between two specific currencies. Provides a minimal
        JSON response focused on the pair relationship. Available on all plans.
      tags:
        - Exchange Rates
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/targetCurrency'
      responses:
        '200':
          description: Successful pair conversion rate response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairRateResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: "Fri, 27 Mar 2020 00:00:00 +0000"
                time_next_update_unix: 1585353600
                time_next_update_utc: "Sat, 28 Mar 2020 00:00:00 +0000"
                base_code: EUR
                target_code: GBP
                conversion_rate: 0.8412
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/pair/{baseCurrency}/{targetCurrency}/{amount}:
    get:
      operationId: getPairConversion
      summary: Convert an amount between a currency pair
      description: >
        Returns the conversion rate between two currencies and the result of converting
        the specified amount. Available on all plans.
      tags:
        - Exchange Rates
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/targetCurrency'
        - name: amount
          in: path
          required: true
          description: The amount to convert (decimal format, e.g. 1234.5678)
          schema:
            type: number
            format: double
            example: 7
      responses:
        '200':
          description: Successful pair conversion response with conversion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairConversionResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                time_last_update_unix: 1585267200
                time_last_update_utc: "Fri, 27 Mar 2020 00:00:00 +0000"
                time_next_update_unix: 1585353600
                time_next_update_utc: "Sat, 28 Mar 2020 00:00:00 +0000"
                base_code: EUR
                target_code: GBP
                conversion_rate: 0.8412
                conversion_result: 5.8884
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/codes:
    get:
      operationId: getSupportedCodes
      summary: Get all supported currency codes
      description: >
        Returns a list of all 165 supported currencies with their ISO 4217 codes
        and full names.
      tags:
        - Currencies
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
      responses:
        '200':
          description: Successful response with supported currency codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedCodesResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                supported_codes:
                  - ["AED", "UAE Dirham"]
                  - ["AFN", "Afghan Afghani"]
                  - ["ARS", "Argentine Peso"]
                  - ["AUD", "Australian Dollar"]
                  - ["EUR", "Euro"]
                  - ["GBP", "Pound Sterling"]
                  - ["USD", "US Dollar"]
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/history/{baseCurrency}/{year}/{month}/{day}:
    get:
      operationId: getHistoricalRates
      summary: Get historical exchange rates for a specific date
      description: >
        Returns exchange rates for all supported currencies on a specific historical date.
        Historical data is available back to 1990. Requires a paid subscription plan.
      tags:
        - Exchange Rates
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/baseCurrency'
        - name: year
          in: path
          required: true
          description: Four-digit year (e.g. 2023)
          schema:
            type: integer
            minimum: 1990
            example: 2023
        - name: month
          in: path
          required: true
          description: Month number (1-12)
          schema:
            type: integer
            minimum: 1
            maximum: 12
            example: 3
        - name: day
          in: path
          required: true
          description: Day of month (1-31)
          schema:
            type: integer
            minimum: 1
            maximum: 31
            example: 15
      responses:
        '200':
          description: Successful response with historical exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                base_code: USD
                year: 2023
                month: 3
                day: 15
                requested_time: "2023-03-15T00:00:01+00:00"
                conversion_rates:
                  USD: 1
                  EUR: 0.9343
                  GBP: 0.8192
        '403':
          description: Authentication error or plan restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unsupported currency code or date out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{apiKey}/quota:
    get:
      operationId: getQuota
      summary: Get API request quota information
      description: >
        Returns the remaining request quota for the current billing period along with
        plan details.
      tags:
        - Account
      security:
        - {}

      parameters:
        - $ref: '#/components/parameters/apiKey'
      responses:
        '200':
          description: Successful response with quota information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
              example:
                result: success
                documentation: https://www.exchangerate-api.com/docs
                terms_of_use: https://www.exchangerate-api.com/terms
                plan_quota: 1500
                requests_remaining: 1243
                refresh_day_of_month: 1
        '403':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        Pass API key as a Bearer token in the Authorization header
        (e.g. Authorization: Bearer YOUR-API-KEY). When using this method, omit the
        API key from the URL path. The path-key endpoints do not use a security scheme
        in the OpenAPI sense; the {apiKey} path parameter serves as the credential.
  parameters:
    apiKey:
      name: apiKey
      in: path
      required: true
      description: Your personal API key obtained from the ExchangeRate-API dashboard
      schema:
        type: string
        example: YOUR-API-KEY
    baseCurrency:
      name: baseCurrency
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the base currency (e.g. USD, EUR, GBP)
      schema:
        type: string
        minLength: 3
        maxLength: 3
        pattern: '^[A-Z]{3}$'
        example: USD
    targetCurrency:
      name: targetCurrency
      in: path
      required: true
      description: ISO 4217 three-letter currency code for the target currency (e.g. GBP, JPY)
      schema:
        type: string
        minLength: 3
        maxLength: 3
        pattern: '^[A-Z]{3}$'
        example: GBP
  schemas:
    ResultSuccess:
      type: string
      enum: [success]
      description: Indicates the request was successful
    ResultError:
      type: string
      enum: [error]
      description: Indicates the request failed
    BaseMetadata:
      type: object
      description: Common metadata fields returned in all successful responses
      properties:
        result:
          $ref: '#/components/schemas/ResultSuccess'
        documentation:
          type: string
          format: uri
          description: Link to the API documentation
          example: https://www.exchangerate-api.com/docs
        terms_of_use:
          type: string
          format: uri
          description: Link to the terms of use
          example: https://www.exchangerate-api.com/terms
    TimestampFields:
      type: object
      description: Update timestamp fields included in rate responses
      properties:
        time_last_update_unix:
          type: integer
          format: int64
          description: Unix epoch timestamp of the last exchange rate update
          example: 1585267200
        time_last_update_utc:
          type: string
          description: UTC datetime string of the last exchange rate update
          example: "Fri, 27 Mar 2020 00:00:00 +0000"
        time_next_update_unix:
          type: integer
          format: int64
          description: Unix epoch timestamp of the next scheduled exchange rate update
          example: 1585353600
        time_next_update_utc:
          type: string
          description: UTC datetime string of the next scheduled exchange rate update
          example: "Sat, 28 Mar 2020 00:00:00 +0000"
    ConversionRates:
      type: object
      description: >
        Object mapping ISO 4217 currency codes to their exchange rate values
        relative to the base currency
      additionalProperties:
        type: number
        format: double
      example:
        USD: 1
        EUR: 0.8876
        GBP: 0.7901
        JPY: 107.53
    LatestRatesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetadata'
        - $ref: '#/components/schemas/TimestampFields'
        - type: object
          required:
            - result
            - base_code
            - conversion_rates
          properties:
            base_code:
              type: string
              description: The ISO 4217 currency code used as the base for rates
              example: USD
            conversion_rates:
              $ref: '#/components/schemas/ConversionRates'
    PairRateResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetadata'
        - $ref: '#/components/schemas/TimestampFields'
        - type: object
          required:
            - result
            - base_code
            - target_code
            - conversion_rate
          properties:
            base_code:
              type: string
              description: The ISO 4217 source currency code
              example: EUR
            target_code:
              type: string
              description: The ISO 4217 target currency code
              example: GBP
            conversion_rate:
              type: number
              format: double
              description: The exchange rate from base to target currency
              example: 0.8412
    PairConversionResponse:
      allOf:
        - $ref: '#/components/schemas/PairRateResponse'
        - type: object
          required:
            - conversion_result
          properties:
            conversion_result:
              type: number
              format: double
              description: The result of converting the specified amount at the conversion_rate
              example: 5.8884
    HistoricalRatesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetadata'
        - type: object
          required:
            - result
            - base_code
            - year
            - month
            - day
            - conversion_rates
          properties:
            base_code:
              type: string
              description: The ISO 4217 currency code used as the base for rates
              example: USD
            year:
              type: integer
              description: The year of the historical data
              example: 2023
            month:
              type: integer
              description: The month of the historical data
              example: 3
            day:
              type: integer
              description: The day of the historical data
              example: 15
            requested_time:
              type: string
              format: date-time
              description: The ISO 8601 timestamp of when data was snapshotted for that date
              example: "2023-03-15T00:00:01+00:00"
            conversion_rates:
              $ref: '#/components/schemas/ConversionRates'
    SupportedCodesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetadata'
        - type: object
          required:
            - result
            - supported_codes
          properties:
            supported_codes:
              type: array
              description: >
                Array of [currencyCode, currencyName] pairs for all supported currencies
              items:
                type: array
                minItems: 2
                maxItems: 2
                items:
                  type: string
              example:
                - ["AED", "UAE Dirham"]
                - ["USD", "US Dollar"]
                - ["EUR", "Euro"]
    QuotaResponse:
      allOf:
        - $ref: '#/components/schemas/BaseMetadata'
        - type: object
          required:
            - result
            - plan_quota
            - requests_remaining
            - refresh_day_of_month
          properties:
            plan_quota:
              type: integer
              description: Total number of API requests allowed per billing period on your current plan
              example: 1500
            requests_remaining:
              type: integer
              description: Number of API requests remaining in the current billing period
              example: 1243
            refresh_day_of_month:
              type: integer
              description: Day of the month when the quota resets
              minimum: 1
              maximum: 31
              example: 1
    ErrorResponse:
      type: object
      required:
        - result
        - error-type
      properties:
        result:
          $ref: '#/components/schemas/ResultError'
        error-type:
          type: string
          description: Machine-readable error code
          enum:
            - unsupported-code
            - malformed-request
            - invalid-key
            - inactive-account
            - quota-reached
          example: invalid-key