# OpenAPI Spec

The full BillerAPI Client API is described by a machine-readable [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0) document. Use it to generate a typed client in your language, drive a mock server, or explore the API in any OpenAPI-aware tool.

## Where to get it

The spec is served from the docs site and updated on every deploy. Fetch it directly:

```http
GET https://docs.billerapi.com/openapi.json
```

The document declares two servers — `https://sandbox.api.billerapi.com` (sandbox) and `https://api.billerapi.com` (production). Point your generated client at the sandbox server while you build.

## Authentication

The spec defines the same auth schemes documented in [Authentication](/docs/guides/authentication):

- `API key` and `API key` header API keys for client-credentialed endpoints.
- `client-credentials` — Bearer API-key auth as an alternative to the header keys.
- `jwt-auth` — a Bearer access token for per-account operations (obtained via link token exchange).

The spec covers the client-facing surface only. Internal and agent-only endpoints are excluded.

## Generate a client

Any OpenAPI generator works. Two common options:

**Generate a typed client from the spec**

**openapi-typescript**

```bash
# TypeScript types + a typed fetch client
npx openapi-typescript https://docs.billerapi.com/openapi.json \
  --output ./billerapi.d.ts
```

**openapi-generator**

```bash
# Full SDKs in many languages (python, go, java, ...)
openapi-generator-cli generate \
  -i https://docs.billerapi.com/openapi.json \
  -g python \
  -o ./billerapi-python
```

All field names in requests and responses are `snake_case`. Errors follow the coded [error envelope](/docs/concepts/errors) (`error_code`, `error_type`, `error_message`, `request_id`). List endpoints use [cursor pagination](/docs/concepts/pagination).

## Official server SDK

An official `@billerapi/node` server SDK generated from this spec is planned. Until it ships, the spec above is the fastest path to a typed client. For the in-browser Connect and Pay flows, use the [Elements SDK](/docs/guides/elements-sdk) instead of a generated client.

## Related

- [API Reference](/docs/api) — human-readable endpoint reference
- [Authentication](/docs/guides/authentication) — client credentials and bearer token auth
- [Error Handling](/docs/concepts/errors) — the coded error envelope the spec references
- [Pagination](/docs/concepts/pagination) — cursor pagination shape used by list endpoints