API Reference

Verified FailSafe Endpoints

Tested endpoint contracts for frontend, backend, android, and utility flows. These are the exact routes used for integration and polling.

Base Configuration

BASE_URL = http://localhost:8000
HEADERS = {
  "Content-Type": "application/json"
}

Error Format

{
  "error": "string (error message)",
  "code": "string (error code)",
  "status": 400,
  "details": "string (optional)"
}

Status	Meaning	Example
200	Success	Experiment fetched
201	Created	Experiment started
202	Accepted	Metrics accepted
400	Bad Request	Invalid payload
401	Unauthorized	Missing API key
404	Not Found	Experiment ID invalid
500	Server Error	Backend error
503	Unavailable	Docker not running

Frontend Experiments

POST/experiments/frontend/start

Start Frontend Experiment

Starts a browser/frontend experiment and returns the experiment record.

{
  "fault_type": "latency",
  "targets": ["dhruvjain-portfolio"],
  "target_type": "frontend",
  "duration_seconds": 20,
  "frontend_run": {
    "base_url": "https://dhruvjain.xyz/",
    "metrics_endpoint": "http://localhost:8000/frontend/metrics",
    "target_urls": ["dhruvjain.xyz"]
  }
}

{
  "id": "exp-uuid-here",
  "state": "running",
  "phase": "baseline",
  "fault_type": "latency",
  "target_type": "frontend",
  "targets": ["dhruvjain-portfolio"],
  "duration_seconds": 20,
  "frontend_run": {
    "base_url": "https://dhruvjain.xyz/",
    "metrics_endpoint": "http://localhost:8000/frontend/metrics",
    "target_urls": ["dhruvjain.xyz"]
  },
  "created_at": "2026-04-06T12:00:00Z",
  "updated_at": "2026-04-06T12:00:00Z"
}

GET/experiments/frontend/status?id={experiment_id}

Get Frontend Experiment Status

Poll every 2 to 3 seconds until the experiment reaches completed or failed.

{
  "experiment": {
    "id": "exp-uuid-here",
    "state": "running",
    "phase": "injecting",
    "fault_type": "latency",
    "target_type": "frontend",
    "duration_seconds": 20,
    "current_intensity": 45,
    "created_at": "2026-04-06T12:00:00Z",
    "updated_at": "2026-04-06T12:00:05Z"
  }
}

POST/frontend/metrics

Ingest Frontend Metrics

Browser collectors post phase-tagged metric batches here.

{
  "metrics": [
    {
      "experiment_id": "exp-uuid-here",
      "phase": "baseline",
      "page": "/",
      "metrics": {
        "lcp": 1200,
        "cls": 0.04,
        "inp": 85,
        "long_tasks": 0,
        "errors": 0,
        "unhandled_rejections": 0
      },
      "api_calls": [
        {
          "url": "https://dhruvjain.xyz/",
          "duration": 280,
          "status": 200
        }
      ],
      "timestamp": 1712400000000
    }
  ]
}

{
  "status": "accepted",
  "message": "Metrics ingested successfully",
  "count": 3
}

GET/experiments/frontend/metrics?id={experiment_id}

Get Frontend Metrics Report

Returns phase-comparison metrics, vitals, stability, API quality, and score summaries.

{
  "experiment_id": "exp-uuid-here",
  "state": "completed",
  "phase": "completed",
  "total_metrics": 3,
  "phases": {
    "baseline": { "avg_lcp": 1200, "avg_cls": 0.04, "avg_inp": 85, "avg_errors": 0, "avg_long_tasks": 0 },
    "injecting": { "avg_lcp": 1650, "avg_cls": 0.08, "avg_inp": 120, "avg_errors": 1, "avg_long_tasks": 2 },
    "recovery": { "avg_lcp": 1300, "avg_cls": 0.05, "avg_inp": 95, "avg_errors": 0, "avg_long_tasks": 0 }
  },
  "vitals": {
    "lcp": { "baseline": 1200, "injecting": 1650, "recovery": 1300 },
    "cls": { "baseline": 0.04, "injecting": 0.08, "recovery": 0.05 },
    "inp": { "baseline": 85, "injecting": 120, "recovery": 95 }
  },
  "stability": {
    "long_tasks": { "baseline": 0, "injecting": 2, "recovery": 0 },
    "errors": { "baseline": 0, "injecting": 1, "recovery": 0 },
    "unhandled_rejections": { "baseline": 0, "injecting": 0, "recovery": 0 }
  },
  "api_quality": {
    "success_rate": 0.95,
    "avg_latency": 596.67,
    "error_count": 1
  },
  "failsafe_index": {
    "score": 78,
    "status": "degraded",
    "summary": "Performance degradation detected during fault injection"
  },
  "frontend_score": {
    "status": "degraded",
    "score": 78
  }
}

POST/experiments/frontend/stop?id={experiment_id}

Stop Frontend Experiment

Stops the running frontend experiment and marks it completed.

{
  "id": "exp-uuid-here",
  "state": "completed",
  "message": "Experiment stopped successfully"
}

Backend Experiments

POST/experiments/backend/start

Start Backend Experiment

Starts a Docker-targeted backend experiment. Both camelCase and snake_case payloads are seen in the tested collection.

{
  "faultType": "network_delay",
  "targets": ["svc-c"],
  "targetType": "docker",
  "observationType": "http",
  "observedEndpoints": ["http://svc-a", "http://svc-b", "http://svc-c"],
  "duration": 60,
  "adaptive": true,
  "stepIntensity": 20,
  "maxIntensity": 100,
  "dependencyGraph": {
    "http://svc-a": ["http://svc-b"],
    "http://svc-b": ["http://svc-c"],
    "http://svc-c": []
  },
  "targetEndpointMap": {
    "svc-a": ["http://svc-a"],
    "svc-b": ["http://svc-b"],
    "svc-c": ["http://svc-c"]
  }
}

{
  "fault_type": "kill",
  "targets": ["svc-c"],
  "target_type": "docker",
  "observation_type": "http",
  "observed_endpoints": ["http://svc-a", "http://svc-b", "http://svc-c"],
  "duration_seconds": 75,
  "scenarios": [
    { "type": "kill", "at": 8, "duration_seconds": 1 },
    { "type": "cpu_stress", "at": 20, "duration_seconds": 25 },
    { "type": "memory_stress", "at": 50, "duration_seconds": 15 }
  ],
  "expected": { "running": true }
}

{
  "id": "exp-backend-uuid",
  "state": "running",
  "phase": "baseline",
  "fault_type": "network_delay",
  "target_type": "docker",
  "targets": ["svc-c"],
  "duration_seconds": 60,
  "current_intensity": 0,
  "created_at": "2026-04-06T12:00:00Z"
}

GET/experiments/backend/status?id={experiment_id}

Get Backend Status

{
  "experiment": {
    "id": "exp-backend-uuid",
    "state": "running",
    "phase": "injecting",
    "fault_type": "network_delay",
    "current_intensity": 45,
    "max_stable_intensity": 40,
    "breaking_intensity": 85
  }
}

GET/experiments/backend/metrics?id={experiment_id}

Get Backend Metrics

{
  "experiment_id": "exp-backend-uuid",
  "state": "completed",
  "baseline_metrics": {
    "avg_latency": 45.5,
    "p95": 120,
    "error_rate": 0.001
  },
  "max_impact_metrics": {
    "avg_latency": 850.3,
    "p95": 2100,
    "error_rate": 0.25
  },
  "recovery_metrics": {
    "avg_latency": 52.1,
    "p95": 140,
    "error_rate": 0.002
  },
  "insights": {
    "degradation_factor": 18.7,
    "recovery_time_seconds": 3,
    "critical_endpoints": ["http://svc-c"]
  }
}

POST/experiments/backend/stop?id={experiment_id}

Stop Backend Experiment

Stops the backend experiment.

Android Experiments

POST/upload/apk

Upload APK

Upload an APK using multipart form data. Either file or apk is accepted in the tested flow.

{
  "id": "apk-uuid-here",
  "apk": "apk-uuid-here",
  "path": "D:\FailSafe\uploads\apks\apk-uuid-here.apk",
  "package": "com.example.code",
  "activity": "com.example.code.MainActivity"
}

POST/experiments/android/start

Start Android Experiment

{
  "fault_type": "kill_app",
  "targets": ["com.example.code"],
  "target_type": "android",
  "observation_type": "android",
  "duration_seconds": 70,
  "apk": "apk-uuid-here",
  "android_run": {
    "avd_name": "Pixel_8a",
    "headless": true,
    "reset_app_state": true
  },
  "scenarios": [
    { "type": "kill_app", "at": 20, "duration_seconds": 1 },
    { "type": "foreground_app", "at": 30, "duration_seconds": 2 }
  ],
  "expected": {
    "running": true,
    "not_crash": true,
    "not_anr": true,
    "should_recover": true
  }
}

{
  "fault_type": "network_disable",
  "targets": ["com.example.code"],
  "target_type": "android",
  "observation_type": "android",
  "duration_seconds": 85,
  "apk": "apk-uuid-here",
  "android_run": {
    "avd_name": "Pixel_8a",
    "headless": true
  },
  "scenarios": [
    { "type": "network_disable", "at": 8, "duration_seconds": 7 },
    { "type": "network_enable", "at": 18, "duration_seconds": 1 },
    { "type": "network_flaky", "at": 28, "duration_seconds": 10 },
    { "type": "network_latency", "at": 44, "duration_seconds": 8 }
  ],
  "expected": {
    "running": true,
    "not_crash": true,
    "not_anr": true,
    "should_recover": true
  }
}

{
  "id": "exp-android-uuid",
  "state": "running",
  "phase": "baseline",
  "fault_type": "kill_app",
  "package": "com.example.code"
}

GET/experiments/android/status?id={experiment_id}

Get Android Status

Returns the running, completed, or failed state for the Android experiment.

GET/experiments/android/metrics?id={experiment_id}

Get Android Metrics

Returns the Android metrics report for a completed experiment.

POST/experiments/android/stop?id={experiment_id}

Stop Android Experiment

Stops the Android experiment and begins recovery handling.

Utility Endpoints

GET/health

Health Check

OK

Postman Variables

Reference Variables

Frontend Collection

{{experiment_id}}
{{base_url}}
{{metrics_endpoint}}

Docker Collection

{{baseUrl}}
{{experimentId}}

Android Collection

{{baseUrl}}
{{apkId}}
{{experimentId}}