HTTP API

Circuit Breaker

GET/api/v1/circuits

List all circuits

GET
/api/v1/circuits

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Query Parameters

state?string

Filter by state (closed, open, half_open)

tags?string

Filter by tags (comma-separated)

Response Body

application/json

curl -X GET "https://example.com/api/v1/circuits"
{  "circuits": [    {      "circuit_name": "string",      "description": "string",      "failure_count": 0,      "last_state_change": "2019-08-24T14:15:22Z",      "state": "closed",      "tags": [        "string"      ],      "time_until_recovery": 0    }  ],  "total_count": 0}
GET/api/v1/circuits/{circuit_name}

Retrieve circuit configuration and state metadata

GET
/api/v1/circuits/{circuit_name}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Response Body

application/json

curl -X GET "https://example.com/api/v1/circuits/string"
{  "config": {    "failure_threshold": 0,    "failure_window_seconds": 0,    "half_open_max_requests": 0,    "recovery_timeout_seconds": 0  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "history": [    {      "at": "2019-08-24T14:15:22Z",      "from": "closed",      "reason": "string",      "to": "closed"    }  ],  "metadata": {    "property1": "string",    "property2": "string"  },  "name": "string",  "state": {    "current": "closed",    "failure_count": 0,    "half_open_requests": 0,    "last_failure_ms": 0,    "last_failure_time": "2019-08-24T14:15:22Z",    "last_state_change": "2019-08-24T14:15:22Z",    "last_state_change_ms": 0  },  "stats": {    "failure_rate": 0.1,    "total_failures": 0,    "total_requests": 0,    "total_successes": 0  },  "tags": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}
POST/api/v1/circuits/{circuit_name}

Create or update a circuit breaker

POST
/api/v1/circuits/{circuit_name}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create or update a circuit

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/circuits/string" \  -H "Content-Type: application/json" \  -d '{    "config": {      "failure_threshold": 0,      "failure_window_seconds": 0,      "half_open_max_requests": 0,      "recovery_timeout_seconds": 0    },    "description": "string"  }'
{  "config": {    "failure_threshold": 0,    "failure_window_seconds": 0,    "half_open_max_requests": 0,    "recovery_timeout_seconds": 0  },  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "description": "string",  "history": [    {      "at": "2019-08-24T14:15:22Z",      "from": "closed",      "reason": "string",      "to": "closed"    }  ],  "metadata": {    "property1": "string",    "property2": "string"  },  "name": "string",  "state": {    "current": "closed",    "failure_count": 0,    "half_open_requests": 0,    "last_failure_ms": 0,    "last_failure_time": "2019-08-24T14:15:22Z",    "last_state_change": "2019-08-24T14:15:22Z",    "last_state_change_ms": 0  },  "stats": {    "failure_rate": 0.1,    "total_failures": 0,    "total_requests": 0,    "total_successes": 0  },  "tags": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}
DELETE/api/v1/circuits/{circuit_name}

Delete a circuit breaker

DELETE
/api/v1/circuits/{circuit_name}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Response Body

curl -X DELETE "https://example.com/api/v1/circuits/string"
Empty
GET/api/v1/circuits/{circuit_name}/history

Retrieve the state-change history for a circuit

GET
/api/v1/circuits/{circuit_name}/history

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Query Parameters

limit?integer

Maximum number of most-recent events to return

Range0 <= value

Response Body

application/json

curl -X GET "https://example.com/api/v1/circuits/string/history"
{  "circuit_name": "string",  "events": [    {      "at": "2019-08-24T14:15:22Z",      "from": "closed",      "reason": "string",      "to": "closed"    }  ],  "total_count": 0}
POST/api/v1/circuits/{circuit_name}/report-failure

Report a failure to the circuit breaker

POST
/api/v1/circuits/{circuit_name}/report-failure

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to report a failure

Response Body

application/json

curl -X POST "https://example.com/api/v1/circuits/string/report-failure" \  -H "Content-Type: application/json" \  -d '{    "duration_ms": 0,    "error_message": "string",    "error_type": "string"  }'
{  "action": "string",  "circuit_name": "string",  "failure_count": 0,  "message": "string",  "state": "closed",  "state_changed": true}
POST/api/v1/circuits/{circuit_name}/report-success

Report a success to the circuit breaker

POST
/api/v1/circuits/{circuit_name}/report-success

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to report a success

Response Body

application/json

curl -X POST "https://example.com/api/v1/circuits/string/report-success" \  -H "Content-Type: application/json" \  -d '{    "duration_ms": 0  }'
{  "action": "string",  "circuit_name": "string",  "failure_count": 0,  "message": "string",  "state": "closed",  "state_changed": true}
POST/api/v1/circuits/{circuit_name}/reset

Manually reset a circuit to closed state

POST
/api/v1/circuits/{circuit_name}/reset

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to manually reset a circuit

Response Body

application/json

curl -X POST "https://example.com/api/v1/circuits/string/reset" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'
{  "action": "string",  "circuit_name": "string",  "previous_state": "closed",  "reason": "string",  "reset_by": "string",  "state": "closed"}
GET/api/v1/circuits/{circuit_name}/stats

Retrieve detailed statistics for a circuit

GET
/api/v1/circuits/{circuit_name}/stats

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Response Body

application/json

curl -X GET "https://example.com/api/v1/circuits/string/stats"
{  "circuit_name": "string",  "current_state": "closed",  "metrics": {    "avg_failure_duration_ms": 0,    "avg_success_duration_ms": 0,    "failure_rate": 0.1,    "time_in_closed_state_seconds": 0,    "time_in_half_open_state_seconds": 0,    "time_in_open_state_seconds": 0,    "total_failures": 0,    "total_requests": 0,    "total_successes": 0  },  "state_changes": [    {      "at": "2019-08-24T14:15:22Z",      "from": "closed",      "reason": "string",      "to": "closed"    }  ],  "window": "string"}
GET/api/v1/circuits/{circuit_name}/status

Get circuit status and check if request should be allowed

GET
/api/v1/circuits/{circuit_name}/status

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Response Body

application/json

curl -X GET "https://example.com/api/v1/circuits/string/status"
{  "allow_request": true,  "circuit_name": "string",  "failure_count": 0,  "half_open_requests": 0,  "is_open": true,  "last_failure_at": "2019-08-24T14:15:22Z",  "reason": "string",  "state": "closed",  "stats": null,  "time_until_recovery": 0}
POST/api/v1/circuits/{circuit_name}/trip

Manually trip a circuit to the open state

POST
/api/v1/circuits/{circuit_name}/trip

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

circuit_name*string

Name of the circuit breaker

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to manually trip a circuit open

Response Body

application/json

curl -X POST "https://example.com/api/v1/circuits/string/trip" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'
{  "action": "string",  "circuit_name": "string",  "previous_state": "closed",  "reason": "string",  "state": "closed",  "tripped_by": "string"}

Chrono

Temporal resource regeneration, cooldowns and idle accrual

Comment

Universal threaded comments with moderation and reactions

On this page

List all circuitsRetrieve circuit configuration and state metadataCreate or update a circuit breakerDelete a circuit breakerRetrieve the state-change history for a circuitReport a failure to the circuit breakerReport a success to the circuit breakerManually reset a circuit to closed stateRetrieve detailed statistics for a circuitGet circuit status and check if request should be allowedManually trip a circuit to the open state