# OpenAPI Specification & Generated Clients

> Download the CurrencyCore OpenAPI 3.1 contract, import it into Postman, Insomnia or Bruno, and generate typed clients for TypeScript, Python, Go, PHP and more.

Canonical: https://currency-core.com/docs/openapi/

---
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`](/openapi.json)
- **Base URL:** `https://api.currency-core.com/v1`
- **Format:** OpenAPI 3.1, JSON

```bash
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:

| Group | Paths |
|---|---|
| Core | `/convert`, `/rates`, `/rates/{base}` |
| History | `/history`, `/history/analysis` |
| PPP | `/ppp`, `/ppp/analysis` |
| Analytics | `/volatility`, `/correlation`, `/drawdown`, `/safe-haven`, `/mean-reversion` |
| Reference | `/countries`, `/currencies` |
| AI | `/ai` |

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.

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

See [Authentication](/docs/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:

```bash
# 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:

```bash
# 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

```bash
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"
```

```json
{
  "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](/docs/guides/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
[support@currency-core.com](mailto:support@currency-core.com). The API does not
return a request ID, so the time and the exact request are the useful identifiers.

## Next steps

- [Authentication](/docs/authentication/)
- [Error codes](/docs/errors/)
- [Official SDKs](/docs/sdks/)
- [MCP server](/docs/mcp/)
- [Convert endpoint reference](/docs/convert-endpoint/)
- [Currency API overview](/currency-api/)