breakers API
Sign in with GitHub

breakers

Configure circuit breakers for a project. Breakers evaluate metric rules and trigger actions as they trip and recover.

GET /v1/projects/:project_id/breakers

List all breakers for a project

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID

Responses

200 List of breakers
breakers
- Array of breaker objects (each includes router_id)
count
- Number of breakers
hash
- Content hash for change detection
updated_at
- Last modification timestamp
Headers: ETag: Weak ETag for conditional requests
304 Not modified (ETag match)

Example

Request 
curl https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers \
  -H "Authorization: Bearer YOUR_USER_API_KEY"
Response 
{
  "breakers": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "API Latency",
      "metric": "api.latency_ms",
      "kind": "p95",
      "op": "gt",
      "threshold": 500,
      "window_ms": 60000,
      "min_state_duration_ms": 60000,
      "cooldown_ms": 300000,
      "router_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "hash": "abc123",
  "updated_at": "2024-01-15T10:30:00",
  "count": 1
}
GET /v1/projects/:project_id/breakers/:breaker_id

Get a single breaker

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID
breaker_id path uuid Yes Breaker ID

Responses

200 Breaker details
breaker
- Breaker object
router_id
- UUID of linked router
404 Breaker not found

Example

Request 
curl https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers/BREAKER_ID \
  -H "Authorization: Bearer YOUR_USER_API_KEY"
Response 
{
  "breaker": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "API Latency",
    "metric": "api.latency_ms",
    "kind": "p95",
    "op": "gt",
    "threshold": 500,
    "window_ms": 60000,
    "min_state_duration_ms": 60000,
    "cooldown_ms": 0
  },
  "router_id": "550e8400-e29b-41d4-a716-446655440000"
}
POST /v1/projects/:project_id/breakers

Create a single breaker

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID

Request Body

kind *
string Breaker kind: error_rate, avg, p95, count, max, min, sum, stddev, percentile, consecutive_failures, delta
metric *
string Metric to monitor
op *
string Comparison operator: gt, lt, gte, lte
threshold *
number Threshold value to compare against
actions
object Actions to execute on state changes
cooldown_ms
integer Minimum time in open before entering half_open
eval_interval_ms
integer Custom evaluation interval. For stable behavior, ensure window_ms >= 3× eval_interval_ms.
half_open_backoff_cap_ms
integer Maximum backoff cap in milliseconds
half_open_backoff_enabled
boolean Whether exponential backoff is enabled (default true)
half_open_confirmation_ms
integer Duration of half-open confirmation window (default 90s)
half_open_indeterminate_policy
string Policy when data is indeterminate (count < min_count) in half-open: optimistic, conservative (default), or pessimistic
id
uuid Breaker UUID (server-generated if not provided)
kind_params
object Kind-specific configuration. For delta: {delta_of, alpha}. For percentile: {percentile}
metadata
object User-defined key/value pairs (string keys and values; max 20 keys; key max 64 chars; value max 255 chars). Tripswitch stores and returns metadata but does not interpret it.
min_count
integer Minimum samples required for evaluation
min_state_duration_ms
integer Minimum time in current state before transition
name
string Human-readable name
window_ms
integer Evaluation window in milliseconds. Recommended >= 3× eval_interval_ms for stable behavior. Not used by consecutive_failures.

Responses

201 Breaker created
breaker
- Created breaker object
router_id
- UUID of linked router
409 Breaker with this ID already exists
422 Validation failed

Example

Request 
curl -X POST https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers \
  -H "Authorization: Bearer YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Latency",
    "metric": "api.latency_ms",
    "kind": "p95",
    "op": "gt",
    "threshold": 500,
    "window_ms": 60000
  }'
Response 
{
  "breaker": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "API Latency",
    "metric": "api.latency_ms",
    "kind": "p95",
    "op": "gt",
    "threshold": 500,
    "window_ms": 60000,
    "min_state_duration_ms": 60000,
    "cooldown_ms": 0
  },
  "router_id": "550e8400-e29b-41d4-a716-446655440000"
}
PATCH /v1/projects/:project_id/breakers/:breaker_id

Update a breaker

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID
breaker_id path uuid Yes Breaker ID

Request Body

actions
object
cooldown_ms
integer
eval_interval_ms
integer
half_open_backoff_cap_ms
integer
half_open_backoff_enabled
boolean
half_open_confirmation_ms
integer
half_open_indeterminate_policy
string
kind
string
kind_params
object
metadata
object User-defined key/value pairs (string keys and values; max 20 keys; key max 64 chars; value max 255 chars). Tripswitch stores and returns metadata but does not interpret it.
metric
string
min_count
integer
min_state_duration_ms
integer
name
string
op
string
threshold
number
window_ms
integer

Responses

200 Breaker updated
breaker
- Updated breaker object
404 Breaker not found
422 Validation failed

Example

Request 
curl -X PATCH https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers/BREAKER_ID \
  -H "Authorization: Bearer YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 750}'
Response 
{
  "breaker": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "API Latency",
    "metric": "api.latency_ms",
    "kind": "p95",
    "op": "gt",
    "threshold": 750,
    "window_ms": 60000
  }
}
PUT /v1/projects/:project_id/breakers

Replace all breakers (bulk sync)

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID

Request Body

breakers *
array Array of breaker objects to set

Responses

200 Breakers replaced
changed
- Whether the set changed
count
- Number of breakers
duration_ms
- Operation duration
hash
- New content hash
409 Guardrail blocked destructive change
412 Precondition failed (If-Match header mismatch)
422 Validation failed

Example

Request 
curl -X PUT https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers \
  -H "Authorization: Bearer YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "breakers": [
      {"name": "API Latency", "metric": "api.latency_ms", "kind": "p95", "op": "gt", "threshold": 500}
    ]
  }'
Response 
{
  "changed": true,
  "count": 1,
  "hash": "abc123",
  "duration_ms": 45
}
DELETE /v1/projects/:project_id/breakers/:breaker_id

Delete a breaker

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID
breaker_id path uuid Yes Breaker ID

Responses

204 Breaker deleted
404 Breaker not found

Example

Request 
curl -X DELETE https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers/BREAKER_ID \
  -H "Authorization: Bearer YOUR_USER_API_KEY"
Response 
(empty body, 204 No Content)
POST /v1/projects/:project_id/breakers/state:batch

Get current state of multiple breakers

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID

Request Body

breaker_ids
array Array of breaker UUIDs to look up
router_ids
array Array of router UUIDs (resolves to linked breakers)

Responses

200 Batch state lookup
states
- Array of breaker state objects
422 Validation failed (must provide breaker_ids or router_ids)

Example

Response 
{
  "states": [
    {
      "breaker_id": "660e8400-e29b-41d4-a716-446655440001",
      "state": "closed",
      "evaluated_at_ms": 1705312300000,
      "sample_count": 42,
      "min_count": 10,
      "window_ms": 60000,
      "observed": true,
      "threshold": 0.05,
      "reason_code": null
    },
    {
      "breaker_id": "660e8400-e29b-41d4-a716-446655440002",
      "state": "open",
      "evaluated_at_ms": 1705312300000,
      "sample_count": 15,
      "min_count": 10,
      "window_ms": 60000,
      "observed": true,
      "threshold": 0.05,
      "reason_code": "threshold_exceeded"
    }
  ]
}
GET /v1/projects/:project_id/breakers/:breaker_id/state

Get current state of a single breaker

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID
breaker_id path uuid Yes Breaker ID

Responses

200 Breaker state lookup
breaker_id
- Breaker UUID
indeterminate
- boolean indicating insufficient data
indeterminate_reason
- Reason for indeterminate (insufficient_samples or null)
last_eval_ms
- Timestamp of last evaluation
name
- Breaker name
next_eval_ms
- Timestamp of next scheduled evaluation
state
- Current state (closed, open, half_open)
state_since_ms
- Timestamp when breaker entered current state
404 Breaker not found

Example

Request 
curl https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers/BREAKER_ID/state \
  -H "Authorization: Bearer YOUR_USER_API_KEY"
GET /v1/projects/:project_id/breakers/state:stream

SSE stream of breaker state changes (SDK endpoint)

Auth: User API key

Parameters

Name In Type Required Description
project_id path uuid Yes Project ID

Responses

200 Server-Sent Events stream
Headers: Cache-Control: no-cache Connection: keep-alive Content-Type: text/event-stream

Example

Request 
curl -N https://api.tripswitch.dev/v1/projects/PROJECT_ID/breakers/state:stream \
  -H "Authorization: Bearer YOUR_USER_API_KEY"
Response 
event: state
data: {"breaker": "checkout", "state": "closed", "allow_rate": null}

event: state
data: {"breaker": "payment", "state": "open", "allow_rate": null}

: heartbeat

event: state
data: {"breaker": "checkout", "state": "open", "allow_rate": null}
← All API resources