Guardail API Documentation

Complete reference for integrating Guardail into your AI pipeline.

Overview

Guardail validates AI-generated outputs against three objective rules:

• Structure — JSON validity, schema matching, type checking
• Arithmetic — Mathematical consistency (e.g., subtotal + tax = total)
• Consistency — Values in output should exist in input (anti-hallucination)

Optionally, Guardail can attempt to repair violations using an LLM.

Authentication

Guardail supports two authentication methods:

RapidAPI (Recommended)

Include the X-RapidAPI-Key header with your RapidAPI subscription key.

X-RapidAPI-Key: your-rapidapi-key

Direct Access

For direct API access, use Bearer authentication with your secret:

Authorization: Bearer YOUR_DIRECT_PROXY_SECRET

Endpoints

POST /v1/guard

Main endpoint for validating and optionally repairing AI outputs.

GET /health

Health check endpoint. Returns:

{
  "ok": true,
  "name": "guardail-api",
  "ts": "2026-01-22T12:00:00.000Z"
}

Request Format

POST to /v1/guard with the following JSON body:

{
  "input": "string",       // Required: Original input text
  "output": any,           // Required: AI-generated output (JSON or string)
  "schema": {              // Required: Expected output schema
    "field_name": "type"
  },
  "policy": {              // Optional: Validation settings
    "rules": ["structure", "arithmetic", "consistency"],
    "strict": true,        // Reject unexpected fields
    "repair": false,       // Enable repair mode
    "max_attempts": 2      // Max repair attempts (1-3)
  },
  "llm": {                 // Optional: BYOK settings for repair
    "provider": "huggingface",
    "hf_token": "hf_...",  // Your Hugging Face token
    "model": "mistralai/Mistral-7B-Instruct-v0.3"
  }
}

Response Format

Successful responses have this structure:

{
  "ok": true,
  "status": "pass" | "failed" | "repaired",
  "output": { ... },       // Validated/repaired output
  "violations": [          // Errors that must be fixed
    {
      "rule": "structure" | "arithmetic",
      "level": "error",
      "message": "Description of the violation"
    }
  ],
  "warnings": [            // Non-blocking issues
    {
      "rule": "consistency",
      "level": "warn",
      "field": "field_name",
      "message": "Description of the warning"
    }
  ],
  "meta": {
    "request_id": "uuid",
    "attempts_used": 1,
    "latency_ms": 12,
    "auth_via": "rapidapi" | "direct"
  }
}

Validation Rules

structure (Error)

Validates that the output is valid JSON and matches your schema.

• Output must be valid JSON
• All required fields must be present
• Field types must match the schema
• In strict mode, no unexpected fields allowed

arithmetic (Error)

Checks mathematical consistency in invoice/financial outputs.

• subtotal + vat = total (or subtotal + tax = total)
• sum(line_items.amount) = total

consistency (Warning)

Detects potential hallucinations by checking if output values exist in input.

• Numbers in output should appear in input
• Dates in output should appear in input
• Proper nouns/entities should appear in input

Repair Mode

When policy.repair: true, Guardail attempts to fix violations using an LLM.

BYOK (Bring Your Own Key)

Provide your Hugging Face token for unlimited repairs:

{
  "policy": { "repair": true },
  "llm": { "hf_token": "hf_YOUR_TOKEN" }
}

Fallback Token

If no BYOK token is provided and fallback is enabled, Guardail uses a shared token with daily quota limits (default: 25 repairs/day per user).

Repair Flow

1. If validation fails with structure or arithmetic errors
2. If repair: true and attempts < max_attempts
3. LLM attempts to fix the output
4. Repaired output is re-validated
5. If valid, status = "repaired"; if still invalid, violations remain

Schema Types

Error Codes

Rate Limits

Default limits (configurable by operator):

• Requests: 60 per 60-second window
• Fallback repairs: 25 per day per user
• Input size: 20,000 characters max
• Output size: 20,000 characters max

Examples

Invoice Validation (Pass)

// Request
{
  "input": "Invoice INV-001 subtotal £83.33 VAT £16.67 total £100",
  "output": {
    "invoice_number": "INV-001",
    "subtotal": 83.33,
    "vat": 16.67,
    "total": 100
  },
  "schema": {
    "invoice_number": "string",
    "subtotal": "number",
    "vat": "number",
    "total": "number"
  }
}

// Response
{
  "ok": true,
  "status": "pass",
  "output": { ... },
  "violations": [],
  "warnings": []
}

Arithmetic Violation (Failed)

// Request
{
  "input": "Invoice subtotal £80 VAT £10 total £100",
  "output": {
    "subtotal": 80,
    "vat": 10,
    "total": 100
  },
  "schema": {
    "subtotal": "number",
    "vat": "number",
    "total": "number"
  }
}

// Response
{
  "ok": true,
  "status": "failed",
  "violations": [{
    "rule": "arithmetic",
    "level": "error",
    "message": "Arithmetic mismatch: subtotal + tax/vat = 90, but total = 100"
  }]
}

Repair Mode (Repaired)

// Request
{
  "input": "User name Alice age 30",
  "output": "Name: Alice, Age: 30",
  "schema": { "name": "string", "age": "number" },
  "policy": { "repair": true },
  "llm": { "hf_token": "hf_YOUR_TOKEN" }
}

// Response
{
  "ok": true,
  "status": "repaired",
  "output": { "name": "Alice", "age": 30 },
  "violations": [],
  "meta": { "attempts_used": 2 }
}