FaultRay API Reference

Comprehensive REST API for infrastructure chaos engineering. Simulate failures, analyze risk, check compliance, and manage chaos experiments programmatically.

Base URL http://localhost:8000

Authentication

API Key Authentication

Authenticate requests by including your API key in the Authorization header as a Bearer token.

Authorization: Bearer fr_live_abc123def456...

API keys can be generated via OAuth login or the settings page. When authentication is not configured, all endpoints are accessible without a key.

Permissions

Endpoints require specific permissions: view_results for read operations, run_simulation for write operations, and create_project for project management.

Rate Limiting

Sliding Window Rate Limits

All /api/* endpoints are rate-limited using a sliding window algorithm. Rate limits are applied per client IP address or API key.

When rate-limited, the API returns a 429 Too Many Requests response.

Free
30 req/min
Basic
120 req/min
Pro
600 req/min
Enterprise
3,000 req/min

Response Codes

200Success - request processed successfully
201Created - resource created successfully
400Bad Request - missing or invalid parameters
401Unauthorized - missing or invalid API key
403Forbidden - insufficient permissions
404Not Found - resource does not exist
429Too Many Requests - rate limit exceeded
500Internal Server Error - unexpected failure
503Service Unavailable - database not available

Error Response Format

{
  "error": {
    "code": 429,
    "message": "Too many requests. Please try again later."
  }
}

API Versioning

Version Prefixes

The API supports versioned prefixes. All endpoints are available at both the unversioned path and under /api/v1/. New endpoints are also available under /api/v2/ (beta).

# Unversioned (always points to latest stable)
GET /api/topology

# Explicit version
GET /api/v1/topology
GET /api/v2/dashboard/summary

Use GET /api/versions to discover available API versions and their status.

Infrastructure

GET /api/topology Get infrastructure topology

Return infrastructure topology as nodes and edges for visualization. Includes risk levels, SPOF detection, and utilization data.

Parameters

No parameters required.

Response Schema

{ "nodes": [ { "id": "web-server", "name": "Web Server", "type": "server", "replicas": 3, "utilization": 42.5, "health": "healthy", "is_spof": false, "risk_level": "low" } ], "edges": [ { "source": "web-server", "target": "database", "dependency_type": "hard", "weight": 0.9, "critical": true } ], "metadata": { "total_components": 12, "total_edges": 18, "resilience_score": 72.5 } }

Example

curl Python JavaScript
curl -X GET http://localhost:8000/api/topology \
  -H "Authorization: Bearer YOUR_API_KEY"
import requests

resp = requests.get(
    "http://localhost:8000/api/topology",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = resp.json()
print(f"Components: {data['metadata']['total_components']}")
const resp = await fetch("http://localhost:8000/api/topology", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();
console.log(`Components: ${data.metadata.total_components}`);
POST /api/simulate-failure/{component_id} Simulate component failure

Simulate a component failure and return cascade effects with wave-by-wave breakdown, blast radius, and recovery time estimate.

Path Parameters

NameTypeRequiredDescription
component_idstringRequiredID of the component to fail

Response Schema

{ "root_cause": "database", "total_affected": 5, "risk_score": 7.2, "waves": [ {"wave": 0, "components": [{"id": "database", "health": "down", "reason": "..."}]}, {"wave": 1, "components": [...]} ], "blast_radius_score": 0.42, "recovery_time_estimate": "15-30 minutes" }

Example

curl Python JavaScript
curl -X POST http://localhost:8000/api/simulate-failure/database \
  -H "Authorization: Bearer YOUR_API_KEY"
import requests

resp = requests.post(
    "http://localhost:8000/api/simulate-failure/database",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
result = resp.json()
print(f"Blast radius: {result['blast_radius_score']}")
const resp = await fetch("http://localhost:8000/api/simulate-failure/database", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const result = await resp.json();
console.log(`Blast radius: ${result.blast_radius_score}`);

Simulation

POST /api/whatif/calculate What-if resilience calculation

Calculate resilience impact of infrastructure modifications without applying them. Compare replicas, circuit breakers, failover, and autoscaling changes.

Request Body

NameTypeRequiredDescription
modificationsobjectRequiredMap of component_id to modification object
modifications.*.replicasintegerOptionalNumber of replicas (min 1)
modifications.*.circuit_breakerbooleanOptionalEnable/disable circuit breaker
modifications.*.failoverbooleanOptionalEnable/disable failover
modifications.*.autoscalingbooleanOptionalEnable/disable autoscaling

Example

curl Python JavaScript
curl -X POST http://localhost:8000/api/whatif/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "modifications": {
      "database": {"replicas": 3, "failover": true},
      "cache": {"circuit_breaker": true}
    }
  }'
import requests

resp = requests.post(
    "http://localhost:8000/api/whatif/calculate",
    json={"modifications": {
        "database": {"replicas": 3, "failover": True},
        "cache": {"circuit_breaker": True}
    }}
)
result = resp.json()
print(f"Score delta: {result['delta']:+.1f}")
const resp = await fetch("http://localhost:8000/api/whatif/calculate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    modifications: {
      database: { replicas: 3, failover: true },
      cache: { circuit_breaker: true }
    }
  })
});
const result = await resp.json();
POST /api/whatif/export Export modified infrastructure YAML

Apply what-if modifications and export the resulting infrastructure as a downloadable YAML file.

Request Body

Same format as /api/whatif/calculate.

Example

curl Python JavaScript
curl -X POST http://localhost:8000/api/whatif/export \
  -H "Content-Type: application/json" \
  -d '{"modifications": {"database": {"replicas": 3}}}' \
  -o modified-infra.yaml
import requests

resp = requests.post(
    "http://localhost:8000/api/whatif/export",
    json={"modifications": {"database": {"replicas": 3}}}
)
with open("modified-infra.yaml", "wb") as f:
    f.write(resp.content)
const resp = await fetch("http://localhost:8000/api/whatif/export", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({modifications: {database: {replicas: 3}}})
});
const yaml = await resp.text();
GET /api/score-history Resilience score history

Return resilience score history from past simulation runs for trend analysis.

Query Parameters

NameTypeRequiredDescription
limitintegerOptionalMaximum entries to return (default: 30)

Example

curl Python JavaScript
curl http://localhost:8000/api/score-history?limit=10
resp = requests.get("http://localhost:8000/api/score-history", params={"limit": 10})
history = resp.json()["history"]
const resp = await fetch("http://localhost:8000/api/score-history?limit=10");
const { history } = await resp.json();

Analysis

GET /api/architecture-advice AI architecture recommendations

Get AI-powered architecture redesign recommendations to achieve target availability.

Query Parameters

NameTypeRequiredDescription
target_ninesfloatOptionalTarget availability in nines (default: 4.0 = 99.99%)

Example

curlPythonJavaScript
curl http://localhost:8000/api/architecture-advice?target_nines=3.5
resp = requests.get("http://localhost:8000/api/architecture-advice", params={"target_nines": 3.5})
const resp = await fetch("http://localhost:8000/api/architecture-advice?target_nines=3.5");
GET /api/risk-heatmap Risk heat map data

Return risk heat map with per-component risk scores, zones, and hotspots across multiple dimensions.

Example

curlPythonJavaScript
curl http://localhost:8000/api/risk-heatmap
resp = requests.get("http://localhost:8000/api/risk-heatmap")
heatmap = resp.json()
const resp = await fetch("http://localhost:8000/api/risk-heatmap");
const heatmap = await resp.json();
GET /api/cost-attribution Failure cost attribution

Analyse the financial impact of potential failures, attributing costs to individual components and teams.

Query Parameters

NameTypeRequiredDescription
revenue_per_hourfloatOptionalHourly revenue for cost calculation (default: 10000)

Example

curlPythonJavaScript
curl "http://localhost:8000/api/cost-attribution?revenue_per_hour=25000"
resp = requests.get("http://localhost:8000/api/cost-attribution", params={"revenue_per_hour": 25000})
const resp = await fetch("http://localhost:8000/api/cost-attribution?revenue_per_hour=25000");
GET /api/benchmark/{industry} Industry benchmark comparison

Benchmark your infrastructure resilience against anonymised industry peers. Use industry=list to see available industries, or industry=all to compare across all.

Path Parameters

NameTypeRequiredDescription
industrystringRequiredIndustry name (fintech, saas, healthcare, etc.) or "list" / "all"

Example

curlPythonJavaScript
curl http://localhost:8000/api/benchmark/fintech
resp = requests.get("http://localhost:8000/api/benchmark/fintech")
const resp = await fetch("http://localhost:8000/api/benchmark/fintech");

Compliance

GET /api/compliance/{framework} Compliance check by framework

Evaluate infrastructure compliance against a specific framework. Supported: soc2, pci-dss, hipaa, iso27001.

Path Parameters

NameTypeRequiredDescription
frameworkstringRequiredCompliance framework identifier

Example

curlPythonJavaScript
curl http://localhost:8000/api/compliance/soc2
resp = requests.get("http://localhost:8000/api/compliance/soc2")
const resp = await fetch("http://localhost:8000/api/compliance/soc2");

Incidents

GET /api/incidents List historical incidents

List available historical cloud provider incidents for replay simulation.

Query Parameters

NameTypeRequiredDescription
providerstringOptionalFilter by cloud provider (aws, gcp, azure)

Example

curlPythonJavaScript
curl http://localhost:8000/api/incidents?provider=aws
resp = requests.get("http://localhost:8000/api/incidents", params={"provider": "aws"})
const resp = await fetch("http://localhost:8000/api/incidents?provider=aws");
POST /api/replay/{incident_id} Replay historical incident

Replay a historical cloud provider incident against your current infrastructure to test resilience.

Path Parameters

NameTypeRequiredDescription
incident_idstringRequiredID of the incident to replay

Example

curlPythonJavaScript
curl -X POST http://localhost:8000/api/replay/aws-us-east-1-2017
resp = requests.post("http://localhost:8000/api/replay/aws-us-east-1-2017")
const resp = await fetch("http://localhost:8000/api/replay/aws-us-east-1-2017", {method: "POST"});

Marketplace

GET /api/marketplace/packages List scenario packages

List all marketplace chaos scenario packages with optional filtering by category or provider.

Query Parameters

NameTypeRequiredDescription
categorystringOptionalFilter by category
providerstringOptionalFilter by cloud provider

Example

curlPythonJavaScript
curl http://localhost:8000/api/marketplace/packages?category=database
resp = requests.get("http://localhost:8000/api/marketplace/packages")
const resp = await fetch("http://localhost:8000/api/marketplace/packages");
POST /api/marketplace/install/{package_id} Install scenario package

Install a marketplace package, converting its scenarios to FaultRay format.

Path Parameters

NameTypeRequiredDescription
package_idstringRequiredPackage identifier

Example

curlPythonJavaScript
curl -X POST http://localhost:8000/api/marketplace/install/aws-rds-failures
resp = requests.post("http://localhost:8000/api/marketplace/install/aws-rds-failures")
const resp = await fetch("http://localhost:8000/api/marketplace/install/aws-rds-failures", {method: "POST"});

Calendar

GET /api/calendar Chaos calendar view

Return calendar view with scheduled experiments, history, blackout windows, and coverage stats.

Example

curlPythonJavaScript
curl http://localhost:8000/api/calendar
resp = requests.get("http://localhost:8000/api/calendar")
const resp = await fetch("http://localhost:8000/api/calendar");
POST /api/calendar/schedule Schedule chaos experiment

Schedule a new chaos experiment with target components, scenario IDs, and optional recurrence.

Request Body

NameTypeRequiredDescription
namestringRequiredExperiment name
descriptionstringOptionalExperiment description
scenario_idsarrayOptionalScenario IDs to run
target_componentsarrayOptionalComponent IDs to target
scheduled_timestringOptionalISO-8601 datetime
recurrencestringOptionalRecurrence pattern (daily, weekly, monthly)

Example

curlPythonJavaScript
curl -X POST http://localhost:8000/api/calendar/schedule \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly DB Failover", "target_components": ["database"], "recurrence": "weekly"}'
resp = requests.post("http://localhost:8000/api/calendar/schedule", json={
    "name": "Weekly DB Failover",
    "target_components": ["database"],
    "recurrence": "weekly"
})
const resp = await fetch("http://localhost:8000/api/calendar/schedule", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({name: "Weekly DB Failover", target_components: ["database"], recurrence: "weekly"})
});
GET /api/calendar/ical Download iCal file

Download iCalendar (.ics) file for import into Google Calendar, Outlook, or other calendar applications.

Example

curlPythonJavaScript
curl http://localhost:8000/api/calendar/ical -o chaos-calendar.ics
resp = requests.get("http://localhost:8000/api/calendar/ical")
with open("chaos-calendar.ics", "wb") as f:
    f.write(resp.content)
const resp = await fetch("http://localhost:8000/api/calendar/ical");
const blob = await resp.blob();

Badges

GET /badge/{type}.svg Get SVG badge

Return an SVG badge for embedding in READMEs, dashboards, or documentation. Types: resilience_score, sla_estimate, grade, spof_count, component_count.

Path Parameters

NameTypeRequiredDescription
typestringRequiredBadge type

Query Parameters

NameTypeRequiredDescription
stylestringOptionalBadge style: flat, flat-square, for-the-badge, plastic (default: flat)

Example

curlPythonJavaScript
curl http://localhost:8000/badge/resilience_score.svg?style=flat-square -o badge.svg
# Markdown embed:
# ![Resilience](http://localhost:8000/badge/resilience_score.svg)
// HTML embed:
// <img src="http://localhost:8000/badge/resilience_score.svg" alt="Resilience">
GET /api/badge-markdown Badge markdown snippets

Get pre-formatted Markdown snippets for embedding all available badges in README files.

Query Parameters

NameTypeRequiredDescription
base_urlstringOptionalBase URL for badge links (default: http://localhost:8000)

Example

curlPythonJavaScript
curl "http://localhost:8000/api/badge-markdown?base_url=https://faultray.example.com"
resp = requests.get("http://localhost:8000/api/badge-markdown")
const resp = await fetch("http://localhost:8000/api/badge-markdown");

Chat

POST /api/chat Infrastructure chat query

Ask a natural language question about your infrastructure. The chat engine interprets intent and returns structured data alongside a human-readable response.

Request Body

NameTypeRequiredDescription
questionstringRequiredNatural language question

Example

curlPythonJavaScript
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the single points of failure?"}'
resp = requests.post("http://localhost:8000/api/chat", json={
    "question": "What are the single points of failure?"
})
const resp = await fetch("http://localhost:8000/api/chat", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({question: "What are the single points of failure?"})
});

Export

POST /api/topology-diff Compare topology files

Upload two YAML infrastructure files and receive a structured diff with Mermaid diagram code. Uses multipart form upload.

Form Data

NameTypeRequiredDescription
before_filefileRequiredYAML file (before state)
after_filefileRequiredYAML file (after state)

Example

curlPythonJavaScript
curl -X POST http://localhost:8000/api/topology-diff \
  -F "before_file=@before.yaml" \
  -F "after_file=@after.yaml"
resp = requests.post("http://localhost:8000/api/topology-diff", files={
    "before_file": open("before.yaml", "rb"),
    "after_file": open("after.yaml", "rb")
})
const form = new FormData();
form.append("before_file", beforeBlob, "before.yaml");
form.append("after_file", afterBlob, "after.yaml");
const resp = await fetch("http://localhost:8000/api/topology-diff", {method: "POST", body: form});

System

GET /api/health API health check

Health check endpoint returning API status, version, uptime, and loaded component count.

Response Schema

{ "status": "healthy", "version": "2.1.0", "uptime": "2h 15m 30s", "uptime_seconds": 8130.0, "components_loaded": 12, "api_versions": [...], "rate_limit_tiers": {"free": 30, "basic": 120, ...}, "timestamp": "2026-03-15T10:30:00+00:00" }

Example

curlPythonJavaScript
curl http://localhost:8000/api/health
resp = requests.get("http://localhost:8000/api/health")
print(resp.json()["status"])  # "healthy"
const resp = await fetch("http://localhost:8000/api/health");
const { status } = await resp.json();
GET /api/versions List API versions

Discover available API versions, their lifecycle status, and changelogs.

Example

curlPythonJavaScript
curl http://localhost:8000/api/versions
resp = requests.get("http://localhost:8000/api/versions")
const resp = await fetch("http://localhost:8000/api/versions");

Quick Start

# 1. Load demo infrastructure
curl http://localhost:8000/demo

# 2. Get topology
curl http://localhost:8000/api/topology

# 3. Simulate a failure
curl -X POST \
  http://localhost:8000/api/simulate-failure/database

# 4. Check resilience score
curl http://localhost:8000/api/health

Python SDK

import requests

BASE = "http://localhost:8000"

# Load demo
requests.get(f"{BASE}/demo")

# Get topology
topo = requests.get(
    f"{BASE}/api/topology"
).json()

# Run what-if analysis
result = requests.post(
    f"{BASE}/api/whatif/calculate",
    json={"modifications": {
        "database": {
            "replicas": 3,
            "failover": True
        }
    }}
).json()

print(f"Score: {result['resilience_score']}")
print(f"Delta: {result['delta']:+.1f}")

Response Format

All API responses are JSON. Errors follow a consistent format:

{
  "error": {
    "code": 400,
    "message": "Description"
  }
}