> For the complete documentation index, see [llms.txt](https://support.swisspay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.swisspay.ai/api-reference/openapi.md).

# OpenAPI specification

We publish a machine-readable OpenAPI 3.1 specification covering every endpoint in this reference.

## Where to find it

The spec is published alongside this documentation, at:

```
https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml
```

If you need a different format (JSON, bundled with examples, or a particular OpenAPI version), email <support@swisspay.ai>.

## What you can do with it

* **Generate a client SDK** in your language of choice with `openapi-generator-cli`, `oapi-codegen`, or any equivalent.
* **Import into Postman or Insomnia** to get a ready-to-go collection.
* **Run mocked servers** with Prism or similar — useful for local dev and tests before pointing at the live API.
* **Validate requests** in your CI with `spectral` or `oas-validate` before you ship.
* **Drop into AI agents** — see [Using the API with AI agents (MCP)](/api-reference/using-with-ai-agents.md).

## Versioning

* The current spec is **v1**.
* We add fields and endpoints without bumping the major version.
* Breaking changes ship under a new prefix (`/api/v2/...`) — `v1` continues to work during a documented deprecation window.

## Importing into common tools

### Postman

In Postman, click **Import → Link** and paste your published spec URL. Postman generates a collection that mirrors this reference.

### `openapi-generator-cli`

```bash
openapi-generator-cli generate \
  -i https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml \
  -g typescript-fetch \
  -o ./swisspay-client
```

### `prism` (mock server)

```bash
npx @stoplight/prism mock https://swisscrm.gitbook.io/swisspay/api-reference/openapi.yaml
```

## Reporting spec issues

If you spot a mismatch between the spec and the actual API behaviour, please email <support@swisspay.ai> with:

* The endpoint and method.
* What the spec says.
* What you observed.
* The `Swisspay-Request-Id` from the offending response, if you have one.