> ## 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`, so 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/overview) 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>