FaultRay API Reference
Comprehensive REST API for infrastructure chaos engineering. Simulate failures, analyze risk, check compliance, and manage chaos experiments programmatically.
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.
Response Codes
| 200 | Success - request processed successfully |
| 201 | Created - resource created successfully |
| 400 | Bad Request - missing or invalid parameters |
| 401 | Unauthorized - missing or 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 - unexpected failure |
| 503 | Service 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
Return infrastructure topology as nodes and edges for visualization. Includes risk levels, SPOF detection, and utilization data.
Parameters
No parameters required.
Response Schema
Example
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}`);Simulate a component failure and return cascade effects with wave-by-wave breakdown, blast radius, and recovery time estimate.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| component_id | string | Required | ID of the component to fail |
Response Schema
Example
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
Calculate resilience impact of infrastructure modifications without applying them. Compare replicas, circuit breakers, failover, and autoscaling changes.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| modifications | object | Required | Map of component_id to modification object |
| modifications.*.replicas | integer | Optional | Number of replicas (min 1) |
| modifications.*.circuit_breaker | boolean | Optional | Enable/disable circuit breaker |
| modifications.*.failover | boolean | Optional | Enable/disable failover |
| modifications.*.autoscaling | boolean | Optional | Enable/disable autoscaling |
Example
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();Apply what-if modifications and export the resulting infrastructure as a downloadable YAML file.
Request Body
Same format as /api/whatif/calculate.
Example
curl -X POST http://localhost:8000/api/whatif/export \
-H "Content-Type: application/json" \
-d '{"modifications": {"database": {"replicas": 3}}}' \
-o modified-infra.yamlimport 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();Return resilience score history from past simulation runs for trend analysis.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Maximum entries to return (default: 30) |
Example
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 AI-powered architecture redesign recommendations to achieve target availability.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| target_nines | float | Optional | Target availability in nines (default: 4.0 = 99.99%) |
Example
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");Return risk heat map with per-component risk scores, zones, and hotspots across multiple dimensions.
Example
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();Analyse the financial impact of potential failures, attributing costs to individual components and teams.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| revenue_per_hour | float | Optional | Hourly revenue for cost calculation (default: 10000) |
Example
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");Benchmark your infrastructure resilience against anonymised industry peers. Use industry=list to see available industries, or industry=all to compare across all.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| industry | string | Required | Industry name (fintech, saas, healthcare, etc.) or "list" / "all" |
Example
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
Evaluate infrastructure compliance against a specific framework. Supported: soc2, pci-dss, hipaa, iso27001.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| framework | string | Required | Compliance framework identifier |
Example
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
List available historical cloud provider incidents for replay simulation.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| provider | string | Optional | Filter by cloud provider (aws, gcp, azure) |
Example
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");Replay a historical cloud provider incident against your current infrastructure to test resilience.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| incident_id | string | Required | ID of the incident to replay |
Example
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
List all marketplace chaos scenario packages with optional filtering by category or provider.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| category | string | Optional | Filter by category |
| provider | string | Optional | Filter by cloud provider |
Example
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");Get curated featured marketplace packages.
Example
curl http://localhost:8000/api/marketplace/featured
resp = requests.get("http://localhost:8000/api/marketplace/featured")const resp = await fetch("http://localhost:8000/api/marketplace/featured");Install a marketplace package, converting its scenarios to FaultRay format.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| package_id | string | Required | Package identifier |
Example
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
Return calendar view with scheduled experiments, history, blackout windows, and coverage stats.
Example
curl http://localhost:8000/api/calendar
resp = requests.get("http://localhost:8000/api/calendar")const resp = await fetch("http://localhost:8000/api/calendar");Schedule a new chaos experiment with target components, scenario IDs, and optional recurrence.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Experiment name |
| description | string | Optional | Experiment description |
| scenario_ids | array | Optional | Scenario IDs to run |
| target_components | array | Optional | Component IDs to target |
| scheduled_time | string | Optional | ISO-8601 datetime |
| recurrence | string | Optional | Recurrence pattern (daily, weekly, monthly) |
Example
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"})
});Download iCalendar (.ics) file for import into Google Calendar, Outlook, or other calendar applications.
Example
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
Return an SVG badge for embedding in READMEs, dashboards, or documentation. Types: resilience_score, sla_estimate, grade, spof_count, component_count.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Required | Badge type |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| style | string | Optional | Badge style: flat, flat-square, for-the-badge, plastic (default: flat) |
Example
curl http://localhost:8000/badge/resilience_score.svg?style=flat-square -o badge.svg
# Markdown embed: # 
// HTML embed: // <img src="http://localhost:8000/badge/resilience_score.svg" alt="Resilience">
Get pre-formatted Markdown snippets for embedding all available badges in README files.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| base_url | string | Optional | Base URL for badge links (default: http://localhost:8000) |
Example
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
Ask a natural language question about your infrastructure. The chat engine interprets intent and returns structured data alongside a human-readable response.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| question | string | Required | Natural language question |
Example
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
Upload two YAML infrastructure files and receive a structured diff with Mermaid diagram code. Uses multipart form upload.
Form Data
| Name | Type | Required | Description |
|---|---|---|---|
| before_file | file | Required | YAML file (before state) |
| after_file | file | Required | YAML file (after state) |
Example
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
Health check endpoint returning API status, version, uptime, and loaded component count.
Response Schema
Example
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();Discover available API versions, their lifecycle status, and changelogs.
Example
curl http://localhost:8000/api/versions
resp = requests.get("http://localhost:8000/api/versions")const resp = await fetch("http://localhost:8000/api/versions");