Platform Documentation

API Overview

OpenGuardrails provides RESTful APIs built with FastAPI. The platform consists of three independent services: Admin Service (Port 5000), Detection Service (Port 5001), and Proxy Service (Port 5002).

Authentication

OpenGuardrails uses API Key authentication. Include your API key in the Authorization header using Bearer token format.

Authentication Example

# Using cURL
curl -X POST "https://api.openguardrails.com/v1/guardrails" \
  -H "Authorization: Bearer sk-xxai-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "OpenGuardrails-Text",
    "messages": [
      {"role": "user", "content": "Test content"}
    ]
  }'

# Using Python requests
import requests

headers = {
    "Authorization": "Bearer sk-xxai-xxxxxxxxxx",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.openguardrails.com/v1/guardrails",
    headers=headers,
    json={
        "model": "OpenGuardrails-Text",
        "messages": [{"role": "user", "content": "Test content"}]
    }
)

# Note: For private deployment, replace api.openguardrails.com with your server address

API Endpoints

Key API endpoints for safety detection and management.

{
  "model": "optional-model-name",
  "messages": [
    {
      "role": "user",
      "content": "User message content"
    },
    {
      "role": "assistant",
      "content": "Assistant response"
    }
  ],
  "skip_input_guardrails": false,
  "skip_output_guardrails": false
}

{
  "id": "det_xxxxxxxx",
  "result": {
    "compliance": {
      "risk_level": "high_risk",
      "categories": ["Violent Crime"],
      "score": 0.85
    },
    "security": {
      "risk_level": "no_risk",
      "categories": [],
      "score": 0.12
    },
    "data": {
      "risk_level": "no_risk",
      "categories": [],
      "entities": [],
      "score": 0.00
    }
  },
  "overall_risk_level": "high_risk",
  "suggest_action": "Decline",
  "suggest_answer": "Sorry, I cannot answer questions involving violent crime.",
  "score": 0.85
}

{
  "input": "User input text to detect",
  "model": "optional-model-name"
}

{
  "output": "Model output text to detect",
  "model": "optional-model-name"
}

{
  "total_detections": 12450,
  "total_blocked": 342,
  "total_passed": 12108,
  "risk_distribution": {
    "no_risk": 11850,
    "low_risk": 258,
    "medium_risk": 180,
    "high_risk": 162
  }
}

Error Handling

All API errors follow a consistent format with HTTP status codes and error details.

Error Response Format

{
  "detail": "Error message description",
  "error_code": "ERROR_CODE",
  "status_code": 400
}

Detection Capabilities

OpenGuardrails provides multi-dimensional security detection capabilities covering common AI security risks.

Usage Modes

Client Libraries

OpenGuardrails provides client libraries in multiple programming languages for quick integration.

# Synchronous usage
from openguardrails import OpenGuardrails

client = OpenGuardrails("sk-xxai-xxxxxxxxxx")
response = client.check_prompt("test content")

# Asynchronous usage
import asyncio
from openguardrails import AsyncOpenGuardrails

async def main():
    async with AsyncOpenGuardrails("sk-xxai-xxxxxxxxxx") as client:
        response = await client.check_prompt("test content")

asyncio.run(main())

const { OpenGuardrails } = require('openguardrails');

const client = new OpenGuardrails('sk-xxai-xxxxxxxxxx');

async function checkContent() {
    const response = await client.checkPrompt('test content');
    console.log(response.suggest_action);
}

checkContent();

import com.openguardrails.OpenGuardrails;
import com.openguardrails.model.CheckResponse;

public class Example {
    public static void main(String[] args) {
        OpenGuardrails client = new OpenGuardrails("sk-xxai-xxxxxxxxxx");
        CheckResponse response = client.checkPrompt("test content");
        System.out.println(response.getSuggestAction());
    }
}

package main

import (
    "fmt"
    "github.com/openguardrails/openguardrails-go"
)

func main() {
    client := openguardrails.NewClient("sk-xxai-xxxxxxxxxx")
    response, _ := client.CheckPrompt("test content")
    fmt.Println(response.SuggestAction)
}

Multimodal Detection

Support for text and image content safety detection using the same risk classification standards.

Image Detection Example

import base64
from openguardrails import OpenGuardrails

client = OpenGuardrails("sk-xxai-xxxxxxxxxx")

with open("image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

response = client.check_messages([
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Is this image safe?"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"}
            }
        ]
    }
])

print(f"Risk Level: {response.overall_risk_level}")

Data Leak Prevention

Identify and mask sensitive information using regular expressions to prevent personal or corporate data leakage.

Ban Policy

Intelligently identify and defend against persistent prompt injection attacks, automatically ban malicious users.

• Trigger risk level: Only risks reaching specified level will be recorded
• Trigger count: Ban triggered after this many times within time window
• Time window: Time range for counting violations
• Ban duration: Temporary or permanent ban

Knowledge Base Response

Vector similarity-based intelligent Q&A matching, prioritize answers from knowledge base when risks are detected.

Knowledge Base File Format (JSONL)

{"questionid": "q1", "question": "What is AI?", "answer": "AI is artificial intelligence..."}
{"questionid": "q2", "question": "How to protect privacy?", "answer": "Use encryption..."}

Sensitivity Configuration

OpenGuardrails provides three-tier sensitivity configuration to adapt to different usage scenarios.