REST API

The ChaosPlane platform API is a Gin-based REST API that provides experiment CRUD, policy management, and real-time updates via WebSocket.

Base URL: http://chaosplane-api.chaosplane.svc.cluster.local:8080

Authentication

The API uses bearer token authentication. Pass your token in the Authorization header:

Authorization: Bearer <token>

Experiments

List experiments

GET /api/v1/experiments

Query parameters:

Parameter	Description
namespace	Filter by namespace
phase	Filter by phase
limit	Max results (default: 50)
offset	Pagination offset

Response:

{
  "items": [
    {
      "name": "pod-kill-test",
      "namespace": "production",
      "phase": "Completed",
      "target": { "kind": "Pod", "namespace": "production" },
      "action": { "type": "pod-kill" },
      "duration": "30s",
      "startTime": "2026-04-10T10:00:00Z",
      "endTime": "2026-04-10T10:01:30Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Get experiment

GET /api/v1/experiments/{namespace}/{name}

Response: Full experiment object including spec, status, conditions, and affected resources.

Create experiment

POST /api/v1/experiments

Body: ChaosExperiment manifest (JSON or YAML)

{
  "apiVersion": "chaos.chaosplane.io/v1alpha1",
  "kind": "ChaosExperiment",
  "metadata": {
    "name": "pod-kill-test",
    "namespace": "production"
  },
  "spec": {
    "target": {
      "kind": "Pod",
      "namespace": "production",
      "labelSelector": {
        "matchLabels": { "app": "my-app" }
      }
    },
    "action": {
      "type": "pod-kill",
      "parameters": { "gracePeriodSeconds": "0" }
    },
    "duration": "30s"
  }
}

Delete experiment

DELETE /api/v1/experiments/{namespace}/{name}

Abort experiment

POST /api/v1/experiments/{namespace}/{name}/abort

Pause experiment

POST /api/v1/experiments/{namespace}/{name}/pause

Resume experiment

POST /api/v1/experiments/{namespace}/{name}/resume

Workflows

List workflows

GET /api/v1/workflows

Query parameters: Same as experiments.

Get workflow

GET /api/v1/workflows/{namespace}/{name}

Create workflow

POST /api/v1/workflows

Delete workflow

DELETE /api/v1/workflows/{namespace}/{name}

Abort workflow

POST /api/v1/workflows/{namespace}/{name}/abort

Resume workflow (from suspend)

POST /api/v1/workflows/{namespace}/{name}/resume

Policies

List policies

GET /api/v1/policies

Get policy

GET /api/v1/policies/{name}

Create policy

POST /api/v1/policies

Update policy

PUT /api/v1/policies/{name}

Delete policy

DELETE /api/v1/policies/{name}

Events

List events

GET /api/v1/events

Query parameters:

Parameter	Description
namespace	Filter by namespace
resource	Filter by resource name
type	Filter by event type (Normal, Warning)

WebSocket

Real-time experiment and workflow status updates.

WS /api/v1/ws

Subscribe to experiment updates

{
  "type": "subscribe",
  "resource": "experiments",
  "namespace": "production"
}

Event message format

{
  "type": "update",
  "resource": "experiment",
  "name": "pod-kill-test",
  "namespace": "production",
  "phase": "Running",
  "timestamp": "2026-04-10T10:00:05Z"
}

Health

GET /healthz

Returns 200 OK when the API is healthy.

GET /readyz

Returns 200 OK when the API is ready to serve traffic (connected to Kubernetes).

Error responses

All errors return a JSON body:

{
  "error": "experiment not found",
  "code": 404
}

Code	Description
400	Bad request (invalid spec)
401	Unauthorized
403	Forbidden (policy violation)
404	Resource not found
409	Conflict (resource already exists)
500	Internal server error