Browsable reference for all 15 CurrencyCore REST paths, generated from the OpenAPI 3.1 contract: parameters, auth, plan gates, response statuses, and schema names.
Reference overview
This reference is generated from the committed OpenAPI contract. It lists all
15 REST paths, their parameters, response statuses, and response schema names.
The contract is CurrencyCore API v1, published as OpenAPI 3.1.0.
Every operation in this contract is GET and reads its inputs from
the URL. Paths below are relative to the base URL. The spec defines no request
bodies. All responses are JSON.
Authentication
Keyed endpoints accept either header shown below. The spec defines no query-string
authentication, so the key belongs in a request header.
Authentication schemes defined by the OpenAPI contract
Scheme
Header
Description
bearerAuth
Authorization: Bearer <key>
Your CurrencyCore API key, e.g. cc_live_….
apiKeyAuth
x-api-key: <key>
Your CurrencyCore API key. Equivalent to Authorization: Bearer <key>.
The public paths are /countries and /currencies . They mount without a key and are not metered.
The example uses values published in the spec. Set CURRENCY_CORE_API_KEY
in your shell before running it.
Errors
Non-2xx JSON responses in the spec reference the ApiError schema:
a single error object with a machine-readable code, a
human-readable message, and an optional details object.
Fields published for the ApiError schema
Field
Type
Required
Description
error
object
Yes
Not published
error.code
string
Yes
Not published
error.message
string
Yes
Not published
error.details
No schema published
No
Not published
Error codes listed in the spec enum
invalid_input
unsupported_query
unknown_currency
unknown_ppp
rate_not_found
unauthorized
forbidden
billing_past_due
rate_limited
internal_error
The details field has no published schema in the spec, so this
reference does not describe its keys.
Plan gates
7 paths publish x-min-plan-tier: growth in the
OpenAPI contract. Their 403 response is described as requiring the growth plan or
higher.
Paths without x-min-plan-tier do not publish a plan tier in the spec.
/history still describes a Free-plan limit of the last 30 days in its
403 response, and /ai has its own enablement and input-size responses.
Core
Conversion and the current or dated exchange-rate snapshot.
GET/convert
Convert
Convert an amount between currencies, optionally PPP-adjusted.
Source currency (ISO 4217), e.g. USD. For PPP (ppp=true), pass CUR:COUNTRY (e.g. USD:USA) when the currency is used in more than one country; common currencies are resolved automatically.
to
query
Yes
string
One or more target currencies, comma-separated, e.g. EUR,INR (max 25). For PPP, pass CUR:COUNTRY pairs (e.g. EUR:DEU,INR:IND) when a currency is used in more than one country; common currencies are resolved automatically.
amount
query
No
number
Amount to convert. Optional, defaults to 1 (so each result equals the rate). When provided it must be a finite positive number.
ppp
query
No
boolean
When true, apply a PPP adjustment. Pass CUR:COUNTRY for currencies used in more than one country; common currencies (USD, EUR, INR and others) resolve automatically.
date
query
No
string
Rate date in YYYY-MM-DD (UTC). Must not be in the future. Defaults to latest.
Responses
Responses for GET /convert
Status
Description
Schema
200
Successful response.
ConvertResponse
400
Invalid or missing request parameters.
ApiError
401
Missing or invalid API key.
ApiError
402
Billing is past due; API access is paused until payment is cleared.
ApiError
403
Forbidden: the Free plan is limited to the last 30 days of historical date= data and cannot use live keys; upgrade for access.
ApiError
429
Rate limit or monthly quota exceeded.
ApiError
default
Unexpected error.
ApiError
200 response schema: ConvertResponse
Top-level fields for ConvertResponse
Field
Type
Required
Description
from
string
Yes
Not published
fromCountry
string
No
Not published
amount
number
Yes
Not published
date
string
Yes
Not published
requestedDate
string
No
Not published
asOf
object (string values)
No
Not published
results
array of object
Yes
Not published
message
string
No
Not published
GET/rates
Rates
The full exchange-rate snapshot for a date (USD base).
Currency everything is measured against (3-letter ISO 4217). Defaults to USD.
currencies
query
No
string
Comma-separated currencies to compare, e.g. GBP,EUR,AED. OMIT to rank ALL currencies vs base ('movers' mode).
from
query
No
string
Window start YYYY-MM-DD (UTC). Defaults to 20 years (2 decades) before to. See period for a shorthand.
to
query
No
string
Window end YYYY-MM-DD (UTC). Defaults to today; a future date clamps to today.
period
query
No
string
Relative window shorthand for from: e.g. 10y, 6m, 30d, ytd, max. Ignored if from is given.
sort
query
No
string
Movers ranking: strengthened (default) or weakened.
assetClass
query
No
string
Movers universe: fiat (default, the liquid tradeable currencies), metals (XAU/XAG/XPT/XPD), or all (every currency incl. illiquid/frontier). fiat excludes metals/synthetics + illiquid frontier codes; redenomination artifacts are always dropped.
limit
query
No
number
Movers: how many top results to return (default 10, max 200).
interval
query
No
string
Attach a trend series per named currency: weekly, monthly, or yearly (compare mode only).
stats
query
No
boolean
Include min/max/avg over the window per currency. Defaults to true; pass false to skip.
Responses
Responses for GET /history/analysis
Status
Description
Schema
200
Successful response.
HistoryAnalysisResponse
400
Invalid or missing request parameters.
ApiError
401
Missing or invalid API key.
ApiError
402
Billing is past due; API access is paused until payment is cleared.
ApiError
403
Requires the growth plan or higher.
ApiError
404
No rate data is available at or before the requested start or end date.
ApiError
429
Rate limit or monthly quota exceeded.
ApiError
default
Unexpected error.
ApiError
200 response schema: HistoryAnalysisResponse
Top-level fields for HistoryAnalysisResponse
Field
Type
Required
Description
base
string
Yes
Not published
from
string
Yes
Not published
to
string
Yes
Not published
mode
string
Yes
Not published
sort
string
No
Not published
assetClass
string
No
Not published
interval
string
No
Not published
stats
boolean
Yes
Not published
results
array of object
Yes
Not published
PPP
Purchasing-power-parity factors and PPP change over time.
GET/ppp
PPP factor
A single country's purchasing-power-parity conversion factor for a year (IMF World Economic Outlook).
The full list of supported ISO 4217 currencies. Use it to resolve a name or symbol to its code, or to check whether a currency is supported (so a missing one fails clearly, not silently). Public, no key needed.
