Create or update a namespace rule

POST

/v1/namespaces/{ns}/rules

curl --request POST \
  --url https://example.com/v1/namespaces/example/rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "algorithm": "token_bucket", "limit": 1, "name": "example", "window_ms": 1 }'

Authorizations

• api_key

Parameters

Path Parameters

ns

required

string

Namespace name

Request Body^required

Media typeapplication/json

Body for POST /v1/namespaces/{ns}/rules. The namespace comes from the path.

object

algorithm

required

string

Example

token_bucket

limit

required

integer format: int64

name

string | null

window_ms

required

integer format: int64

Responses

200

Rule created or replaced

Media typeapplication/json

The default rule for a namespace. limit/window_ms are u64 on the wire but stored as int/bigint; values are range-checked before insert.

object

algorithm

required

string

limit

required

integer format: int64

name

string | null

namespace

required

string

window_ms

required

integer format: int64

Example

{
  "algorithm": "sliding_window"
}

400

Limit/window_ms invalid

Media typeapplication/json

The JSON body returned for every error response: { "error": "<message>" }, optionally with a stable machine code ({ "error": ..., "code": ... }). The code lets clients map an error to their own localized copy instead of showing the English error string; it is present only for errors we’ve assigned a stable code, and omitted otherwise.

object

code

Stable machine-readable error code for client-side localization, when one is defined for this error (e.g. key_not_found, algorithm_not_on_plan).

string | null

error

required

Human-readable error message. Never contains internal/driver detail.

string

Example^generated

{
  "code": "example",
  "error": "example"
}

401

Missing or invalid API key

Media typeapplication/json

The JSON body returned for every error response: { "error": "<message>" }, optionally with a stable machine code ({ "error": ..., "code": ... }). The code lets clients map an error to their own localized copy instead of showing the English error string; it is present only for errors we’ve assigned a stable code, and omitted otherwise.

object

code

Stable machine-readable error code for client-side localization, when one is defined for this error (e.g. key_not_found, algorithm_not_on_plan).

string | null

error

required

Human-readable error message. Never contains internal/driver detail.

string

Example^generated

{
  "code": "example",
  "error": "example"
}

403

Algorithm not available on the caller’s plan (§4.3)

Media typeapplication/json

The JSON body returned for every error response: { "error": "<message>" }, optionally with a stable machine code ({ "error": ..., "code": ... }). The code lets clients map an error to their own localized copy instead of showing the English error string; it is present only for errors we’ve assigned a stable code, and omitted otherwise.

object

code

Stable machine-readable error code for client-side localization, when one is defined for this error (e.g. key_not_found, algorithm_not_on_plan).

string | null

error

required

Human-readable error message. Never contains internal/driver detail.

string

Example^generated

{
  "code": "example",
  "error": "example"
}