Guardrails API

A FastAPI server that hosts Guardrails AI in your own environment, providing OpenAI-compatible endpoints for applying guards to LLM interactions.

Installation

Requirements: Python 3.10–3.13

pip install guardrails-api

For development:

git clone https://github.com/guardrails-ai/guardrails-api.git
cd guardrails-api
pip install -e ".[dev]"

Quick Start

1. Install Guardrails Hub validators

pip install guardrails-ai-detect-pii

2. Set up your guards

Option A — Config file (in-memory, no database required)

Create a config.py that defines your guards:

from guardrails import Guard
from guardrails_ai.detect_pii import DetectPII

guard = Guard(name="pii-guard")
guard.use(DetectPII(pii_entities=["EMAIL_ADDRESS", "PHONE_NUMBER"]))

Add any additional server settings to your .env file:

PORT=8000
GUARDRAILS_LOG_LEVEL=INFO

Guards are loaded at startup and the API is read-only. Suitable for local development and static deployments.

Option B — PostgreSQL (persistent, full CRUD)

Add database credentials to your .env file using individual variables:

PGHOST=localhost
PGPORT=5432
PGDATABASE=guardrails
PGUSER=postgres
PGPASSWORD=password

Or a single connection URL:

DB_URL=postgresql://postgres:password@localhost:5432/guardrails

When a database is configured, schema migrations run automatically on startup and guards can be created, updated, and deleted via the API.

Guards themselves live in the database, so config.py does not need to define any. However, any validator you plan to use at runtime must be imported at startup so its class is registered in the process. Import them in your config.py:

from guardrails_ai.detect_pii import DetectPII  # noqa: F401 — imported for validator registration

3. Start the server

guardrails-api start --env .env

The server will be available at http://localhost:8000.

• Swagger UI: http://localhost:8000/docs
• Health check: http://localhost:8000/health-check

CLI Reference

guardrails-api start

Start the API server.

guardrails-api start [OPTIONS]

Examples:

# Basic startup
guardrails-api start

# Custom port and config
guardrails-api start --port 9000 --config ./my_guards.py

# Custom env file with override
guardrails-api start --env ./production.env --env-override

guardrails-api db upgrade

Upgrade the database schema (PostgreSQL only).

guardrails-api db upgrade [REVISION] [OPTIONS]

guardrails-api db upgrade
guardrails-api db upgrade abc123ef

guardrails-api db downgrade

Downgrade the database schema (PostgreSQL only).

guardrails-api db downgrade [REVISION] [OPTIONS]

guardrails-api db downgrade
guardrails-api db downgrade -2

guardrails-api --version

Print the installed version.

guardrails-api --version

Configuration

Environment Variables

PostgreSQL (optional)

By default the server uses in-memory storage. To enable persistence, set database connection variables:

# Individual variables
PGHOST=localhost
PGPORT=5432
PGDATABASE=guardrails
PGUSER=postgres
PGPASSWORD=password

# Or a full connection URL
DB_URL=postgresql://postgres:password@localhost:5432/guardrails

# Optional connection extras
DB_EXTRAS=?sslmode=verify-ca
PG_POOL_SIZE=5
PG_POOL_MAX_OVERFLOW=10
PG_POOL_TIMEOUT=30

When PGHOST (or DB_URL) is set, the server will automatically run schema migrations on startup and enable full CRUD operations on guards via the API.

Custom Middleware

Pass a middleware file to register custom Starlette middleware:

# middleware.py
from starlette.middleware.base import BaseHTTPMiddleware

class AuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        # add custom auth logic here
        return await call_next(request)

guardrails-api start --middleware middleware.py

Running in Production

For production, run directly with uvicorn or gunicorn:

# uvicorn
uvicorn --factory 'guardrails_api.app:create_app' --host 0.0.0.0 --port 8000 --workers 4

# gunicorn
gunicorn -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 "guardrails_api.app:create_app()"

API Endpoints

Storage Modes

In-memory (default): Guards are loaded from config.py at startup. The API is read-only — guards cannot be created or updated via the API.

PostgreSQL: Full CRUD via the API. Guards are persisted in the database, not seeded from config.py. Schema migrations run automatically on startup, and any validators imported in config.py are registered so they can be referenced by guards created via the API.