Getting Started

Brume is a hosted rate-limiting gateway built in Rust. You define rules, evaluate requests against them with one HTTP call, and read standard X-RateLimit-* headers. This guide walks you through your first check.

Installation

Install the TypeScript SDK:

npm install @brume/limit

Or with Bun:

bun add @brume/limit

The SDK is a thin typed client over the HTTP API — you can also call the API directly with curl or any HTTP client.

Create a project and an API key

Sign in at app.brume.run, create a project, and mint an API key with the rate_limit scope. The key is shown exactly once — store it in your secret manager.

Create a rule

A rule binds a namespace to an algorithm, a limit, and a window. Create one with the dashboard or the API:

curl -X POST https://api.brume.run/v1/ratelimit/rules \
  -H "Authorization: Bearer $BRUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "api",
    "identifier_type": "user",
    "algorithm": "sliding_window_counter",
    "limit": 100,
    "window_seconds": 60
  }'

This rule allows each user 100 requests per minute against the api namespace.

Make your first check

import { createLimitClient } from '@brume/limit';

const limit = createLimitClient({
  apiKey: process.env.BRUME_API_KEY!,
});

const result = await limit.limit('api', user.id);

if (!result.success) {
  return new Response('Too many requests', {
    status: 429,
    headers: { 'Retry-After': String(result.retry_after ?? 60) },
  });
}

limit() consumes one unit of capacity. check() is read-only — it reports the current state without consuming. Both return the same typed result: success, limit, remaining, reset, retry_after, and degraded.

Read the headers

Every evaluation also sets standard response headers you can forward to your callers:

Next steps

• Learn the four algorithms in Rate Limiting
• Scope your keys in Authentication
• Handle failures in Error Handling