Documentation

Everything you need to add API rate limiting to your app.

On this page

Quickstart

1. Create an account

Sign up at throttl.xyz to get access to the dashboard.

2. Create an API key

From the dashboard, create a new API key. Choose a plan based on your expected usage.

3. Validate requests

Call the validate endpoint before processing each API request:

bash
curl -X POST https://api.throttl.xyz/api/validate \
  -H "Content-Type: application/json" \
  -d '{"key": "tk_your_api_key_here"}'

4. Handle the response

The API returns whether the request is valid and how many requests remain:

json
{
  "valid": true,
  "remaining": 9847
}

API Reference

POST/api/validate

Validate an API key and increment usage. Call this for each API request you want to track.

Request body

{
  "key": "tk_your_api_key"  // required
}

Response

// Success (200)
{
  "valid": true,
  "remaining": 9847
}

// Success with warning (200)
{
  "valid": true,
  "remaining": 50,
  "alert": "quota_90_percent"
}

// Quota exceeded (429)
{
  "valid": false,
  "error": "quota_exceeded",
  "remaining": 0
}

// Invalid key (401)
{
  "valid": false,
  "error": "invalid_key"
}
GET/api/plans

List all available plans.

Response

[
  {
    "id": "abc123",
    "name": "free",
    "monthlyQuota": 1000,
    "rateLimit": 10
  },
  {
    "id": "def456",
    "name": "pro",
    "monthlyQuota": 50000,
    "rateLimit": 100
  }
]
POST/api/keys

Create a new API key.

Request body

{
  "name": "Production",
  "planId": "abc123",
  "ownerId": "user_123"
}

Response

{
  "id": "key_abc",
  "secret": "tk_xxxxxxxx",  // Only shown once!
  "name": "Production",
  "planId": "abc123",
  "ownerId": "user_123",
  "message": "Store this secret securely"
}

SDK / Middleware

Use our Express middleware to automatically validate and track API requests.

Installation

bash
npm install @throttl/express

Usage

javascript
import express from 'express';
import { throttl } from '@throttl/express';

const app = express();

// Add Throttl middleware
app.use(throttl({
  apiUrl: 'https://api.throttl.xyz'
}));

// Your routes are now protected
app.get('/api/data', (req, res) => {
  res.json({ data: 'protected!' });
});

Webhooks

Configure webhooks to receive notifications when quota thresholds are reached.

Events

  • quota.90_percent — Triggered when usage reaches 90%
  • quota.exceeded — Triggered when quota is exhausted

Payload

json
{
  "event": "quota.90_percent",
  "timestamp": 1705123456789,
  "data": {
    "keyId": "abc123",
    "keyName": "Production",
    "planName": "pro",
    "currentUsage": 45000,
    "monthlyQuota": 50000,
    "percentUsed": 90
  }
}

Need help?

Check out our GitHub or reach out directly.

GitHubContact us