OpenAPI Specification & Generated Clients

The full CurrencyCore API is described by an OpenAPI 3.1 contract. The same contract is used to generate our SDKs, validate requests in CI, and keep the endpoint reference, MCP tools and agent instructions in sync.

Download

• Latest v1 spec: /openapi.json
• Base URL: https://api.currency-core.com/v1
• Format: OpenAPI 3.1, JSON

curl -O https://currency-core.com/openapi.json

The URL is stable. It always points at the current v1 contract. Pin a copy in your repository if you generate clients in CI.

What it covers

The spec includes all 15 public paths:

It also defines:

• both authentication schemes: Authorization: Bearer and x-api-key
• the shared error envelope and status codes
• parameter enums, date formats and numeric types
• example requests and responses
• plan entitlements where they affect a response

Authentication

The spec declares the two header schemes. Your generated client needs the key injected at runtime; do not hard-code it in generated code.

{
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    }
  }
}

See Authentication for key types, revocation and rate limits.

Import into API tools

Postman

1. Open Postman and choose Import.
2. Select the downloaded openapi.json, or paste https://currency-core.com/openapi.json.
3. Set the Authorization header to Bearer cc_test_your_key in the collection variables.
4. Run a request from the generated collection.

Insomnia and Bruno

Both tools import OpenAPI 3.1 directly:

• Insomnia: Application menu → Import → From File → openapi.json.
• Bruno: Collection menu → Import Collection → OpenAPI → openapi.json.

Swagger UI, Scalar or Redoc

Point any OpenAPI viewer at https://currency-core.com/openapi.json. The spec includes servers, so “Try it” requests target the production API. Use a test key while you explore.

Generate a typed client

The spec works with OpenAPI Generator and most modern codegen tools. Examples:

# TypeScript fetch client
npx @openapitools/openapi-generator-cli generate \
  -i https://currency-core.com/openapi.json \
  -g typescript-fetch \
  -o ./src/currencycore

# Python client
npx @openapitools/openapi-generator-cli generate \
  -i https://currency-core.com/openapi.json \
  -g python \
  -o ./currencycore_client

You can also use:

# Hey API (TypeScript)
npx @hey-api/openapi-ts -i https://currency-core.com/openapi.json -o src/client

# Orval (TypeScript)
npx orval --input https://currency-core.com/openapi.json --output ./src/api.ts

Generated clients are a starting point. Add:

• a timeout (the API is fast, but networks are not)
• retry with exponential backoff for 429 and 5xx
• a cache keyed by endpoint, base, date and parameters
• your own error mapping on top of the shared error envelope

Example request and response

curl -G https://api.currency-core.com/v1/convert \
  -H "Authorization: Bearer cc_test_your_key" \
  --data-urlencode "from=USD" \
  --data-urlencode "to=EUR,INR" \
  --data-urlencode "amount=100"

{
  "from": "USD",
  "amount": 100,
  "date": "2026-11-10",
  "results": [
    { "to": "EUR", "result": 89.24, "rate": 0.8924 },
    { "to": "INR", "result": 9413.0, "rate": 94.13 }
  ]
}

Versioning and compatibility

The contract is versioned in the URL (/v1). Additive changes, such as a new optional parameter or a new endpoint, do not require a new version. A breaking change would need a new URL version; track the changelog for shipped changes.

If you generate a client, commit the spec version you generated from and regenerate deliberately. Do not let a CI job silently pull a new spec into a production build.

Keeping the contract accurate

The contract is generated from packages/shared/src/openapi.ts and the endpoint catalog in packages/shared/src/api-catalog.ts; the committed packages/shared/openapi.json is the generated artifact. The marketing site copies it to /openapi.json at build time and a post-build check verifies:

• OpenAPI 3.1
• all 15 paths present
• both authentication schemes present
• the docs page exists

If you find a mismatch between the spec and a live response, send the endpoint, the UTC time, the status, and the response body to [email protected]. The API does not return a request ID, so the time and the exact request are the useful identifiers.

Next steps

• Authentication
• Error codes
• Official SDKs
• MCP server
• Convert endpoint reference
• Currency API overview