API Reference
The Guardrails API is where policy meets execution. Every authorization decision, every rule change, every audit record flows through these endpoints—and every action produces verifiable evidence.
Base URL
Local development: http://localhost:8099
Interactive docs
When running locally, FastAPI serves interactive OpenAPI docs at:
http://localhost:8099/docs— Swagger UIhttp://localhost:8099/redoc— ReDoc
Core endpoints
Rules
Rules define what actions are allowed or denied. Each rule change is recorded in the audit chain.
| Method | Endpoint | Description |
|---|---|---|
POST | /rules | Create a new rule |
PUT/PATCH | /rules/{id} | Update an existing rule |
DELETE | /rules/{id} | Soft delete a rule |
Policies
Policies group rules and define enforcement behavior. Policy changes stream through the system immediately—no redeployment required.
| Method | Endpoint | Description |
|---|---|---|
POST | /policies | Create a new policy |
PUT/PATCH | /policies/{id} | Update an existing policy |
DELETE | /policies/{id} | Soft delete a policy |
Decisions
The authorization decision endpoint. Default-deny: requests without valid authorization context are rejected and recorded.
| Method | Endpoint | Description |
|---|---|---|
POST | /authorize | Evaluate an authorization decision |
Every call to /authorize produces an audit record—whether the decision is allow or deny. The record includes the policy evaluated, the actor context, and the outcome.
Audit logs
Query and verify the tamper-evident audit chain.
| Method | Endpoint | Description |
|---|---|---|
GET | /audit-logs | Query audit history |
GET | /audit-logs/verify | Verify hash-chain integrity |
The /audit-logs/verify endpoint returns ok: true when the chain is intact. If any record has been altered, the verification fails.
Server-Sent Events (streams)
Real-time streams for decision events, policy changes, and audit activity.
| Endpoint | Description |
|---|---|
GET /audit-logs/stream | All audit events |
GET /policy-decisions/stream | Authorization decisions only |
GET /policy-changes/stream | Policy CRUD events |
GET /rule-changes/stream | Rule CRUD events |
Use these streams to build dashboards, trigger alerts, or integrate with external systems.
Authentication headers
Most endpoints expect:
Authorization: Bearer <token>
X-Actor-Id: <string>
X-Actor-Type: <string>
The actor context (X-Actor-Id, X-Actor-Type) is recorded in the audit log. This is how you trace who made each decision.
Public SDK
The public SDK repository:
Next steps
- Getting Started — run the API locally
- Proof Demo Guide — see the API in action
- Cryptographic Audit Chains — how verification works