Acquire a concurrency lease

POST

/v1/leases

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

Authorizations

• api_key

Request Body^required

Media typeapplication/json

Body for POST /v1/leases. limit/window_ms are optional: inline wins, else the namespace’s concurrent_limit rule fills them (§2.3).

object

key

required

string

limit

Max concurrent slots. Optional when a concurrent rule exists.

integer | null format: int64

namespace

required

string

window_ms

Lease TTL in milliseconds. Optional when a concurrent rule exists.

integer | null format: int64

Example^generated

{
  "key": "example",
  "limit": 1,
  "namespace": "example",
  "window_ms": 1
}

Responses

200

Lease decision — always 200; allowed carries the verdict, lease_id set when allowed

Media typeapplication/json

object

active

required

Active lease count after this call.

integer format: int64

allowed

required

boolean

lease_id

string | null

limit

required

integer format: int64

reset_ms

required

When denied, ms until the soonest-expiring lease frees a slot.

integer format: int64

Example^generated

{
  "active": 1,
  "allowed": true,
  "lease_id": "example",
  "limit": 1,
  "reset_ms": 1
}

400

Malformed / missing limit+window_ms

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

Concurrent_limit is 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"
}

429

Monthly hard ceiling exceeded (§4.2 anti-abuse cap)

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"
}