Endpoints

All endpoints require an X-API-Key header. See Authentication.

Successful responses use a consistent envelope: "success": true and a data object. Error responses instead return "success": false with an error object — see Errors.

Latest Rates

Retrieve the most recent exchange rates for a base currency.

GET /v1/rates/latest
Parameter Type Required Description
base query No Base currency code (e.g. EUR, USD). Defaults to EUR

Example request:

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/rates/latest?base=EUR"

Example response:

{
    "success": true,
    "data": {
        "base": "EUR",
        "updated_at": "2026-03-29T15:00:00Z",
        "rates": {
            "USD": 1.0821,
            "GBP": 0.8569,
            "JPY": 162.45,
            "CHF": 0.9612
        }
    }
}

{info} Responses include a Cache-Control: private, max-age=86400 header (24 hours).

Pair Conversion

Get the exchange rate between two currencies, with optional amount conversion.

GET /v1/rates/pair/{from}/{to}
Parameter Type Required Description
from path Yes Source currency code
to path Yes Target currency code
amount query No Amount to convert (0 < amount < 1,000,000,000,000)

Example request (with amount):

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/rates/pair/EUR/USD?amount=100"

Example response:

{
    "success": true,
    "data": {
        "base": "EUR",
        "target": "USD",
        "rate": 1.0821,
        "amount": 100,
        "converted": 108.21
    }
}

Example request (rate only):

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/rates/pair/EUR/USD"
{
    "success": true,
    "data": {
        "base": "EUR",
        "target": "USD",
        "rate": 1.0821
    }
}

Historical Rates

Retrieve exchange rates for a specific past date.

GET /v1/rates/history/{from}/{to}/{date}
Parameter Type Required Description
from path Yes Base currency code
to path Yes Target currency code
date path Yes Date in YYYY-MM-DD format

{warning} Historical access requires a Pro or Business plan. Pro plans are limited to 1 year of history; Business plans have unlimited history. Free plans receive a 403 plan-upgrade-required error.

Example request:

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/rates/history/EUR/USD/2026-03-01"

Example response:

{
    "success": true,
    "data": {
        "base": "EUR",
        "target": "USD",
        "date": "2026-03-01",
        "rate": 1.0794
    }
}

{info} Returns the historical rate for the requested from/to pair on the given date. Unsupported currencies return 422 unsupported-currency; a supported pair with no rate for that date returns 404 no-data-available.

{info} Historical responses include a Cache-Control: private, max-age=604800, immutable header (7 days).

Supported Codes

List all supported currency codes with their localized names.

GET /v1/currencies
Parameter Type Required Description
locale query No Language for names: en (default) or de

Example request:

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/currencies?locale=en"

Example response:

{
    "success": true,
    "data": {
        "currencies": {
            "EUR": "Euro",
            "USD": "US Dollar",
            "GBP": "British Pound",
            "JPY": "Japanese Yen",
            "CHF": "Swiss Franc"
        }
    }
}

{info} Responses include a Cache-Control: private, max-age=2592000 header (30 days).

Enriched Pair

Get a pair conversion with additional currency metadata (names and symbols).

GET /v1/rates/enriched/{from}/{to}
Parameter Type Required Description
from path Yes Source currency code
to path Yes Target currency code
locale query No Language for names: en (default) or de

Example request:

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/rates/enriched/EUR/USD"

Example response:

{
    "success": true,
    "data": {
        "base": "EUR",
        "target": "USD",
        "rate": 1.0821,
        "base_detail": {
            "name": "Euro",
            "symbol": "€"
        },
        "target_detail": {
            "name": "US Dollar",
            "symbol": "$"
        }
    }
}

Quota

Check your current plan's rate limit usage and remaining quota.

GET /v1/quota

No additional parameters required — the API key determines the user.

Example request:

curl -s -H "X-API-Key: YOUR_API_KEY" "https://api.rateflow.com/v1/quota"

Example response:

{
    "success": true,
    "data": {
        "plan": "Pro",
        "quota": {
            "base_limit": 50000,
            "effective_limit": 55000,
            "used": 12450,
            "remaining": 42550,
            "overflow_allowed": true,
            "overflow_percent": 10
        },
        "resets_at": "2026-04-01T00:00:00Z"
    },
    "meta": {
        "timestamp": "2026-03-29T15:00:00Z"
    }
}
Field Description
plan Name of your current plan
quota.base_limit Monthly request limit for your plan
quota.effective_limit Actual limit (higher if overflow is allowed)
quota.used Requests made this month
quota.remaining Requests remaining this month
quota.overflow_allowed Whether overflow above base limit is permitted
quota.overflow_percent Overflow percentage allowed (0-100)
resets_at ISO 8601 timestamp when quota resets (1st of next month)