What is an OpenAPI spec, and how do I generate a Bird client from it?

An OpenAPI specification is a machine-readable description of an HTTP API: every path, the shape of each request and response, the authentication it expects, and the errors it can return. Its point is that tools can read it, so you can generate types, a client, mock servers or tests instead of transcribing documentation by hand.

Where is Bird's spec?

Two URLs, the same document in two formats:

https://bird.com/openapi.yaml
https://bird.com/openapi.json

One property matters more than the URLs. It is the same bundle our own SDK generators and the API reference pages build from, read from the build rather than maintained beside it. So the spec you download cannot describe a different API than the one the reference documents or the one the SDKs call. A published spec that drifts from the implementation is worse than no spec, and that is the specific failure this arrangement rules out.

What will a generated client cover?

The public API, exactly. The published document is the public bundle, which is a meaningful distinction rather than a formality.

Bird's operations carry an audience and the bundle keeps only the public ones, so a client you generate has methods for what an API key can call and nothing else. What that excludes comes in three shapes, and they are worth telling apart because the workaround differs:

• Dashboard-only operations. Rotating an API key, or the resource event stream. There is no programmatic path; a person does it in the dashboard.
• Operations on the agent surfaces but not public. Toll-free verification is the clear case: it is absent from the bundle and present on the CLI and the MCP server, both key-authenticated, so it is scriptable without a browser.
• Things an OpenAPI file cannot describe. Subscribing to Realtime channel events is a WebSocket data plane rather than an operation, so no generator can produce it. Its REST sibling goes the other way: publishing an event to a channel is public, so that half is in your generated client.

That is worth knowing before you conclude a capability is missing. An operation absent from your generated client is a statement about which surface it is on, or about whether an HTTP description can express it at all, rather than about whether Bird does it.

Should I generate a client or use an SDK?

If your language has a Bird SDK, use it: it is generated from this same specification and then wrapped in the request lifecycle. Should I use a Bird SDK or call the API directly? covers that choice properly, including the verb methods that reach operations without a typed method.

Generating your own makes sense when there is no SDK for your language, when your organisation standardises on its own generator and conventions, or when you want types only and intend to make the calls yourself.

What will I still have to write?

This is the part people underestimate, because a generator produces something that looks finished.

A generated client gives you the shapes: paths, parameters, request bodies, response types, error envelopes. It does not give you the behaviour that makes an integration survive contact with a network. You will still be writing:

• Idempotency. Generating and reusing a key per logical operation, not per attempt.
• Retries. Backing off on a 429 and a retryable 5xx, honouring Retry-After, and never retrying a deterministic 4xx.
• Region routing. Reading the region out of your key's prefix and choosing the host.

Two of those come with a slot rather than nothing, which is its own trap: every mutating operation declares an Idempotency-Key parameter and the host is a declared server variable, so a generator hands you a field to fill and a region to pick. Neither generates a key per logical operation or reads the region out of your key, which is the work those two bullets describe.

• Pagination. Walking cursors rather than assuming offsets.
• Webhook verification. Signature checking over the raw request body.

None of it is difficult, and all of it is the reason the SDKs exist. If you are generating a client because there is no SDK for your language, budget for that layer rather than for the generation, which is a single command.

API reference documents the same operations as browsable pages, and rate limits covers the one piece of behaviour a generated client cannot infer from the spec.