Response Headers

Every header the Brew Public API v1 sets on responses, request correlation, rate limits, idempotency, deprecation, caching.

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

Header	Example	Notes
x-request-id	req_8cac13fd94e6420cacdd75a1aa403a28	Opaque per-request correlator. Always include in support tickets: Brew engineers can trace your call through the full pipeline.
Cache-Control	no-store	Brew responses are never cached; integrators should not cache them either.
X-RateLimit-Limit	100	Requests allowed in the current rolling 60s window for this route + key.
X-RateLimit-Remaining	73	Requests left before the window exhausts. Honor this to preemptively slow down.
X-RateLimit-Reset	1717891234	Unix epoch seconds when the window resets.

Headers on Specific Responses

Header	When	Format
Retry-After	429 RATE_LIMITED	Integer seconds. Honor verbatim or take max(Retry-After, your-backoff).
X-Credit-Cost	On a successful fixed-cost credit-metered POST (e.g. /v1/content/transform, /v1/content/html-to-png)	Integer credits charged for this call.
X-Credits-Remaining	Alongside X-Credit-Cost on a successful fixed-cost call	Integer balance after the charge.
Deprecation	Only on a deprecated alias route: none are active today	true
Sunset	Only on a deprecated alias route: none are active today	RFC 9745 timestamp, e.g. 2026-12-01T00:00:00Z
Link	Only on a deprecated alias route: none are active today	<…canonical successor URL…>; rel="successor-version"

Usage-metered operations (email generate / edit, image generation) bill the actual model usage and do not emit these headers. Read your balance from GET /v1/usage instead. See Credits for the full metering model.

These deprecation headers are defined for forward-compatibility, but no v1 routes are currently deprecated. You will not see them on any live route today. If a route is ever sunset, the Link header will point at its canonical successor.

Request Headers Brew Honors

Set these on requests when applicable:

Header	Purpose	See
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 24h	Idempotency
Content-Type: application/json	Required on POST / PATCH with a body

Inspecting Headers from Clients

curl

curl -i -H "Authorization: Bearer $BREW_API_KEY" \
  https://brew.new/api/v1/audiences

-i (or -D -) prints the response headers above the body.

TypeScript SDK (Raw Mode)

const { headers, data } = await brew.audiences.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:

Header	If you see…	Do
X-RateLimit-Remaining	0 or near 0	Pause until X-RateLimit-Reset to avoid a 429.
Retry-After	Anything (on 429)	Sleep that many seconds, then retry with the same Idempotency-Key.
Deprecation: true	On a legacy route	Migrate to the URL in the Link: rel="successor-version" header before Sunset.
Sunset	On a legacy route	Plan the migration; the alias stops working at that timestamp.
x-request-id	Always	Log 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

• Rate limits: the canonical 429 cookbook.
• Idempotency: Idempotency-Key semantics.
• Errors: error envelope (the body that pairs with 429 RATE_LIMITED, 409 IDEMPOTENCY_CONFLICT, etc.).
• API introduction: the overview that links every reference page. No v1 routes are currently deprecated, so Deprecation / Sunset / Link are not emitted on any live route today.

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:

Self-Service Tools

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.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.