Skip to main content

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.

A complete catalog of the headers Brew sets on API responses — what each one means, when it’s present, and how to consume it.

​
Headers on every response

HeaderExampleNotes
x-request-idreq_8cac13fd94e6420cacdd75a1aa403a28Opaque per-request correlator. Always include in support tickets — Brew engineers can trace your call through the full pipeline.
Cache-Controlno-storeBrew responses are never cached; integrators should not cache them either.
X-RateLimit-Limit100Requests allowed in the current rolling 60s window for this route + key.
X-RateLimit-Remaining73Requests left before the window exhausts. Honor this to preemptively slow down.
X-RateLimit-Reset1717891234Unix epoch seconds when the window resets.

​
Headers on specific responses

HeaderWhenFormat
Retry-After429 RATE_LIMITEDInteger seconds. Honor verbatim or take max(Retry-After, your-backoff).
DeprecationLegacy alias routes (e.g. /v1/events, /v1/executions, /v1/triggers/{id})true
SunsetLegacy alias routesRFC 9745 timestamp, e.g. 2026-12-01T00:00:00Z
LinkLegacy alias routes</api/v1/automation/runs>; rel="successor-version" — points at the canonical successor
The legacy aliases are functionally identical to the canonical routes; only the headers differ. Migrate before the sunset to drop the deprecation noise.

​
Request headers Brew honors

Set these on requests when applicable:
HeaderPurposeSee
Authorization: Bearer brew_…API key authentication (preferred)Authentication
X-API-Key: brew_…API key authentication (alternative — pick one)Authentication
Idempotency-Key: <≤100 chars>Replay-safe POST retries — same key + same body = cached response for 24hIdempotency
Content-Type: application/jsonRequired on POST / PATCH with a body

​
Inspecting headers from clients

​
curl

curl -i -H "Authorization: Bearer $BREW_API_KEY" \
  https://brew.new/api/v1/contacts
-i (or -D -) prints the response headers above the body.

​
TypeScript SDK (raw mode)

const { headers, data } = await brew.contacts.list(
  { limit: 50 },
  { raw: true }   // returns BrewRawResponse<…> instead of just the body
)
console.log(headers.get('x-request-id'))
console.log(headers.get('X-RateLimit-Remaining'))
Pass { raw: true } in RequestOptions on any SDK call to get the full BrewRawResponse<T> with the headers.

​
fetch

const res = await fetch('https://brew.new/api/v1/contacts', {
  headers: { Authorization: `Bearer ${process.env.BREW_API_KEY!}` },
})

console.log(res.headers.get('x-request-id'))
console.log(res.headers.get('X-RateLimit-Limit'))
console.log(res.headers.get('X-RateLimit-Remaining'))
console.log(res.headers.get('X-RateLimit-Reset'))
console.log(res.headers.get('Retry-After'))
console.log(res.headers.get('Deprecation'))
console.log(res.headers.get('Sunset'))
console.log(res.headers.get('Link'))

​
Header → action mapping

A typical agent / SDK consumes these headers like so:
HeaderIf you see…Do
X-RateLimit-Remaining0 or near 0Pause until X-RateLimit-Reset to avoid a 429.
Retry-AfterAnything (on 429)Sleep that many seconds, then retry with the same Idempotency-Key.
Deprecation: trueOn a legacy routeMigrate to the URL in the Link: rel="successor-version" header before Sunset.
SunsetOn a legacy routePlan the migration; the alias stops working at that timestamp.
x-request-idAlwaysLog it; surface it on every customer-facing error.

​
Casing

HTTP headers are case-insensitive. Brew emits x-request-id lowercase, X-RateLimit-* and Retry-After in canonical case; fetch / SDKs read them case-insensitively.

​
See also

​
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:

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.