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}
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
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)
← All API resources