# OpenAPI spec

> A machine-readable OpenAPI 3.1 description of the AY Inbox API.

Source: https://docs.ayinbox.com/api/openapi/

The AY Inbox API is described by a machine-readable OpenAPI 3.1 document:

```
https://docs.ayinbox.com/openapi.json
```

The spec is maintained by hand and is partial: it covers the core resources, and some newer endpoints are described only in this reference and the [endpoint list](/api/endpoints/). When the two disagree, the endpoint list is the one kept current with the code. Every route a key can reach is reachable with `ayinbox api` and plain HTTP whether or not the spec describes it.

What you can do with it [#what-you-can-do-with-it]

* **Generate a client.** Point any OpenAPI generator (openapi-generator, oapi-codegen, openapi-typescript, and friends) at the URL to produce a typed client in your language.
* **Explore it interactively.** Import the URL into Postman or Insomnia to get a ready-to-call collection with every endpoint, parameter, and schema.
* **Validate against it.** Use it for contract tests so your integration breaks loudly when an assumption changes.

There are no official client libraries yet (see [SDKs](/api/sdks/)): generating a client from this spec or calling the API over plain HTTP is the supported path.

The realtime WebSocket gateway has its own machine-readable description in [AsyncAPI 3.1](https://docs.ayinbox.com/asyncapi.json); see the [realtime guide](/api/realtime/).

Conventions baked into the spec [#conventions-baked-into-the-spec]

* The single server is `https://api.ayinbox.com/v1`. Every path in the spec is relative to that versioned base. See [versioning](/api/).
* Authentication is an API key sent as a Bearer token (`bearerAuth`). See [authentication](/api/authentication/).
* List endpoints share a `data` plus `pagination` envelope with an opaque `cursor` token, and errors share a `code` plus `request_id` shape. See the [overview](/api/) and [error codes](/api/error-codes/).

The spec is versioned with the API: a breaking change ships as a new spec under a new version, never as an in-place edit to `v1`.