openapi: 3.1.0
info:
  title: freecurrencyapi
  version: "1"
  summary: Free current and historical foreign exchange rates.
  description: >-
    freecurrencyapi provides current and historical exchange rates for a set of
    world currencies. All endpoints are served over HTTPS and return JSON.
    Authenticate every request with your API key, either as the `apikey` query
    parameter or the `apikey` request header.


    This document is generated from the freecurrencyapi service implementation
    and is the machine-readable source of truth for the v1 REST API. A
    human-readable version is available at https://freecurrencyapi.com/docs.
    freecurrencyapi is the free tier of currencyapi.com — upgrade there for
    minute-level data, the convert and range endpoints and more currencies.
  contact:
    name: freecurrencyapi support
    email: support@freecurrencyapi.com
servers:
  - url: https://api.freecurrencyapi.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Rates
    description: Latest and historical exchange rates.
  - name: Metadata
    description: Supported currencies and account status.
paths:
  /v1/latest:
    get:
      tags: [Rates]
      summary: Latest exchange rates
      operationId: getLatest
      description: Returns the latest exchange rates for a base currency (default `USD`).
      parameters:
        - { $ref: '#/components/parameters/BaseCurrency' }
        - { $ref: '#/components/parameters/Currencies' }
      responses:
        '200':
          description: Latest rates, keyed by currency code.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RatesResponse' }
              example:
                data: { EUR: 0.918456, USD: 1, GBP: 0.789012 }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/historical:
    get:
      tags: [Rates]
      summary: Historical exchange rates
      operationId: getHistorical
      description: >-
        Returns exchange rates for a single past date (default: yesterday).
        Requesting a range via `date_from`/`date_to` is not available on the free
        plan and returns 403 — use currencyapi.com's `/range` endpoint instead.
      parameters:
        - { $ref: '#/components/parameters/BaseCurrency' }
        - { $ref: '#/components/parameters/Currencies' }
        - name: date
          in: query
          required: false
          description: The date to fetch rates for (format `YYYY-MM-DD`). Defaults to yesterday.
          schema: { type: string, format: date }
          example: "2022-01-01"
      responses:
        '200':
          description: Historical rates, keyed by date then currency code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      type: object
                      additionalProperties: { type: number }
                required: [data]
              example:
                data:
                  "2022-01-01": { EUR: 0.879908, GBP: 0.739337 }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Range queries are not available on the free plan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example:
                message: "To get a range of historical data, please upgrade to currencyapi.com in your dashboard and use the /range endpoint (https://currencyapi.com/docs/range)"
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/currencies:
    get:
      tags: [Metadata]
      summary: List supported currencies
      operationId: getCurrencies
      description: Returns metadata for the supported currencies, optionally filtered.
      parameters:
        - { $ref: '#/components/parameters/Currencies' }
      responses:
        '200':
          description: Supported currency metadata keyed by code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties: { $ref: '#/components/schemas/CurrencyInfo' }
                required: [data]
              example:
                data:
                  EUR:
                    symbol: "€"
                    name: "Euro"
                    symbol_native: "€"
                    decimal_digits: 2
                    rounding: 0
                    code: "EUR"
                    name_plural: "Euros"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/status:
    get:
      tags: [Metadata]
      summary: Account quota status
      operationId: getStatus
      description: Returns your quota usage. Does not count against your quota.
      responses:
        '200':
          description: Current quota usage.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusResponse' }
              example:
                account_id: 313373133731337
                quotas:
                  month: { total: 5000, used: 120, remaining: 4880 }
                  grace: { total: 0, used: 0, remaining: 0 }
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    ApiKeyQuery: { type: apiKey, in: query, name: apikey, description: "API key as the apikey query parameter." }
    ApiKeyHeader: { type: apiKey, in: header, name: apikey, description: "API key as the apikey request header (recommended)." }
  parameters:
    BaseCurrency:
      name: base_currency
      in: query
      required: false
      description: The base currency all values are relative to. Defaults to `USD`.
      schema: { type: string }
      example: "USD"
    Currencies:
      name: currencies
      in: query
      required: false
      description: >-
        Comma-separated currency codes to include (e.g. `EUR,USD,GBP`). Defaults
        to the full supported set.
      schema: { type: string }
      example: "EUR,USD,GBP"
  responses:
    Unauthorized:
      description: An API key was supplied but is invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "If you specify an apikey it has to be a valid one." }
    ValidationError:
      description: One or more request parameters failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }
          example:
            message: "Validation error"
            errors: { base_currency: ["The selected base currency is invalid."] }
            info: "For more information, see documentation: https://freecurrencyapi.com/docs/status-codes#_422"
    RateLimited:
      description: You have exceeded your monthly quota or minute rate limit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "You have reached your monthly limit, please upgrade your plan" }
  schemas:
    RatesResponse:
      type: object
      description: Latest rates as a flat map of currency code to value.
      properties:
        data:
          type: object
          additionalProperties: { type: number }
      required: [data]
    CurrencyInfo:
      type: object
      properties:
        symbol: { type: string, example: "€" }
        name: { type: string, example: "Euro" }
        symbol_native: { type: string, example: "€" }
        decimal_digits: { type: integer, example: 2 }
        rounding: { type: number, example: 0 }
        code: { type: string, example: "EUR" }
        name_plural: { type: string, example: "Euros" }
    StatusResponse:
      type: object
      properties:
        account_id: { type: integer, example: 313373133731337 }
        quotas:
          type: object
          properties:
            month: { $ref: '#/components/schemas/QuotaBucket' }
            grace: { $ref: '#/components/schemas/QuotaBucket' }
          required: [month]
      required: [quotas]
    QuotaBucket:
      type: object
      properties:
        total: { type: integer, example: 5000 }
        used: { type: integer, example: 120 }
        remaining: { type: integer, example: 4880 }
    Error:
      type: object
      properties: { message: { type: string }, info: { type: string } }
      required: [message]
    ValidationError:
      type: object
      properties:
        message: { type: string, example: "Validation error" }
        errors:
          type: object
          additionalProperties: { type: array, items: { type: string } }
        info: { type: string }
      required: [message, errors]
