Documentation

API Documentation

The API exposes endpoints for fetching individual monthly rates, full yearly series, yearly averages, ranges, and direct currency conversion. Every endpoint requires a Bearer token in the Authorization header.

Authentication

Send your API key in the Authorization header on every request to /api/v1/*. Tokens start with ukk_ and are issued manually.

curl -H "Authorization: Bearer ukk_…" \
  https://ukk-api.xevieso.com/api/v1/currencies

Rate limiting

60 requests per minute per API key on a sliding window. Exceeding the limit returns 429 with a Retry-After header. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Endpoints

List currencies

GET/api/v1/currencies

Returns every known currency with its ISO code and display name.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  https://ukk-api.xevieso.com/api/v1/currencies

{
  "currencies": [
    { "code": "USD", "name": "US-Dollar" },
    { "code": "GBP", "name": "Pfund Sterling" }
  ]
}

Monthly rate

GET/api/v1/rates/monthly

Returns the monthly rate for a currency. If only year is provided, all available months for that year are returned.

currency *: ISO code (e.g. USD).
year *: Four-digit year.
month: 1–12. If omitted: all available months of that year.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates/monthly?currency=USD&year=2024&month=3"

{
  "currency": "USD",
  "year": 2024,
  "month": 3,
  "rate": "1.08720000",
  "isFinal": true
}

Yearly average

GET/api/v1/rates/yearly

Returns the yearly average once all twelve months of the year are confirmed final.

currency *: ISO code.
year *: Four-digit year.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates/yearly?currency=USD&year=2024"

{
  "currency": "USD",
  "year": 2024,
  "rate": "1.08205000"
}

Range query

GET/api/v1/rates

Returns every monthly rate of a currency within an inclusive range.

currency *: ISO code.
from *: Start month in YYYY-MM format.
to *: End month in YYYY-MM format.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates?currency=GBP&from=2024-01&to=2024-06"

{
  "currency": "GBP",
  "rates": [
    { "year": 2024, "month": 1, "rate": "0.85230000", "isFinal": true },
    { "year": 2024, "month": 2, "rate": "0.85510000", "isFinal": true }
  ]
}

Convert an amount

GET/api/v1/convert

Converts an amount at the monthly rate between two currencies. At least one side must be EUR.

amount *: Numeric amount.
from *: Source ISO code.
to *: Target ISO code.
year *: Four-digit year.
month *: 1–12.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/convert?amount=100&from=USD&to=EUR&year=2024&month=3"

{
  "amount": 100,
  "from": "USD",
  "to": "EUR",
  "year": 2024,
  "month": 3,
  "converted": "91.9794",
  "rate": "0.91979..."
}

Error codes

200: Success.
400: Invalid parameters (Zod validation).
401: Missing or invalid/revoked token.
404: No data for the requested period/currency.
429: Rate limit exceeded.
500: Internal error.

Caching

Responses include Cache-Control headers. Since monthly rates are stable once published, hour- or day-granularity client caches are reasonable.