API Guardian — Technical Documentation

Step-by-step instructions for installing, running, and using API Guardian, a self-hosted API proxy designed to prevent runaway API costs, retry storms, and rate-limit outages.

1. Prerequisites

  • Docker (latest version)
  • Docker Compose (latest version)
  • API keys for providers (OpenAI, Groq)

2. Installation

Step 1: Clone the Repository

git clone https://github.com/vaisx05/api-guardian.git
cd api-guardian

Step 2: Configure Environment Variables

cp .env.example .env
REDIS_ADDR=redis:6379

OPENAI_RPM=60
GROQ_RPM=60

OPENAI_DAILY_BUDGET=2000
OPENAI_MONTHLY_BUDGET=30000

GROQ_DAILY_BUDGET=5000
GROQ_MONTHLY_BUDGET=100000

SLACK_WEBHOOK_URL=

Step 3: Start Services

docker compose up --build

3. Usage

Health Check

curl http://127.0.0.1:8080/health

Proxying Requests (OpenAI)

curl http://127.0.0.1:8080/v1/models \
  -H "Host: api.openai.com" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY"

4. Rate Limiting Behavior

  • Per-provider limits based on Host header
  • Limits reset every minute
  • Exceeding limits returns HTTP 429

5. Budget Enforcement

Daily and monthly budgets are enforced per provider. When exceeded, API Guardian returns:

HTTP 402 Payment Required

This indicates cost exhaustion, not a transient failure.

6. Alerts (Optional)

  • 50%, 80%, 100% budget usage alerts
  • Blocked request alerts
  • Slack webhook integration

7. Redis Behavior

CounterTTL
Rate limit~2 minutes
Daily budget48 hours
Monthly budget35 days

8. Supported Providers

  • OpenAI
  • Groq

9. Security Model

  • No payload logging
  • No API keys stored
  • No PII collected
  • Designed for self-hosted environments

10. Philosophy

One blocked runaway request can pay for this tool for a year.
← Back to API Guardian overview