> ## 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.

# API Design Notes

> Why Brew's API uses idempotency, partial-success batches, and polling before outbound webhooks, with context for builders.

Reference pages define the Brew API contract. These notes explain the choices
behind a few cross-cutting behaviors so you can make better decisions when
building around that contract.

## Why Every Retry Needs Idempotency

A network timeout does not tell a caller whether the server finished a `POST`.
Repeating the request can therefore create a second workflow run, send a
second email, or charge for the same generation twice. A stable key lets Brew
recognize the retry and replay the original result without doing the work
again. A changed body must use a new key so a genuine new operation is not
hidden as a retry.

This is why idempotency matters most at boundaries where another system may
redeliver an event or where a long-running request can outlive its connection:
trigger fires, sends, email generation, and batch contact writes. See the
[Idempotency](/api-reference/api/idempotency) reference for the exact window,
conflict response, and key patterns.

## Why Batch Writes Allow Partial Success

Rows in an import are independent. Rejecting a 1,000-row request because
three addresses are malformed would make callers resend valid work and would
hide the rows that need fixing. Brew validates each row, writes the valid
rows, and reports the failures beside them so a caller can correct and retry
only the bad rows.

This keeps the batch endpoint useful for imports while leaving transaction
semantics with the caller. If an application needs all-or-nothing behavior,
validate and stage the input before calling the endpoint, or use a separate
compensating workflow that knows which records it owns. The response does not
identify which successful rows were newly inserted, so deleting every address
from the input could remove pre-existing contacts. See [Batch operations](/api-reference/api/batch-operations)
for the response shape and limits.

## Why Polling Before Outbound Webhooks

The API has asynchronous work today, but outbound webhooks are not shipped
yet. Polling is the supported pattern because every accepted operation returns
a durable run or send identifier, and the status reads already expose the
same state the dashboard uses. That gives backends a predictable integration
without asking them to implement a delivery protocol that is still changing.

When outbound webhooks arrive, they can add push delivery for systems that
need it. They will still complement, rather than replace, status reads for
reconciliation and recovery. Until then, use [Async jobs & polling](/api-reference/api/async-jobs)
and follow the planned status in [Events & webhooks](/api-reference/api/events-and-webhooks).

## See Also

* [Authentication](/api-reference/api/authentication): key lifecycle, scopes, and brand binding.
* [Rate limits](/api-reference/api/rate-limits): per-route policies and `429` recovery.
* [Errors](/api-reference/api/errors): the standard error envelope and code catalog.
* [Credits](/api-reference/api/credits): credit costs and metering.

## 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 explore it further with ChatGPT or Claude.
      </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>