API Reference

REST API Reference

Complete reference for the DriftRail API. All endpoints require authentication via API key.

Base URL

Production: https://api.driftrail.com

Authentication

Include your API key in the Authorization header:

Authorization: Bearer aso_live_your_api_key_here

Alternative: Use X-API-Key header.

Key Formats

Environment Prefix Example
Production aso_live_ aso_live_a1b2c3d4...
Staging aso_test_ aso_test_e5f6g7h8...
Development aso_dev_ aso_dev_i9j0k1l2...

Rate Limits

Plan Requests/min Burst
Starter60100
Growth300500
Pro1,0002,000
EnterpriseCustomCustom

Per-key rate limits can be configured via the API Keys endpoint.

Error Codes

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions or scope
404Not Found - Resource doesn't exist
415Unsupported Media Type - Use application/json
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Inline Guard

Real-time content safety check. Blocks dangerous outputs before they reach users. <50ms latency.

POST /api/guard Critical Path

Request Body

{
  "output": "The LLM response to check",
  "input": "Optional user prompt for context",
  "mode": "strict",
  "timeout_ms": 100,
  "skip_classification": false
}
mode: "strict" (block medium+ risk) or "permissive" (high only)
timeout_ms: Classification timeout (max 500ms)

Response

{
  "allowed": true,
  "action": "allow",
  "output": "The LLM response to check",
  "triggered": [],
  "classification": {
    "risk_score": 15,
    "pii": { "detected": false, "types": [] },
    "toxicity": { "detected": false, "severity": "none" },
    "prompt_injection": { "detected": false, "risk": "none" }
  },
  "latency_ms": 42,
  "fallback": false
}

Fail-Open: If classification times out, allowed: true and fallback: true are returned.

Ingest

Log an LLM inference event for async classification and monitoring.

POST /ingest

Request Body

{
  "model": "gpt-5",
  "provider": "openai",
  "input": {
    "prompt": "What is the capital of France?",
    "messages": [{ "role": "user", "content": "..." }],
    "retrievedSources": [{ "id": "doc-1", "content": "..." }]
  },
  "output": {
    "text": "The capital of France is Paris.",
    "toolCalls": []
  },
  "metadata": {
    "latencyMs": 420,
    "tokensIn": 25,
    "tokensOut": 12,
    "temperature": 0.7
  }
}

Response (202 Accepted)

{
  "success": true,
  "event_id": "evt_a1b2c3d4...",
  "job_id": "job_e5f6g7h8..."
}

Events

Query logged inference events with optional filters.

GET /api/events

Query Parameters

event_idstringGet specific event app_idstringFilter by application environmentstringprod, staging, dev modelstringFilter by model name start_timeISO8601Start of time range end_timeISO8601End of time range limitintegerMax results (default: 100) offsetintegerPagination offset

Classifications

List classification results with risk scores and detected issues.

GET /api/classifications

List all classifications with filters for risk score and time range.

GET /api/classifications/distribution

Get risk distribution statistics (low, medium, high counts).

GET /api/classifications/high-risk

Get high-risk events above threshold (default: 70).

Stats

Get aggregated statistics for your application.

GET /api/stats

Query param: period = 1h, 24h, 7d, 30d

{
  "period": "24h",
  "events": { "total": 5000, "by_environment": {...} },
  "models": [{ "model": "gpt-5", "count": 3000 }],
  "risk": { "low": 4200, "medium": 650, "high": 150 },
  "latency": { "avg_ms": 520, "p95_ms": 1200 },
  "alerts": { "critical": 1, "warning": 3, "info": 8 }
}

API Keys

Manage API keys with scoping, IP allowlisting, expiration, and usage analytics.

GET /api/keys

List all API keys with usage stats.

POST /api/keys

Create new API key with optional scopes, IP restrictions, expiration.

{
  "name": "Production API",
  "environment": "prod",
  "scopes": ["read", "write", "ingest", "guard"],
  "allowed_ips": ["192.168.1.0/24"],
  "expires_at": "2025-12-31T23:59:59Z",
  "rate_limit_override": 500
}
PATCH /api/keys/rotate

Rotate a key with optional grace period.

GET /api/keys/usage

Get usage overview across all keys.

DELETE /api/keys?key_id=xxx

Revoke an API key.

Scopes: read, write, ingest, guard, admin, * (all)

Guardrails

Configure rule-based guardrails for content filtering.

GET /api/guardrails

List all guardrails.

POST /api/guardrails

Create a guardrail rule.

{
  "name": "Block PII",
  "rule_type": "block_pii",
  "action": "block",
  "config": { "types": ["email", "phone", "ssn"] }
}
POST /api/guardrails/check

Test content against guardrails.

Rule Types: block_high_risk, block_pii, block_toxicity, block_prompt_injection, custom_regex, custom_keywords

Actions: flag, block, redact, warn

Detections

Configure detection types and custom classifiers.

GET /api/detections/types

List available detection types for your tier.

PUT /api/detections/settings

Update enabled detections.

POST /api/detections/custom Pro+

Add custom detection with your own prompt.

Webhooks

Register webhook endpoints for real-time notifications.

POST /api/webhooks

Register a webhook (HTTPS required).

{
  "url": "https://your-app.com/webhook",
  "events": ["alert.critical", "classification.high_risk"]
}

Events: alert.created, alert.critical, usage.threshold, classification.high_risk

Integrations

Connect to Slack, Teams, or Discord for notifications.

POST /api/integrations

Create integration.

{
  "type": "slack",
  "webhook_url": "https://hooks.slack.com/...",
  "channel_name": "#ai-alerts",
  "events": ["alert.critical", "incident.created"]
}
POST /api/integrations/test

Test a webhook URL before saving.

Types: slack, teams, discord

Projects

Organize your AI applications into projects with separate keys and guardrails.

GET /api/projects

List all projects.

POST /api/projects

Create a new project.

GET /api/projects/:id/keys

List project API keys.

GET /api/projects/:id/guardrails

List project-specific guardrails.

GET /api/projects/:id/usage

Get project usage statistics.

Incidents

Track and manage AI safety incidents.

GET /api/incidents

List incidents with status/severity filters.

POST /api/incidents

Create an incident.

{
  "title": "High hallucination rate detected",
  "description": "Hallucination rate spiked to 15%",
  "severity": "high",
  "incident_type": "hallucination_spike"
}
PATCH /api/incidents/:id/status

Update incident status (open, investigating, mitigating, resolved, closed).

GET /api/incidents/stats

Get incident statistics including MTTR.

Compliance

Manage compliance frameworks and GDPR data subject requests.

GET /api/compliance/status

Get compliance framework status (HIPAA, SOC2, GDPR, PCI-DSS).

PUT /api/compliance/settings

Update compliance settings.

{
  "hipaa_enabled": true,
  "gdpr_enabled": true,
  "pii_auto_redact": true,
  "pii_redaction_level": "standard",
  "data_region": "eu"
}
POST /api/compliance/dsar

Create GDPR Data Subject Access Request.

""

Model Comparison

Compare model performance and run A/B tests.

GET /api/models/leaderboard

Get model performance leaderboard. Metrics: avg_risk_score, avg_latency_ms, hallucination_rate, error_rate.

POST /api/models/comparisons

Create A/B test comparison between two models.

GET /api/models/performance/:model

Get performance history for a specific model.

Exports

Export data for compliance audits and analysis.

POST /api/exports

Create an export job.

{
  "export_type": "events",
  "format": "json",
  "date_from": "2026-01-01T00:00:00Z",
  "date_to": "2026-01-31T23:59:59Z"
}
GET /api/exports/download/:id

Download completed export file.

Types: events, classifications, audit_logs, incidents, full_audit

Formats: json, csv, pdf

Brand Safety

Protect your brand with content rules and competitor monitoring.

POST /api/brand-safety/rules

Create a brand safety rule.

{
  "name": "Block Competitor Mentions",
  "rule_type": "competitor_mentions",
  "config": { "terms": ["CompetitorA", "CompetitorB"] },
  "action": "flag",
  "severity": "medium"
}
POST /api/brand-safety/check

Check text against brand safety rules.

Rule Types: blocked_terms, competitor_mentions, sentiment_threshold, topic_restriction, custom_regex

Retention

Configure data retention policies for compliance.

POST /api/retention

Create a retention policy.

{
  "name": "Production Events - 90 days",
  "data_type": "inference_events",
  "retention_days": 90,
  "environment_filter": ["prod"]
}
GET /api/retention/summary

Get retention summary with deletion stats.

Audit Logs

Search, stream, and export audit logs. Configure SIEM integration.

GET /api/logs

Search logs with filters (level, action, actor, resource, time range).

GET /api/logs/stats

Get log statistics by level and action.

POST /api/logs/export

Configure SIEM export (Splunk, Datadog, etc.).

PUT /api/logs/sampling

Configure log sampling for high-volume environments.

PUT /api/logs/retention

Configure log retention with optional archiving.

AI Playground

Test AI models with real-time DriftRail safety monitoring.

GET /api-playground

Get usage limits and available models.

POST /api-playground

Send a message and get AI response with detections.

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "model": "gemini-flash-lite-latest",
  "runDetections": true
}

Limits: Starter: 25/mo, Growth: 500/mo, Pro: 2,500/mo, Enterprise: 10,000+/mo

Alerts

Manage drift alerts and notifications.

GET /api/alerts

List alerts with severity and status filters.

PATCH /api/alerts

Acknowledge or resolve an alert.