OpenAPI spec

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. 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

• 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): 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; see the realtime guide.

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.
• Authentication is an API key sent as a Bearer token (bearerAuth). See 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 and 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.