> ## 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.
# SDK Overview
> Official Brew SDKs and how to choose between the SDK and raw REST API
## Overview
Brew currently ships an official TypeScript SDK for the public API.
It is a thin, typed wrapper over the same `/api/v1` endpoints documented
in the API reference. The SDK does not invent a second contract. It
follows the OpenAPI source of truth.
## Current SDK
| SDK | Package | Install |
| ---------- | -------------------------------------------------------------- | --------------------------- |
| TypeScript | [`@brew.new/sdk`](https://www.npmjs.com/package/@brew.new/sdk) | `npm install @brew.new/sdk` |
## What You Get
* Typed request and response shapes.
* One client with resource methods like `brew.contacts.upsert(...)`.
* Automatic retries for safe retry cases.
* Auto-generated idempotency keys on `POST`.
* Typed `BrewApiError` handling for non-2xx responses.
## Current TypeScript SDK Resources
The TypeScript SDK exposes every public v1 resource. Reads are **flat** —
one `list()` per resource that returns a `{ data, pagination }` collection,
or a single row when you pass its id (`list({ emailId })`,
`list({ audienceId })`, …). `?include=` opt-ins (`html`, `versions`,
`graph`, `count`, `events`, `logs`) embed the heavier detail on demand.
| Resource | Methods | Notes |
| --------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brew.usage` | `get` | Plan, credit balance, and email-send quota. |
| `brew.analytics` | `campaigns`, `automations`, `events`, `eventsAll` | Read-only KPIs + the unified event explorer. |
| `brew.analytics.sends` | `list`, `listAll` | The single **send read**. `list({ sendId, include: 'events' })` returns one send + its per-recipient events; `list({ emailId })` filters to a design. Writes stay on `brew.emails.send`. |
| `brew.analytics.triggerInstances` | `list`, `listAll` | Fired-trigger instance history (`list({ triggerInstanceId })` for one). |
| `brew.automations` | `create`, `list`, `patch`, `publish`, `unpublish`, `delete`, `test` | Deterministic graph; every `sendEmail` node pins `emailVersionId`. `list({ automationId, include: 'graph,versions' })` returns one automation. `publish()` / `unpublish()` are convenience wrappers over `patch({ published })`. |
| `brew.automations.triggers` | `create`, `list`, `patch`, `delete`, `fire` | Deterministic create (`brew_api` provider hardcoded server-side) → bare row. `list({ triggerEventId })` for one; `patch` is metadata-only; gate firing via `automation.published`. |
| `brew.automations.runs` | `list`, `listAll` | Read-only run history. `list({ automationRunId, include: 'logs' })` returns one run + its `logs[]`. |
| `brew.emails` | `generate`, `import`, `edit`, `list`, `auditAccessibility`, `restore`, `delete`, `send` | AI body generation via `generate({ prompt })`; `import({ format, content })` ingests existing HTML/MJML/JSX into an editable design. `list({ emailId, include: 'html,versions' })` returns one design (carries `previewImage`). `send(input)` delivers a design — pass `test: true` for a one-off QA send. Send reads live on `brew.analytics.sends`. |
| `brew.sends` | `cancel` | `cancel(sendId)` cancels a scheduled or queued send → `{ sendId, status: 'canceled' }`. Idempotent (already-canceled → `200`); `409` once the send is sending / sent / failed, `404` for an unknown / cross-brand id. |
| `brew.contacts` | `upsert`, `patch`, `delete`, `search`, `validate`, `importCsv` | The contact **read** is `search({ filters, audienceId?, search?, sort, count?, cursor })` — by-email = a `{ field: 'email', operator: 'equals' }` filter. `upsert` / `delete` take a single contact or a batch (≤ 1000). |
| `brew.content` | `generateImage`, `gif`, `transform`, `htmlToPng`, `addImage` | Credit-metered media generation + image ops. `gif({ from })` and `transform({ operation })` are discriminated unions. |
| `brew.fields` | `list`, `create`, `delete` | Custom contact fields. |
| `brew.audiences` | `list`, `create`, `update`, `delete` | Saved audiences. `list({ audienceId, include: 'count' })` returns one audience + its live member count. |
| `brew.domains` | `list`, `add`, `verify`, `updateSettings`, `delete` | Sending domains. `list({ domainId })` for one; `list({ sendableOnly: true })` filters to verified senders. |
| `brew.brand` | `get`, `patch`, `update`, `getImages` | Brand readiness + design context. `get({ include })` embeds `identity` / `emailDesign` / `imageStyle` / `logos`; `patch()` (alias `update()`) writes them; `getImages({ q?, type?, aspectRatio? })` searches the brand image library (`q` = credit-metered semantic search; no `q` = a free browse). |
| `brew.templates` | `list` | Org-wide public template catalog (rows carry `html` + `previewImage`). |
| `brew.help` | `get` | No-auth machine-readable API catalog (`GET /v1/help`). |
Brand management is not part of the public API or the SDK. **Each API
key is bound to exactly one brand**, and every resource above except
`templates` (org-wide) and `help` (no-auth) automatically scopes to
that brand. Create and manage
keys at [brew.new/settings/api](https://brew.new/settings/api). See
the [API introduction's Brand Scoping section](/api-reference/api/api-introduction#brand-scoping)
for the full breakdown.
## Other Languages
The TypeScript SDK is the only one Brew currently ships as a typed,
versioned wrapper. **For Python / Go / Ruby / Java / PHP / Swift /
Kotlin / .NET**, generate a client from the canonical OpenAPI 3.1
spec — see [Generate your own SDK](/sdks/openapi-codegen) for the
recommended generators and one-command scaffolds. The spec lives at:
* `https://brew.new/openapi/public-api-v1.yaml` — served from the
API host
* `https://docs.brew.new/api-reference/openapi-public-v1.yaml` —
served from this docs site
If you want REST directly (no codegen), every endpoint works fine
with `curl` / `httpx` / `fetch` — see the cURL examples on every
generated [Public API v1](/api-reference/public-v1/contacts/get-contacts) endpoint page.
## SDK Or REST API
Use the SDK when you want:
* Type safety.
* Less HTTP boilerplate.
* Built-in retries and idempotency support.
* A resource-oriented client surface.
```ts theme={null}
import { createBrewClient } from '@brew.new/sdk'
const brew = createBrewClient({
apiKey: process.env.BREW_API_KEY!,
})
const { data: domains } = await brew.domains.list()
```
Use REST directly when you:
* Are not in TypeScript.
* Want direct control over raw requests.
* Are building your own wrapper.
```bash theme={null}
curl -H "Authorization: Bearer brew_your_api_key" \
https://brew.new/api/v1/domains
```
## Suggested Reading Order
1. [Authentication](/sdks/authentication)
2. [TypeScript Installation](/sdks/typescript/installation)
3. [TypeScript Quickstart](/sdks/typescript/quickstart)
4. [API Reference](/api-reference/api/api-introduction)
## 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:
Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
Click "Open in ChatGPT" at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.
Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.