> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

## Overview

OpenAPI is a specification for describing Representational State Transfer (REST) API interfaces. The
OpenAPI Specification (OAS) is both human and machine-readable.

The OpenAPI Description (OAD) represents a formal description of an API and is often published by a
service provider as a JSON or YAML file. The description can be used to generate client libraries,
documentation, and other tools.

See [OpenAPI Specification v3.1.0](https://spec.openapis.org/oas/v3.1.0) and
[OpenAPI Initiative](https://www.openapis.org/) for more information.

## Yoco's OpenAPI description

A publicly accessible OpenAPI 3.1 description of the REST API is available at
[https://api.yoco.com/openapi.json](https://api.yoco.com/openapi.json).

## Using the OpenAPI description

Because the OpenAPI description is machine-readable, there are many publicly available tools that
can be used to generate client libraries, documentation, and test API integrations.

Here are some common use-cases:

* Generate client libraries using
  [OpenAPI Generator](https://openapi-generator.tech/docs/installation)
* Generate documentation using [Swagger UI](https://swagger.io/tools/swagger-ui/)
* Mock an API using [Prism](https://stoplight.io/open-source/prism)
* Import OpenAPI definition into
  [Postman](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/)
  and [Bruno](https://docs.usebruno.com/open-api/importOAS).

### Generating an API client using OpenAPI Generator

[OpenAPI Generator](https://openapi-generator.tech/) is recommended for generating client libraries.

[Install](https://openapi-generator.tech/docs/installation) using your preferred package manager:

**`npm`**

```shell title="npm"
npm install @openapitools/openapi-generator-cli -g
```

**`Homebrew`**

```shell title="Homebrew"
brew install openapi-generator
```

**`pip`**

```shell title="pip"
pip install openapi-generator-cli
```

Verify `openapi-generator-cli` is installed:

**`Command`**

```shell title="Command"
openapi-generator-cli version
```

**`Output`**

```text title="Output"
7.16.0
```

List all available [generators](https://openapi-generator.tech/docs/generators):

**`Command`**

```shell title="Command"
openapi-generator-cli list
```

**`Output`**

```text title="Output"
The following generators are available:

CLIENT generators:
    - ada
    - android
    - apex
    - bash
    - c
    - clojure
    ...
```

Generate a client library for TypeScript:

```shell
openapi-generator-cli generate -g typescript -o yoco-typescript-client -i https://api.yoco.com/openapi.json
```

The client library is generated in the `yoco-typescript-client` directory.

View the generated `README.md` file for usage instructions.

### Generating a Python API client using `openapi-python-client`

[openapi-python-client](https://github.com/openapi-generators/openapi-python-client) is recommended
for generating a client library for Python. It's a more modern alternative that has strong typing,
better support for async and leverages [Pydantic](https://docs.pydantic.dev/latest/) for data models
and validation.

Install `openapi-python-client` generator:

```shell
pipx install openapi-python-client --include-deps
```

Generate the client from the OpenAPI description:

```shell
openapi-python-client generate --url https://api.yoco.com/openapi.json
```

The client library is generated in the `yoco-api-client` directory.

Make an API call using the generated client:

Note that this is just an example and is not production-ready code. You should never store credentials
as plain text in your code.

```python
from yoco_api_client import AuthenticatedClient
from yoco_api_client.api.orders import list_orders_v1_orders_get
from yoco_api_client.models import ErrorResponse, PaginatedResponseOrder

client = AuthenticatedClient(
    base_url="https://api.yoco.com",
    token="ThisIsAnOAuthAccessToken"
)

with client as client:
    response = list_orders_v1_orders_get.sync(client=client)

    if isinstance(response, PaginatedResponseOrder):
        print(f"Received paginated order response: ", response)

        for order in response.data:
            print(order.id)
    elif isinstance(response, ErrorResponse):
        raise Exception(f"Received HTTP status code {response.status}: {response.detail}")
```