A client generator saves you from copying endpoint paths and request fields into your own library. It can also produce models that catch incorrect input before a request leaves your application.
Where do I get Bird's spec?
Download the public specification in JSON or YAML.
Bird's API reference and SDK generators also use the public bundle. Save the downloaded file with your generation configuration so you can reproduce the client later.
The OpenAPI specification defines how paths, parameters, authentication and response shapes are described. Your generator uses that description to build methods and models for its target language.
How do I generate a client?
Use OpenAPI Generator to produce a client from Bird's JSON spec. Install the tool before running the download, validation and generation commands.
This example generates a Ruby client in bird-client:
curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-clientUse JSON to avoid the generator's YAML parser size limit. Validation can print recommendations even when it succeeds. Review errors before generating.
Replace ruby with a supported generator for another language. Follow that generator's installation requirements and the generated README to build or install the output.
Keep the generated files separate from handwritten application code. Regenerating into that directory can overwrite edits you made directly to the client.
The generator's usage guide documents language options and configuration files.
Which operations will the client cover?
The client covers the HTTP operations included in Bird's public bundle. An operation on another surface will not acquire a method through public-client generation.
For example, API-key rotation is available through a dashboard session or a personal CLI or MCP grant. It is absent from the public bundle and cannot be called with a workspace API key.
Toll-free verification also has CLI and MCP operations outside the public bundle. Check those surfaces before concluding that an absent method requires manual work.
Realtime publishing is a public HTTP operation. Subscribing to channel events requires a WebSocket connection. Use a Realtime client for that part.
What request handling should I check?
Inspect the generated runtime before adding the handling it lacks. Different generators and configurations supply different behavior.
| Concern | What to verify |
|---|---|
| Region | The selected host matches the region in your key's prefix. |
| Idempotency | One key is reused across attempts of the same write. |
| Retries | Temporary failures have bounded retries that honor Retry-After. |
| Pagination | Iteration follows cursors until no further page remains. |
| Webhooks | Verification uses the unchanged request body and checks the signature before parsing. |
A generated parameter does not necessarily manage its value for you. An Idempotency-Key field still needs a key with the right lifetime unless the runtime supplies one.
Likewise, a configurable server region does not prove the client reads it from your credential. Set or verify the host before making a request.
Should I generate a client or use a Bird SDK?
Use a Bird SDK when its supported language and dependencies fit your application. Generate a client when you need another language or your organization's generation conventions.
SDK or direct API calls compares the supported languages, retry behavior and timeout defaults.
- Bird SDK: use the request handling Bird provides and maintains.
- Generated client: choose your language and review its runtime handling before deployment.
- Generated types only: keep request handling in your existing HTTP layer.
In short
Download the public specification.
Bird publishes the same API description as YAML and JSON. The JSON format avoids the generator's YAML size limit.
Generate for your target language.
OpenAPI Generator validates the downloaded JSON before generating the client.
Check the generated request handling.
Review region selection, retries, idempotency, pagination and webhook verification before relying on the client.
Check another surface for missing operations.
API-key rotation uses a dashboard session or personal CLI or MCP grant. Realtime subscriptions need a WebSocket client.