openapi: 3.0.3
info:
  title: CurrencyRateAPI
  description: RESTful API for latest and historical currency exchange rates. Supports date fallback, source grouping, and caching. Internal system updates happen every 1 hour. Latest rates are cached for 15 minutes, historical rates for 24 hours.
  version: 1.0.0
servers:
  - url: https://currencyrateapi.com/api
    description: Main API server
paths:
  /latest:
    get:
      summary: Latest exchange rates
      description: |
        Returns the latest available quotes for the specified base currency.
        Data is updated internally every hour and cached for 15 minutes. Polling more frequently than every 15 minutes is not recommended.
        By default, returns only a minimal list of basic currencies (major global currencies) to reduce traffic:
        USD, EUR, GBP, CHF, JPY, CAD, AUD, NZD, SEK, NOK, DKK, ISK, PLN, CZK, HUF, RON, BGN, HRK, RSD, MKD, MDL, TRY, SGD, HKD, KRW, TWD, ILS, AED, SAR, QAR, KWD, BHD, OMR, ZAR.
        Use `extended_list=1` to get all available currencies.
      parameters:
        - name: base
          in: query
          description: 3-letter base currency code (ISO 4217).
          schema:
            type: string
            default: EUR
            example: USD
        - name: base_currency
          in: query
          description: Alternative name for the 'base' parameter.
          schema:
            type: string
        - name: codes
          in: query
          description: Comma-separated list of currency codes to filter the response (e.g., 'USD,GBP,JPY').
          schema:
            type: string
            example: GBP,JPY
        - name: quote
          in: query
          description: Alternative name for the 'codes' parameter.
          schema:
            type: string
        - name: extended_list
          in: query
          description: If set to '1', returns all available currencies. By default, returns only a minimal list to reduce traffic.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{date}:
    get:
      summary: Historical exchange rates
      description: |
        Returns currency exchange rates for a specific date (YYYY-MM-DD). Includes logic for automatic search of the nearest earlier date if data is missing.
        By default, returns only a minimal list of basic currencies (major global currencies) to reduce traffic:
        USD, EUR, GBP, CHF, JPY, CAD, AUD, NZD, SEK, NOK, DKK, ISK, PLN, CZK, HUF, RON, BGN, HRK, RSD, MKD, MDL, TRY, SGD, HKD, KRW, TWD, ILS, AED, SAR, QAR, KWD, BHD, OMR, ZAR.
        Use `extended_list=1` to get all available currencies.
      parameters:
        - name: date
          in: path
          required: true
          description: Date in YYYY-MM-DD format.
          schema:
            type: string
            format: date
            example: '2024-03-02'
        - name: base
          in: query
          description: Base currency code.
          schema:
            type: string
            default: EUR
        - name: codes
          in: query
          description: List of currencies to filter.
          schema:
            type: string
        - name: base_currency
          in: query
          description: Alternative name for the 'base' parameter.
          schema:
            type: string
        - name: quote
          in: query
          description: Alternative name for the 'codes' parameter.
          schema:
            type: string
        - name: extended_list
          in: query
          description: If set to '1', returns all available currencies. By default, returns only a minimal list to reduce traffic.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /history:
    get:
      summary: Historical exchange rates (Alternative format)
      description: |
        Returns currency exchange rates for a specific date (YYYY-MM-DD). Includes logic for automatic search of the nearest earlier date if data is missing.
        By default, returns only a minimal list of basic currencies (major global currencies) to reduce traffic:
        USD, EUR, GBP, CHF, JPY, CAD, AUD, NZD, SEK, NOK, DKK, ISK, PLN, CZK, HUF, RON, BGN, HRK, RSD, MKD, MDL, TRY, SGD, HKD, KRW, TWD, ILS, AED, SAR, QAR, KWD, BHD, OMR, ZAR.
        Use `extended_list=1` to get all available currencies.
      parameters:
        - name: date
          in: query
          required: true
          description: Date in YYYY-MM-DD format.
          schema:
            type: string
            format: date
            example: '2024-03-02'
        - name: base
          in: query
          description: Base currency code.
          schema:
            type: string
            default: EUR
        - name: codes
          in: query
          description: List of currencies to filter.
          schema:
            type: string
        - name: base_currency
          in: query
          description: Alternative name for the 'base' parameter.
          schema:
            type: string
        - name: quote
          in: query
          description: Alternative name for the 'codes' parameter.
          schema:
            type: string
        - name: extended_list
          in: query
          description: If set to '1', returns all available currencies. By default, returns only a minimal list to reduce traffic.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          description: Invalid date format or currency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /currencies:
    get:
      summary: List of available currencies (Alias)
      description: Alias for /codes. Returns a complete reference of supported currencies.
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodesResponse'
  /codes:
    get:
      summary: List of available currencies
      description: Returns a complete reference of supported currencies with codes, names, and symbols.
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodesResponse'
  /discovery:
    get:
      summary: API Discovery
      description: Returns links to all available endpoints, metadata specifications (OpenAPI, Postman), and JSON schemas.
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  info:
                    type: object
                  endpoints:
                    type: object
                  metadata:
                    type: object
                  schemas:
                    type: object
components:
  schemas:
    RatesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        base:
          type: string
          description: Base currency code in lowercase.
        date:
          type: string
          format: date
          description: Actual date for which rates are provided (may differ from requested if fallback is used).
        rates:
          type: object
          description: Quotes object, where the key is the currency code and the value is a number (rate).
          additionalProperties:
            type: number
        last_update_unix:
          type: integer
          description: Unix timestamp of the last data update in the system.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Short machine-readable error code.
        message:
          type: string
          description: Detailed description of the error in human-readable language.
    CodesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        currencies:
          type: object
          description: Currency map, where the key is a 3-letter code.
          additionalProperties:
            type: object
            properties:
              currency:
                type: string
                description: Currency name
              symbol:
                type: string
                nullable: true
                description: Currency symbol
              entity:
                type: string
                description: Country/region
