> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brew.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate your own SDK

> Generate a typed Brew Public API v1 client in Python, Go, Ruby, Java, PHP, Swift, Kotlin, .NET, or any language supported by an OpenAPI 3.1 generator.

The official Brew SDK is TypeScript-first (`@brew.new/sdk`). For every other language — Python, Go, Ruby, Java, PHP, Swift, Kotlin, .NET, Rust, Elixir — generate your own client from the canonical OpenAPI 3.1 spec. The same spec powers Brew's TypeScript SDK and the [generated API reference pages](/api-reference/public-v1/contacts/get-contacts), so the contract is guaranteed in sync.

## The OpenAPI spec

| URL                                                          | Use when                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `https://brew.new/openapi/public-api-v1.yaml`                | Pulling from the API host (recommended — always matches the live deploy). |
| `https://docs.brew.new/api-reference/openapi-public-v1.yaml` | Pulling from the docs site (Mintlify CDN).                                |

Both URLs serve the same bytes — the docs URL is a mirror. The spec covers every public v1 endpoint (triggers, automations, automation runs, emails, sends, contacts, fields, audiences, domains, templates) with request schemas, response schemas, error envelopes, rate-limit + idempotency headers, and per-route examples.

## Recommended generators

The OpenAPI ecosystem has several mature generators. We don't endorse a single one — pick what fits your stack.

<Tabs>
  <Tab title="openapi-generator (OSS, every language)">
    The reference open-source generator. Supports \~50 client targets.

    ```bash theme={null}
    # One-time install (Java is required)
    brew install openapi-generator

    # Python
    openapi-generator generate \
      -i https://brew.new/openapi/public-api-v1.yaml \
      -g python \
      -o ./brew-python-sdk \
      --additional-properties=packageName=brew_sdk

    # Go
    openapi-generator generate \
      -i https://brew.new/openapi/public-api-v1.yaml \
      -g go \
      -o ./brew-go-sdk \
      --additional-properties=packageName=brew

    # Ruby
    openapi-generator generate \
      -i https://brew.new/openapi/public-api-v1.yaml \
      -g ruby \
      -o ./brew-ruby-sdk \
      --additional-properties=gemName=brew_sdk
    ```

    Every other supported language — Java, PHP, C#, Swift, Kotlin, Rust, Elixir, Dart — uses the same shape: change the `-g` target.
  </Tab>

  <Tab title="Speakeasy (commercial, high polish)">
    Speakeasy generates idiomatic SDKs (typed, paginated iterators, async-friendly retries, telemetry hooks) from the same OpenAPI source.

    ```bash theme={null}
    # Install
    brew install speakeasy-api/tap/speakeasy

    # Generate
    speakeasy quickstart \
      --schema https://brew.new/openapi/public-api-v1.yaml \
      --target python   # or go, ruby, csharp, java, php, swift, terraform, ...
    ```

    Speakeasy reads vendor extensions on the spec to produce nicer method names; ours is already annotated for the TypeScript generator so most extensions transfer.
  </Tab>

  <Tab title="Fern (commercial, multi-language)">
    Fern is another commercial multi-language SDK generator that consumes OpenAPI.

    ```bash theme={null}
    npm install -g fern-api
    fern init                                                 # set up a project
    fern api init --openapi https://brew.new/openapi/public-api-v1.yaml
    fern generate --group python-sdk   # or go-sdk, java-sdk, ruby-sdk
    ```
  </Tab>

  <Tab title="Just use cURL / fetch / httpx">
    Skipping codegen entirely is a totally legitimate choice for small integrations.

    ```bash theme={null}
    # Python (httpx)
    pip install httpx
    ```

    ```python theme={null}
    import os
    import httpx

    BREW = httpx.Client(
        base_url="https://brew.new/api",
        headers={"Authorization": f"Bearer {os.environ['BREW_API_KEY']}"},
        timeout=60.0,
    )

    # Fire an automation (the trigger id travels in the URL path)
    res = BREW.post(
        "/v1/automations/triggers/tri_signup/fire",
        json={
            "payload": {"email": "jane@example.com", "firstName": "Jane"},
        },
        headers={"Idempotency-Key": f"signup-{user_id}-{event_ts}"},
    )
    res.raise_for_status()
    print(res.json()["details"]["automationRunIds"])
    ```

    The Brew TypeScript SDK is a thin wrapper over `fetch` — the equivalent code in any language stays small.
  </Tab>
</Tabs>

## Auth + headers in generated clients

Every generator emits a configurable client. Wire the API key into the `Authorization` header. Most generators have a one-call helper:

| Generator         | Auth setup (Python example)                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| openapi-generator | `configuration = brew_sdk.Configuration(access_token=os.environ['BREW_API_KEY'])` |
| Speakeasy         | `client = Brew(security=brew.Security(bearer_auth=os.environ['BREW_API_KEY']))`   |
| Fern              | `client = BrewClient(token=os.environ['BREW_API_KEY'])`                           |

The spec declares two security schemes — `bearerAuth` (preferred) and `apiKeyAuth` (the `X-API-Key` form). Pick whichever your generator surfaces more cleanly.

## What to wire up in your generated client

Beyond the call shape, a production-ready Brew client should:

* **Honor `X-RateLimit-Remaining` and `Retry-After`** — see [Rate limits](/api-reference/api/rate-limits) for the cookbook.
* **Set `Idempotency-Key` on retried `POST`s** — see [Idempotency](/api-reference/api/idempotency).
* **Surface `x-request-id`** on every error so customers can include it in support tickets — see [Response headers](/api-reference/api/response-headers).
* **Branch error logic on `error.code`** (stable) not `error.message` (human-readable) — see [Errors](/api-reference/api/errors).
* **Use the `BrewApiError` envelope** — every non-2xx response carries `{ error: { code, type, message, suggestion, docs, retryAfter?, param?, details? } }`.

The TypeScript SDK does all of this automatically — port the patterns over.

## Pinning to a spec version

The OpenAPI spec is versioned via the v1 prefix on every path (`/v1/...`). When we break compatibility, we'll mint `/v2/...` paths AND publish a new spec at `public-api-v2.yaml`; the v1 spec will stay at the same URL.

For a more reproducible build, pin to a copy of the spec checked into your repo:

```bash theme={null}
curl -fsSL https://brew.new/openapi/public-api-v1.yaml > vendor/brew-openapi-v1.yaml
# then point your generator at vendor/brew-openapi-v1.yaml
```

Re-pull periodically (e.g. via CI) to pick up new endpoints + new examples.

## Contributing back

If you publish a generator config / template that produces an idiomatic Brew client in \$YOUR\_LANGUAGE, link it from the [changelog](/changelog) or open an issue — we'll happily mention it as a community SDK.

## See also

* [TypeScript SDK overview](/sdks/overview) — the official `@brew.new/sdk`.
* [TypeScript Quickstart](/sdks/typescript/quickstart) — see the patterns to port.
* [API introduction](/api-reference/api/api-introduction) — the contract every generator targets.
* [Errors](/api-reference/api/errors), [Rate limits](/api-reference/api/rate-limits), [Idempotency](/api-reference/api/idempotency), [Response headers](/api-reference/api/response-headers) — the cross-cutting concerns every client needs.

## Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

<Tabs>
  <Tab title="Self-Service Tools">
    <CardGroup cols="2">
      <Card title="Search Documentation" icon="magnifying-glass" color="#c44925">
        Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
      </Card>

      <Card title="ChatGPT/Claude Integration" icon="robot" color="#c44925">
        Click "Open in ChatGPT" at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Talk to Our Team">
    <CardGroup cols="2">
      <Card title="Schedule a Call" icon="calendar" color="#c44925" href="https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ1iYoRUG1J792XQpbuQLjSRRDupr7MwraFK-HQRCtTYdBmrQi8nZu2qXfzKQigb8gbKJK3KN3-R">
        Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
      </Card>

      <Card title="Call Us Directly" icon="phone" color="#c44925">
        Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
      </Card>

      <Card title="Slack Channel" icon="slack" color="#c44925">
        Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
      </Card>

      <Card title="Email Support" icon="envelope" color="#c44925" href="mailto:support@brew.new">
        Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>