Documentation

API Reference

Complete reference for perfecX G-Rails REST API endpoints and SDK methods.

Base URL

https://api.perfecxion.ai/v1/g-rails

Authentication

All API requests require authentication using an API key.

# HTTP Header
Authorization: Bearer YOUR_API_KEY

# Example with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.perfecxion.ai/v1/g-rails/guardrails

Guardrail Management

Create Guardrail Set

POST/guardrails

Create a new set of guardrails for your AI application.

Request Body

{
  "name": "production_guardrails",
  "description": "Safety guardrails for production chatbot",
  "guardrails": [
    {
      "type": "toxicity",
      "config": {
        "threshold": 0.7,
        "categories": ["hate", "threat", "insult", "profanity"],
        "action": "block",
        "models": ["perspective", "detoxify"]
      }
    },
    {
      "type": "bias",
      "config": {
        "protected_attributes": ["gender", "race", "age"],
        "max_disparity": 0.05,
        "action": "warn",
        "mitigation": "rebalance"
      }
    },
    {
      "type": "pii",
      "config": {
        "detect_types": ["email", "phone", "ssn", "credit_card"],
        "action": "redact",
        "replacement": "[REDACTED]"
      }
    },
    {
      "type": "hallucination",
      "config": {
        "fact_check": true,
        "confidence_threshold": 0.8,
        "sources": ["wikipedia", "trusted_kb"],
        "action": "flag"
      }
    }
  ],
  "metadata": {
    "team": "ai-safety",
    "environment": "production",
    "version": "1.0"
  }
}

Response

{
  "id": "gs_1234567890abcdef",
  "name": "production_guardrails",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "guardrails_count": 4,
  "api_endpoint": "https://api.perfecxion.ai/v1/g-rails/check/gs_1234567890abcdef"
}

List Guardrail Sets

GET/guardrails

Retrieve all guardrail sets for your organization.

Query Parameters

status - Filter by status (active, inactive, testing)
environment - Filter by environment (production, staging, development)
limit - Number of results per page (default: 20)
offset - Pagination offset

Update Guardrail Set

PUT/guardrails/{guardrail_set_id}

Update guardrail configurations and thresholds.

Delete Guardrail Set

DELETE/guardrails/{guardrail_set_id}

Remove a guardrail set from your organization.

Guardrail Checking

Check Input

POST/check/input

Check user input against guardrails before processing.

{
  "guardrail_set_id": "gs_1234567890abcdef",
  "input": "User message to check",
  "context": {
    "user_id": "user_123",
    "session_id": "sess_456",
    "previous_messages": 3
  },
  "options": {
    "explain_violations": true,
    "suggest_alternatives": true
  }
}

Check Output

POST/check/output

Check model output before returning to user.

{
  "guardrail_set_id": "gs_1234567890abcdef",
  "input": "Original user input",
  "output": "Model generated response",
  "model_metadata": {
    "model_name": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 150
  }
}

Response Example

{
  "passed": false,
  "action": "block",
  "violations": [
    {
      "guardrail": "toxicity",
      "score": 0.85,
      "threshold": 0.7,
      "categories": ["profanity"],
      "explanation": "Output contains inappropriate language"
    }
  ],
  "modified_output": null,
  "suggestions": [
    "Consider rephrasing without profanity",
    "Use more professional language"
  ],
  "metadata": {
    "processing_time_ms": 45,
    "guardrails_checked": 4
  }
}

Batch Check

POST/check/batch

Check multiple inputs/outputs in a single request.

Analytics & Monitoring

Get Metrics

GET/metrics

Retrieve guardrail performance metrics and statistics.

{
  "guardrail_set_id": "gs_1234567890abcdef",
  "time_range": {
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-15T23:59:59Z"
  },
  "metrics": {
    "total_checks": 15423,
    "blocked": 342,
    "warnings": 1205,
    "modifications": 892,
    "pass_rate": 0.89,
    "avg_latency_ms": 23.5,
    "violations_by_type": {
      "toxicity": 145,
      "bias": 89,
      "pii": 567,
      "hallucination": 34
    },
    "top_violation_patterns": [
      {"pattern": "profanity", "count": 78},
      {"pattern": "email_exposure", "count": 234},
      {"pattern": "gender_bias", "count": 45}
    ]
  }
}

Get Violations Log

GET/violations

Retrieve detailed violation logs for analysis.

Performance Impact Analysis

GET/analytics/performance

Analyze the performance impact of guardrails on your system.

Configuration & Testing

Test Guardrails

POST/test

Test guardrails with sample inputs without affecting metrics.

{
  "guardrail_set_id": "gs_1234567890abcdef",
  "test_cases": [
    {
      "name": "toxic_input",
      "input": "This is a hate speech example",
      "expected_action": "block"
    },
    {
      "name": "pii_detection",
      "input": "My email is john@example.com",
      "expected_action": "redact"
    }
  ]
}

Get Optimization Recommendations

GET/recommendations/{guardrail_set_id}

Get AI-powered recommendations to optimize your guardrails.

WebSocket API

Real-time guardrail checking via WebSocket connection.

// JavaScript WebSocket example
const ws = new WebSocket('wss://api.perfecxion.ai/v1/g-rails/stream');

ws.on('open', () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    api_key: 'YOUR_API_KEY',
    guardrail_set_id: 'gs_1234567890abcdef'
  }));
});

// Send input for checking
ws.send(JSON.stringify({
  type: 'check_input',
  id: 'msg_123',
  input: 'User message to check'
}));

// Receive results
ws.on('message', (data) => {
  const result = JSON.parse(data);
  if (result.type === 'check_result') {
    console.log('Guardrail result:', result);
  }
});

SDK Methods

Python SDK

from perfecxion_g_rails import GRailsClient

client = GRailsClient(api_key="your-api-key")

# Create guardrail set
guardrails = client.create_guardrail_set(
    name="my_guardrails",
    guardrails=[...]
)

# Check input
result = client.check_input(
    guardrail_set_id=guardrails.id,
    input="User message"
)

# Check output
result = client.check_output(
    guardrail_set_id=guardrails.id,
    input="User input",
    output="Model response"
)

# Get metrics
metrics = client.get_metrics(
    guardrail_set_id=guardrails.id,
    time_range="last_hour"
)

Node.js SDK

import { GRailsClient } from '@perfecxion/g-rails';

const client = new GRailsClient({ apiKey: 'your-api-key' });

// Create guardrail set
const guardrails = await client.createGuardrailSet({
  name: 'my_guardrails',
  guardrails: [...]
});

// Check input
const result = await client.checkInput({
  guardrailSetId: guardrails.id,
  input: 'User message'
});

// Stream checks
const stream = client.streamChecks({
  guardrailSetId: guardrails.id
});

stream.on('violation', (event) => {
  console.log('Violation detected:', event);
});

Rate Limits

Endpoint	Rate Limit
Guardrail Creation	100 per hour
Check Input/Output	10,000 per minute
Batch Check	1,000 per minute
Metrics Retrieval	1,000 per hour
WebSocket Connections	100 concurrent

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

SDK Documentation

Python SDK Documentation Node.js SDK Documentation