# Postman Collection for the CurrencyCore API

> Import the generated CurrencyCore Postman v2.1 collection and environment, set baseUrl and apiKey, and use one request per OpenAPI path. No hosted workspace.

Canonical: https://currency-core.com/docs/guides/postman/
Updated: 2026-11-12
Published: 2026-11-11

---
The CurrencyCore Postman collection is generated from the OpenAPI 3.1 contract.
It is not hand-maintained, and there is **no hosted Postman workspace** to join.
You download two files, import them into your own Postman, and set your key.

## Download

- [Collection](/postman_collection.json)
- [Environment template](/postman_environment.json)
- [OpenAPI specification](/openapi.json)
- [OpenAPI documentation](/docs/openapi/)

The collection is a Postman v2.1 collection. The environment contains two
variables: `baseUrl` and `apiKey`.

## Import and send a request

1. Download both files.
2. In Postman, choose **Import** and add both the collection and the environment.
3. Select the **CurrencyCore API** environment.
4. Set `apiKey` to your key. The environment ships with an empty placeholder, so
   no key is stored in the published file.
5. Open a request and choose **Send**.

`baseUrl` is already set to `https://api.currency-core.com/v1`. Do not append
`/v1` again. The collection uses collection-level bearer auth with the
`{{apiKey}}` variable, which Postman sends as
`Authorization: Bearer <key>`. You can also use `x-api-key`, but the generated
collection uses the bearer form. See [Authentication](/docs/authentication/)
for key types and headers.

A successful convert request returns:

```json
{
  "from": "USD",
  "amount": 100,
  "date": "2026-11-10",
  "results": [{ "to": "INR", "result": 8345.0, "rate": 83.45 }]
}
```

## What is in the collection

There are 15 requests, one for each public path, grouped into six folders:

| Folder | Requests |
|---|---|
| Core | Convert, rates, rates by base |
| History | History, history analysis |
| PPP | PPP factor, PPP analysis |
| Analytics | Volatility, correlation, drawdown, safe haven, mean reversion |
| Reference | Countries, currencies |
| AI | AI query |

Query values come from the examples in the OpenAPI contract. For example, the
convert request starts with `from=USD`, `to=EUR,INR`, and `amount=100`. Edit the
query parameters in Postman as needed. The two reference requests are public and
do not need a key, but they still work with the environment selected.

The collection does **not** include test scripts or assertions. The generator
adds requests, descriptions, auth, variables, and folders only. If you need
automated checks, add them in your own workspace or run them against your
integration tests.

## Regenerate after a spec change

From the repository root:

```bash
pnpm --filter @currencycore/web gen:postman
```

From `apps/web`:

```bash
node scripts/gen-postman.mjs
```

The generator reads `packages/shared/openapi.json` and writes:

- `apps/web/public/postman_collection.json`
- `apps/web/public/postman_environment.json`

Validate the output with:

```bash
pnpm --filter @currencycore/web test:postman
```

The check fails if the collection is missing, does not use the Postman v2.1
schema, does not have six folders, does not have 15 GET requests, or is missing
the `baseUrl` and `apiKey` variables.

Do not hand-edit the generated files. A regeneration overwrites them. Change the
OpenAPI contract or the generator instead. If the spec gains a path that is not
assigned to a folder, the generator stops and asks for a folder mapping rather
than silently dropping the request.

## Related

- [API reference](/docs/api/) for parameters and response fields
- [OpenAPI specification](/docs/openapi/)
- [Authentication](/docs/authentication/)
- [Errors](/docs/errors/) for the error envelope
- [Rate limits](/docs/rate-limits/) before you run a large collection
- [Guides](/docs/guides/) for migration and integration patterns