# 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 staging.
* **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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.swisspay.ai/api-reference/openapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.