Throttle

GET/api/v1/throttle/plans

List_plans

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: updated_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/throttle/plans"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "plans": [    {      "actions": {        "property1": {          "cost": 0        },        "property2": {          "cost": 0        }      },      "created_at": "2019-08-24T14:15:22Z",      "default_enforcement": "soft",      "description": "string",      "headers_mode": "standard",      "limits": {        "max_requests": 0,        "window_seconds": 0      },      "owner_id": "string",      "plan_id": "string",      "refund_window_seconds": 0,      "subject_namespaces": [        "string"      ],      "tags": [        "string"      ],      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

POST/api/v1/throttle/plans

Create_plan

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a throttle plan.

Use internal IDs only; do not pass email addresses, phone numbers, or other PII as subject identifiers.

actions?

Optional map of action name to cost

default_enforcement?null|

description?|

Optional human-facing description

headers_mode?null|

limits*

Token-bucket limits

plan_id*string

Plan slug identifier (lowercase a-z, 0-9, and hyphen)

refund_window_seconds?|

How long after a consume a refund is accepted (seconds)

Formatint64

Range0 <= value

subject_namespaces?array<string>

Optional allowlist of permitted subject namespaces

tags?array<string>

Free-form metadata tags

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/throttle/plans" \  -H "Content-Type: application/json" \  -d '{    "limits": {      "max_requests": 0,      "window_seconds": 0    },    "plan_id": "string"  }'

{  "actions": {    "property1": {      "cost": 0    },    "property2": {      "cost": 0    }  },  "created_at": "2019-08-24T14:15:22Z",  "default_enforcement": "soft",  "description": "string",  "headers_mode": "standard",  "limits": {    "max_requests": 0,    "window_seconds": 0  },  "owner_id": "string",  "plan_id": "string",  "refund_window_seconds": 0,  "subject_namespaces": [    "string"  ],  "tags": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}

GET/api/v1/throttle/plans/{plan_id}

Get_plan

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/throttle/plans/string"

{  "actions": {    "property1": {      "cost": 0    },    "property2": {      "cost": 0    }  },  "created_at": "2019-08-24T14:15:22Z",  "default_enforcement": "soft",  "description": "string",  "headers_mode": "standard",  "limits": {    "max_requests": 0,    "window_seconds": 0  },  "owner_id": "string",  "plan_id": "string",  "refund_window_seconds": 0,  "subject_namespaces": [    "string"  ],  "tags": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}

PATCH/api/v1/throttle/plans/{plan_id}

Update_plan

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial update for a throttle plan.

actions?|

Replacement action catalog

default_enforcement?null|

description?|

New description

headers_mode?null|

limits?null|

refund_window_seconds?|

New refund window in seconds

Formatint64

Range0 <= value

tags?array<string>|

Replacement tag set

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/throttle/plans/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "actions": {    "property1": {      "cost": 0    },    "property2": {      "cost": 0    }  },  "created_at": "2019-08-24T14:15:22Z",  "default_enforcement": "soft",  "description": "string",  "headers_mode": "standard",  "limits": {    "max_requests": 0,    "window_seconds": 0  },  "owner_id": "string",  "plan_id": "string",  "refund_window_seconds": 0,  "subject_namespaces": [    "string"  ],  "tags": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}

DELETE/api/v1/throttle/plans/{plan_id}

Delete_plan

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/throttle/plans/string"

{  "message": "string",  "plan_id": "string"}

POST/api/v1/throttle/plans/{plan_id}/check

Check

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Query Parameters

enforce?string

Override the plan default enforcement: hard returns 429 on denial

Value in

"soft"
"hard"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Check + consume against a plan bucket.

action?|

Optional action name; falls back to the default bucket when omitted

cost?|

Optional explicit cost overriding the action default

Formatint64

Range0 <= value

subject*string

Opaque subject identifier of the form {namespace}:{id}

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/throttle/plans/string/check" \  -H "Content-Type: application/json" \  -d '{    "subject": "string"  }'

{  "allowed": true,  "consume_token": "string",  "limit": 0,  "reason": "string",  "remaining": 0,  "reset_after_seconds": 0,  "reset_at": 0,  "retry_after_seconds": 0}

POST/api/v1/throttle/plans/{plan_id}/peek

Peek

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Read-only bucket inspection.

action?|

Optional action name

subject*string

Opaque subject identifier

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/throttle/plans/string/peek" \  -H "Content-Type: application/json" \  -d '{    "subject": "string"  }'

{  "limit": 0,  "remaining": 0,  "reset_after_seconds": 0,  "reset_at": 0}

POST/api/v1/throttle/plans/{plan_id}/refund

Refund

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Refund a prior consume by its token.

action?|

Optional action name (must match the original check)

consume_token*string

Consume token returned by the original allowed check

subject*string

Opaque subject identifier

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/throttle/plans/string/refund" \  -H "Content-Type: application/json" \  -d '{    "consume_token": "string",    "subject": "string"  }'

{  "cost_refunded": 0,  "refunded": true}

POST/api/v1/throttle/plans/{plan_id}/reset

Reset

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Administratively reset a subject bucket to full capacity.

action?|

Optional action name

subject*string

Opaque subject identifier

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/throttle/plans/string/reset" \  -H "Content-Type: application/json" \  -d '{    "subject": "string"  }'

{  "message": "string"}

GET/api/v1/throttle/plans/{plan_id}/stats

Stats

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

plan_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/throttle/plans/string/stats"

{  "plan_id": "string",  "total_allowed": 0,  "total_checks": 0,  "total_denied": 0,  "total_refunded": 0}

Throttle

200application/json

400

403

201application/json

400

403

409

200application/json

404

200application/json

400

403

404

200application/json

403

404

200application/json

400

403

404

429

200application/json

403

404

200application/json

403

404

200application/json

403

404

200application/json

403

404

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`