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]

Option	Default	Description
--env	.env	Path to environment file
--config	""	Path to config file defining guards
--port	8000	Port to listen on
--middleware	""	Path to middleware file
--env-override	False	Override existing env vars with values from --env

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]

Argument/Option	Default	Description
revision	head	Target revision
--env	.env	Path to environment file
--env-override	False	Override existing env vars

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]

Argument/Option	Default	Description
revision	-1	Target revision (use -1 to roll back one step)
--env	.env	Path to environment file
--env-override	False	Override existing env vars

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

guardrails-api --version

Print the installed version.

guardrails-api --version

Configuration

Environment Variables

Variable	Default	Description
PORT	8000	Server port
HOST	http://localhost	Host address
GUARDRAILS_LOG_LEVEL	INFO	Log level for Guardrails
LOGLEVEL	INFO	Application log level
GUARDRAILS_API_KEY	—	API key for authenticating requests
APP_ENVIRONMENT	local	Deployment environment label

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

Method	Path	Description
GET	/health-check	Server health status
GET	/guards	List all guards
POST	/guards	Create a guard (requires PostgreSQL)
GET	/guards/{guard_name}	Get a guard by name
PUT	/guards/{guard_name}	Update a guard (requires PostgreSQL)
DELETE	/guards/{guard_name}	Delete a guard (requires PostgreSQL)
POST	/guards/{guard_name}/validate	Run validation against a guard
POST	/guards/{guard_name}/openai/v1/chat/completions	OpenAI ChatCompletion compatiable endpoint for guarded LLM interactions.

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.