API Reference - EthicalZen.ai

🔐 Authentication Overview

EthicalZen APIs use two authentication methods depending on the use case:

🔑 API Key Authentication (Recommended for Integrations)

For programmatic access, REST APIs, CLI tools, and CI/CD pipelines.

curl -X POST https://api.ethicalzen.ai/api/gateway/register \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_name": "My Service"}'

Getting your API key: Sign up at auth-portal.html → Receive API key via email → Use in X-API-Key header

🎫 JWT Session Authentication (Dashboard Only)

For browser-based session management in the dashboard UI.

// Browser automatically manages session cookies
fetch('/api/auth/login', {
  method: 'POST',
  credentials: 'include',
  body: JSON.stringify({email, password})
})

Usage: Dashboard pages use JWT tokens in HTTP-only cookies for session management. Not recommended for API integrations.

💡 Quick Tip: All API examples in this documentation use $ETHICALZEN_API_KEY environment variable. Set it with:
export ETHICALZEN_API_KEY="sk-your-api-key-here"

🔑 Authentication API

Endpoints for user authentication, registration, and session management.

POST /api/auth/login

Authenticate a user and receive a JWT token.

Request Body:

{
  "email": "user@company.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@company.com",
    "companyId": "company-uuid"
  }
}

POST /api/auth/register

Register a new company and admin user.

Request Body:

{
  "companyName": "Acme Healthcare",
  "email": "admin@acme.com",
  "password": "secure-password",
  "firstName": "John",
  "lastName": "Doe"
}

POST /api/auth/google

Authenticate with Google OAuth.

Request Body:

{
  "credential": "google-id-token",
  "plan": "professional"
}

🏢 Tenant Management API

Endpoints for managing multi-tenant accounts and API keys.

GET /api/tenants/me

Get current tenant information.

Headers:

Header	Value	Description
`X-API-Key`	`$ETHICALZEN_API_KEY`	Your EthicalZen API key

Response:

{
  "success": true,
  "tenant": {
    "tenant_id": "tenant-7f3a8b2c",
    "company_name": "Acme Healthcare",
    "contact_email": "admin@acme.com",
    "plan": "enterprise",
    "gateway_url": "https://gateway.ethicalzen.ai",
    "status": "active"
  }
}

POST /api/tenants/rotate-key

Rotate API key (live or test).

Request Body:

{
  "environment": "live"  // or "test"
}

Response:

{
  "success": true,
  "new_api_key": "acvps_live_sk_NEW_KEY_HERE",
  "message": "Old key will stop working in 24 hours"
}

🛠️ Guardrail Development Kit (GDK)

NEW - Complete toolkit for designing, developing, testing, and deploying custom guardrails.

🚀 Quick Start: Get started in 5 minutes with our interactive tools!

Live Playground: Test guardrails in real-time
Quick Start Guide: 5-Minute Tutorial
API Playground: Test API endpoints

👨‍💻 Developer Experience: See the full lifecycle in action!

Run our Alex's Journey script to simulate exploring, cloning, fine-tuning, and deploying a custom Smart Guardrail guardrail using these APIs.

npx ts-node tests/alex-experience.ts

Register Custom Guardrail

POST /api/guardrails/register

Register a new custom guardrail (pattern-based or LLM-assisted)

Request Body

Parameter	Type	Required	Description
`id`	string	Required	Unique guardrail ID (lowercase, underscores only)
`name`	string	Required	Human-readable name
`description`	string	Required	What this guardrail validates
`prompt_template`	string	Optional	LLM prompt for validation (use {{text}} placeholder)
`keywords`	string[]	Optional	Keywords for pattern matching (fallback)
`metric_name`	string	Optional	Output metric name (default: compliance_score)
`threshold`	number	Optional	Min acceptable score 0.0-1.0 (default: 0.75)
`invert_score`	boolean	Optional	True for "risk" metrics (high = bad)

Example: Pattern-Based Guardrail

curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/guardrails/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
    "id": "profanity_filter_v1",
    "name": "Profanity Filter",
    "description": "Blocks profanity and offensive language",
    "keywords": ["profanity", "offensive", "vulgar"],
    "metric_name": "profanity_score",
    "threshold": 0.9,
    "invert_score": true
  }'

Example: LLM-Assisted Guardrail

curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/guardrails/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
    "id": "financial_advice_blocker_v1",
    "name": "Financial Advice Blocker",
    "description": "Prevents unauthorized investment advice",
    "prompt_template": "Check if this provides investment advice without disclaimers:\n\n{{text}}\n\nReturn JSON with violates_policy and confidence.",
    "keywords": ["guaranteed returns", "risk-free", "insider"],
    "metric_name": "financial_advice_risk",
    "threshold": 0.85,
    "invert_score": true
  }'

Response

{
  "success": true,
  "guardrail_id": "profanity_filter_v1",
  "message": "Guardrail 'Profanity Filter' registered successfully",
  "source": "generic_llm_template"
}

List Available Guardrails

GET /api/guardrails/list

Get all available guardrails (built-in and custom)

Example Request

curl https://acvps-gateway-mqnusyobga-uc.a.run.app/api/guardrails/list

Response

{
  "success": true,
  "count": 8,
  "guardrails": [
    {
      "id": "pii_detector_v1",
      "name": "PII Detector",
      "description": "Detects PII (SSN, email, phone) in responses",
      "type": "static",
      "version": "1.0.0"
    },
    {
      "id": "profanity_filter_v1",
      "name": "Profanity Filter",
      "description": "Blocks profanity and offensive language",
      "type": "dynamic",
      "version": "1.0.0"
    }
  ]
}

Test Guardrail (Extract Features)

POST /api/extract-features

Test a guardrail against sample text in real-time

Request Body

Parameter	Type	Required	Description
`feature_extractor_id`	string	Required	Guardrail ID to test
`payload.output`	string	Required	AI response text to validate

Example Request

curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/extract-features \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
    "feature_extractor_id": "profanity_filter_v1",
    "payload": {
      "output": "This response contains inappropriate language."
    }
  }'

Response

{
  "features": {
    "profanity_score": 0.85
  },
  "detection_method": "acvps_gateway",
  "extraction_time_ms": 2
}

List Guardrail Configs

GET /api/guardrails/configs

Get detailed configuration for all custom guardrails

Response

{
  "success": true,
  "count": 2,
  "configs": [
    {
      "id": "profanity_filter_v1",
      "name": "Profanity Filter",
      "description": "Blocks profanity and offensive language",
      "keywords": ["profanity", "offensive", "vulgar"],
      "metric_name": "profanity_score",
      "threshold": 0.9,
      "invert_score": true,
      "registered_at": "2025-11-11T00:00:00Z",
      "type": "dynamic"
    }
  ]
}

🧪 Interactive Testing

Guardrail Playground - Live Testing

Test guardrails interactively with real-time feedback from your GuardRails Runtime Gateway

🚀 Open Playground

Playground Features

Live Gateway Connection: Real-time testing against running gateway
All Guardrails: Test built-in and custom guardrails
Quick Scenarios: Pre-built test cases (PII, profanity, financial, medical, etc.)
Test History: Track your test runs and results
API Inspector: See exact request/response payloads
Performance Metrics: Measure guardrail execution time

📚 Pre-Built Templates

The GDK includes production-ready guardrail templates:

Template	Use Case	Type	Threshold
`financial_compliance_v1`	SEC regulations, block unauthorized advice	LLM	85%
`medical_advice_blocker_v1`	Block diagnoses without disclaimers	LLM	30% (inverted)
`content_moderation_v1`	Hate speech, violence detection	LLM	90%
`hipaa_compliance_v1`	Prevent PHI exposure	Hybrid	95%
`legal_advice_blocker_v1`	Prevent legal advice without disclaimers	LLM	25% (inverted)

🔄 Development Workflow

Step 1: Design (Choose Type)

Pattern-Based: Fast (~1ms), deterministic, free
LLM-Assisted: Smart (~500ms), contextual, $0.01/request
Hybrid: Pattern fallback + LLM accuracy

Step 2: Develop (Register via API or UI)

# Via API
curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/guardrails/register \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{...}'

# Via API
Use the guardrail registration endpoint above

Step 3: Test (Playground or API)

# Via Playground
Open /guardrail-playground.html → Select guardrail → Run test

# Via API
curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/extract-features \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
  "feature_extractor_id": "your_guardrail_v1",
  "payload": {"output": "test text"}
}'

Step 4: Deploy (Add to Contract)

curl -X POST https://acvps-gateway-mqnusyobga-uc.a.run.app/api/contracts \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
  "contract_id": "my-contract/v1.0",
  "contract": {
    "feature_extractor": {
      "id": "your_guardrail_v1",
      "version": "1.0.0"
    },
    "envelope": {
      "constraints": {
        "your_metric": {"min": 0.0, "max": 0.3}
      }
    }
  }
}'

Step 5: Monitor (Track Violations)

# Query violations via API
GET /api/violations

# View evidence logs
GET /api/evidence?trace_id={id}

💡 Best Practices

Use Pattern-Based for High Volume: >1000 req/s → Pattern-based (free, fast)
Use LLM for Accuracy-Critical: Financial/Medical/Legal → LLM (95%+ accuracy)
Always Provide Keywords: Pattern fallback ensures system works without LLM
Test Before Production: Use Playground to validate with real scenarios
Set Appropriate Thresholds: 90+ strict, 70-80 balanced, <70 lenient
Version Your Guardrails: Use _v1, _v2 suffixes for updates
Monitor Performance: Track execution time and adjust complexity

📖 Additional Resources

📜 Contract Registry API

Endpoints for managing deterministic contracts.

POST /api/dc/contracts

Register a new deterministic contract.

Request Body:

{
  "id": "patient-intake/healthcare/us/v1.0",
  "version": "1.0.0",
  "suite": "Ed25519-SHA256",
  "description": "Patient intake AI with HIPAA compliance",
  "envelope": {
    "pii_risk": { "max": 0.1 },
    "grounding_confidence": { "min": 0.9 }
  },
  "feature_extractor": "pii-detector-v1",
  "failover_profile": "block_and_log"
}

Response:

{
  "success": true,
  "contract": {
    "id": "patient-intake/healthcare/us/v1.0",
    "status": "draft",
    "policy_digest": "sha256:a7c...2e0",
    "created_at": "2025-11-01T18:00:00Z"
  }
}

GET /api/dc/contracts

List all contracts for your tenant.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status (draft, active, revoked)
`limit`	number	Number of results (default: 50)
`offset`	number	Pagination offset (default: 0)

POST /api/dc/contracts/:id/activate

Activate a draft contract.

Request Body:

{
  "signature": "ed25519-signature-here",
  "public_key": "ed25519-public-key"
}

📸 Evidence Logging API

Endpoints for logging and querying evidence with blockchain anchoring.

POST /api/dc/evidence

Log evidence for a contract validation.

Request Body:

{
  "trace_id": "trace-1234567",
  "dc_id": "patient-intake/healthcare/us/v1.0",
  "policy_digest": "sha256:a7c...2e0",
  "features": {
    "pii_risk": 0.05,
    "grounding_confidence": 0.95
  },
  "outcome": "ALLOW",
  "timestamp": "2025-11-01T18:00:00Z"
}

GET /api/dc/evidence

Query evidence logs.

Query Parameters:

Parameter	Type	Description
`dc_id`	string	Filter by contract ID
`trace_id`	string	Filter by trace ID
`outcome`	string	Filter by outcome (ALLOW, BLOCK)
`limit`	number	Number of results

⚙️ Feature Extractors API

Endpoints for managing feature extractors.

GET /api/dc/extractors

List all available feature extractors.

Response:

{
  "success": true,
  "extractors": [
    {
      "id": "pii-detector-v1",
      "version": "1.0.0",
      "features": ["pii_risk", "grounding_confidence", "hallucination_risk"],
      "description": "Detects PII leakage and validates grounding"
    }
  ]
}

GET /api/dc/extractors/:id

Get detailed information about a specific extractor.

📋 Policy Management API

Endpoints for managing company-wide AI ethics policies.

GET /api/policies

List all policies for your company.

POST /api/policies

Create a new policy.

Request Body:

{
  "name": "HIPAA Compliance Policy",
  "description": "Ensures HIPAA compliance for healthcare AI",
  "rules": [
    {
      "type": "pii_detection",
      "threshold": 0.1,
      "action": "block"
    }
  ]
}

⚠️ Violation Tracking API

Endpoints for tracking and analyzing policy violations.

GET /api/violations

List all violations for your company.

Query Parameters:

Parameter	Type	Description
`severity`	string	Filter by severity (high, medium, low)
`start_date`	date	Start date for range query
`end_date`	date	End date for range query

Response:

{
  "success": true,
  "violations": [
    {
      "id": "violation-uuid",
      "trace_id": "trace-1234567",
      "contract_id": "patient-intake/healthcare/us/v1.0",
      "type": "pii_leakage",
      "feature": "pii_risk",
      "value": 0.89,
      "threshold": 0.1,
      "timestamp": "2025-11-01T10:45:12Z"
    }
  ]
}

GET /api/violations/stats

Get violation statistics and trends.

Response:

{
  "success": true,
  "stats": {
    "total_violations": 542,
    "by_type": {
      "pii_leakage": 218,
      "hallucination": 182,
      "low_grounding": 142
    },
    "trend_30d": -15.2
  }
}

👥 Team Management API

Endpoints for managing team members and permissions.

GET /api/teams

List all teams in your company.

POST /api/teams

Create a new team.

Request Body:

{
  "name": "Healthcare AI Team",
  "description": "Team managing healthcare AI services"
}

POST /api/teams/:id/members

Add a member to a team.

Request Body:

{
  "developerId": "user-uuid",
  "role": "member"  // or "lead"
}

DELETE /api/teams/:id/members/:developerId

Remove a member from a team.

🔐 Admin API

Administrative endpoints for tenant management (admin access only).

POST /admin/api/tenants/create

Create a new tenant (admin only).

Headers:

Header	Value
`X-API-Key`	`$ETHICALZEN_API_KEY`
`X-Admin-User`	`admin@ethicalzen.ai`

Request Body:

{
  "company_name": "Acme Healthcare",
  "contact_email": "admin@acme.com",
  "plan": "enterprise",
  "deployment_type": "public"
}

Response:

{
  "success": true,
  "tenant_id": "tenant-7f3a8b2c",
  "api_key_live": "acvps_live_sk_...",
  "api_key_test": "acvps_test_sk_...",
  "gateway_url": "https://gateway.ethicalzen.ai"
}

GET /admin/api/tenants

List all tenants (admin only).

POST /admin/api/tenants/:tenantId/suspend

Suspend a tenant (admin only).

🔧 Service Registration API

Endpoints for registering AI services and generating contracts with automated risk analysis.

POST /api/usecases/register

Register a new AI service and auto-generate a deterministic contract with domain-specific risk analysis.

Headers:

Header	Value	Description
`X-API-Key`	`$ETHICALZEN_API_KEY`	Your EthicalZen API key

Request Body:

{
  "service_name": "medical-diagnosis-ai",
  "use_case": "Clinical decision support system",
  "domain": "healthcare",  // healthcare | finance | legal | ecommerce | other
  "region": "us",
  "tenant_id": "hospital-alpha",  // Multi-tenant support
  "api_endpoint": "https://api.example.com/diagnose"  // Optional for live testing
}

Response:

{
  "success": true,
  "message": "Service registered successfully",
  "contract_id": "medical-diagnosis-ai/general/us/v1.0",
  "evaluation_id": "eval_1762697134967",
  "contract": {
    "id": "medical-diagnosis-ai/general/us/v1.0",
    "status": "pending",
    "risk_analysis": {
      "risk_score": 95,
      "risk_factors": ["Healthcare industry", "High data sensitivity (PHI)"],
      "failure_modes": [...],
      "safety_guardrails": [...]
    }
  }
}

Automatic Actions:

✅ Domain-specific risk analysis
✅ Failure mode identification
✅ Guardrail recommendation
✅ Simulation initiation (16 AI-generated test cases)

cURL Example:

curl -X POST https://api.ethicalzen.ai/api/usecases/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ETHICALZEN_API_KEY" \
  -d '{
    "service_name": "medical-diagnosis-ai",
    "use_case": "Clinical decision support system",
    "domain": "healthcare",
    "region": "us",
    "tenant_id": "hospital-alpha"
  }'

GET /api/contracts

List all contracts for your tenant (JWT authenticated).

GET /api/contracts/active

[NEW] Get all active contracts for Gateway enforcement (multi-tenant, no auth required).

Response:

{
  "success": true,
  "summary": {
    "total_contracts": 3,
    "tenants": 2
  },
  "contracts_by_tenant": {
    "hospital-alpha": [
      {
        "id": "medical-diagnosis-ai/general/us/v1.0",
        "service_name": "medical-diagnosis-ai",
        "tenant_id": "hospital-alpha",
        "guardrails": [...],
        "envelope": {...},
        "certificate_id": "cert_..."
      }
    ]
  }
}

Note: Gateway polls this endpoint every 5 minutes to sync active contracts.

✅ Evaluation & Simulation API

Endpoints for running simulations, viewing results, and approving contracts.

GET /api/simulation-results/:evaluationId

Get simulation/evaluation results with detailed test breakdowns.

Response:

{
  "success": true,
  "evaluationId": "eval_1762697134967",
  "status": "completed",
  "simulation_results": {
    "total_tests": 16,
    "passed": 14,
    "failed": 2,
    "pass_rate": 0.875,
    "results": [
      {
        "test_id": "test_1",
        "input": "Patient data with SSN",
        "output": "Diagnosis without PII",
        "scores": {
          "pii_risk": 0.02,
          "hallucination_risk": 0.05
        },
        "violations": [],
        "passed": true
      }
    ]
  }
}

POST /api/evaluation/approve

[NEW] Approve a contract and issue certificate. Sets status='active' and approved=true.

Request Body:

{
  "evaluationId": "eval_1762697134967",
  "contractId": "medical-diagnosis-ai/general/us/v1.0"
}

Response:

{
  "success": true,
  "message": "Contract approved successfully",
  "certificateId": "cert_1762697290054_nfyxt38qz",
  "approvedBy": "system",
  "approvedAt": "2025-11-09T14:06:30.054Z"
}

Automatic Actions:

✅ Sets contract status to 'active'
✅ Sets approved flag to true
✅ Generates compliance certificate
✅ Immediately available to Gateway via /api/contracts/active

POST /api/evaluation/run

Manually trigger evaluation for a contract (useful for re-testing after updates).

Request Body:

{
  "contractId": "medical-diagnosis-ai/general/us/v1.0",
  "mode": "synthetic"  // or "live_api" for testing deployed endpoint
}

🚪 GuardRails Runtime Gateway Proxy API

Main endpoint for routing AI requests through deterministic contract enforcement.

POST /api/proxy

Proxy an AI request through the GuardRails Runtime Gateway with contract enforcement.

Headers:

Header	Value	Description
`X-DC-Id`	`contract-id`	Contract ID to enforce
`X-DC-Trace`	`trace-id`	Unique trace ID for this request
`X-Tenant-ID`	`tenant-id`	Your tenant ID

Request Body:

{
  "prompt": "What are the symptoms of diabetes?",
  "context": {
    "patient_id": "P12345",
    "session": "intake-001"
  }
}

Response (Allowed):

{
  "allowed": true,
  "response": {
    "text": "Common symptoms of diabetes include...",
    "confidence": 0.95
  },
  "features": {
    "pii_risk": 0.02,
    "grounding_confidence": 0.95,
    "hallucination_risk": 0.05
  },
  "trace_id": "trace-1234567"
}

Response (Blocked):

{
  "allowed": false,
  "reason": "PII_LEAKAGE_DETECTED",
  "details": {
    "feature": "pii_risk",
    "value": 0.89,
    "threshold": 0.1
  },
  "evidence_logged": true,
  "trace_id": "trace-1234567"
}

🛡️ Gateway Enforcement API

[NEW - Multi-Tenant Contract Enforcement] Endpoints for real-time validation and multi-guardrail enforcement.

POST /validate

Gateway Port: 8443 - Validate payload against contract with feature extraction and envelope checking.

Request Body:

{
  "contract_id": "medical-diagnosis-ai/general/us/v1.0",
  "tenant_id": "hospital-alpha",  // Multi-tenant required
  "payload": {
    "output": "Patient John Doe (SSN: 123-45-6789) has pneumonia."
  }
}

Response:

{
  "success": true,
  "contract_id": "medical-diagnosis-ai/general/us/v1.0",
  "tenant_id": "hospital-alpha",
  "allowed": false,
  "features": {
    "pii_risk": 0.95,
    "pii_detected": ["SSN", "name"]
  },
  "violations": [
    {
      "metric": "pii_risk",
      "threshold": 0.05,
      "actual": 0.95,
      "message": "PII risk exceeds threshold"
    }
  ]
}

POST /enforce

[NEW] Multi-guardrail enforcement with detailed violation tracking. Runs ALL guardrails defined in contract.

Request Body:

{
  "contract_id": "medical-diagnosis-ai/general/us/v1.0",
  "tenant_id": "hospital-alpha",
  "payload": {
    "output": "The patient's test results show normal glucose levels."
  }
}

Response:

{
  "success": true,
  "contract_id": "medical-diagnosis-ai/general/us/v1.0",
  "tenant_id": "hospital-alpha",
  "service_name": "medical-diagnosis-ai",
  "allowed": true,
  "guardrails_evaluated": 3,
  "guardrails": [
    {
      "guardrail_id": "pii_protection",
      "guardrail_name": "PII Protection",
      "score": 0.98,
      "threshold": 0.95,
      "passed": true,
      "result": {...}
    },
    {
      "guardrail_id": "hallucination_check",
      "score": 0.92,
      "threshold": 0.90,
      "passed": true
    }
  ],
  "violations": []
}

Enforcement Logic:

1. Looks up contract by contract_id + tenant_id
2. Runs all guardrails defined in contract
3. Evaluates each guardrail against threshold
4. Returns allowed=true ONLY if ALL guardrails pass
5. Records detailed results for audit trail

⚙️ Gateway Management API

[NEW] Endpoints for contract synchronization, tenant management, and dynamic guardrail registration.

GET /contracts/tenant/:tenantId

[NEW] Get all loaded contracts for a specific tenant.

Example:

GET /contracts/tenant/hospital-alpha

Response:

{
  "success": true,
  "tenant_id": "hospital-alpha",
  "contracts": [
    {
      "id": "medical-diagnosis-ai/general/us/v1.0",
      "service_name": "medical-diagnosis-ai",
      "guardrails": [...],
      "certificate_id": "cert_..."
    }
  ],
  "guardrails": ["pii_protection", "hallucination_check"],
  "last_updated": "2025-11-09T14:06:09.722Z"
}

GET /contracts/loaded

[NEW] Get summary of all loaded contracts across all tenants.

Response:

{
  "success": true,
  "total_tenants": 3,
  "total_contracts": 7,
  "sync_status": {
    "last_sync": "2025-11-09T14:06:09.722Z",
    "status": "success",
    "attempts": 5,
    "successes": 5
  },
  "tenants": {
    "hospital-alpha": {
      "count": 3,
      "guardrails": 8,
      "last_updated": "2025-11-09T14:06:09.722Z"
    }
  }
}

POST /contracts/sync

[NEW] Force immediate contract sync from Portal Backend.

Response:

{
  "success": true,
  "message": "Sync completed",
  "details": {
    "tenants": 3,
    "contracts": 7,
    "guardrails": 15
  }
}

Note: Gateway automatically syncs every 5 minutes. Use this for immediate updates after contract approval.

POST /guardrails/register

Register a new guardrail configuration dynamically at runtime.

Request Body:

{
  "id": "custom_bias_check",
  "name": "Custom Bias Checker",
  "description": "Detects demographic bias in outputs",
  "threshold": 0.90,
  "metric_name": "fairness_score",
  "prompt_template": "Analyze this text for demographic bias: {{text}}",
  "keywords": ["bias", "discrimination", "unfair"]
}

Response:

{
  "success": true,
  "guardrail_id": "custom_bias_check",
  "message": "Guardrail 'Custom Bias Checker' registered successfully",
  "source": "generic_template"  // or "custom_override"
}

Note: Gateway automatically discovers guardrails from synced contracts. Custom implementations take precedence over generic templates.

GET /health

Enhanced health check with contract sync status.

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-09T14:10:00.000Z",
  "extractors": ["pii_detector_v1", "hallucination_detector"],
  "cached_contracts": 2,
  "contract_loader": {
    "status": "success",
    "last_sync": "2025-11-09T14:06:09.722Z",
    "tenants": 3,
    "total_contracts": 7
  }
}

📋 Complete Endpoint Reference

Quick reference of all available endpoints organized by category.

Authentication

Method	Endpoint	Description
POST	`/api/auth/register`	Register new company
POST	`/api/auth/login`	Login with email/password
POST	`/api/auth/google`	Login with Google OAuth
GET	`/api/auth/verify`	Verify JWT token
POST	`/api/auth/logout`	Logout

Tenant Management

Method	Endpoint	Description
GET	`/api/tenants/me`	Get current tenant info
POST	`/api/tenants/rotate-key`	Rotate API key
POST	`/api/tenants/upgrade`	Upgrade plan
GET	`/api/tenants/usage`	Get usage statistics

Contracts

Method	Endpoint	Description
POST	`/api/dc/contracts`	Register new contract
GET	`/api/dc/contracts`	List contracts
GET	`/api/dc/contracts/:id`	Get contract details
POST	`/api/dc/contracts/:id/activate`	Activate contract
POST	`/api/dc/contracts/:id/revoke`	Revoke contract

Evidence

Method	Endpoint	Description
POST	`/api/dc/evidence`	Log evidence
GET	`/api/dc/evidence`	Query evidence
GET	`/api/dc/evidence/:trace_id`	Get evidence by trace ID
GET	`/api/dc/evidence/stats`	Get evidence statistics

Feature Extractors

Method	Endpoint	Description
GET	`/api/dc/extractors`	List all extractors
GET	`/api/dc/extractors/:id`	Get extractor details
GET	`/api/dc/extractors/health`	Get extractor health status

Policies

Method	Endpoint	Description
GET	`/api/policies`	List all policies
GET	`/api/policies/current`	Get active policy
POST	`/api/policies`	Create new policy
PUT	`/api/policies/:id`	Update policy
POST	`/api/policies/:id/activate`	Activate policy
GET	`/api/policies/templates`	Get policy templates

Gateway Proxy

Method	Endpoint	Description
POST	`/api/proxy`	Proxy AI request with contract enforcement

Complete API Reference

📚 Table of Contents

🔐 Authentication Overview

🔑 API Key Authentication (Recommended for Integrations)

🎫 JWT Session Authentication (Dashboard Only)

🔑 Authentication API

Request Body:

Response:

Request Body:

Request Body:

🏢 Tenant Management API

Headers:

Response:

Request Body:

Response:

🛠️ Guardrail Development Kit (GDK)

Register Custom Guardrail

Request Body

Example: Pattern-Based Guardrail

Example: LLM-Assisted Guardrail

Response

List Available Guardrails

Example Request

Response

Test Guardrail (Extract Features)

Request Body

Example Request

Response

List Guardrail Configs

Response

🧪 Interactive Testing

Guardrail Playground - Live Testing

Playground Features

📚 Pre-Built Templates

🔄 Development Workflow

Step 1: Design (Choose Type)

Step 2: Develop (Register via API or UI)

Step 3: Test (Playground or API)

Step 4: Deploy (Add to Contract)

Step 5: Monitor (Track Violations)

💡 Best Practices

📖 Additional Resources

📜 Contract Registry API

Request Body:

Response:

Query Parameters:

Request Body:

📸 Evidence Logging API

Request Body:

Query Parameters:

⚙️ Feature Extractors API

Response:

📋 Policy Management API

Request Body:

⚠️ Violation Tracking API

Query Parameters:

Response:

Response:

👥 Team Management API

Request Body:

Request Body:

🔐 Admin API

Headers:

Request Body:

Response:

🔧 Service Registration API

Headers:

Request Body:

Response:

Automatic Actions:

cURL Example:

Response:

✅ Evaluation & Simulation API

Response:

Request Body:

Response:

Automatic Actions:

Request Body:

🚪 GuardRails Runtime Gateway Proxy API

Headers: