Limits

Set up

npm install @limitry/sdk

import { createClient } from "@limitry/sdk";

const limitry = createClient(); // reads LIMITRY_API_KEY

pip install limitry

from limitry import Limitry

limitry = Limitry()  # reads LIMITRY_API_KEY

npm install -g @limitry/cli
limitry login

export LIMITRY_API_KEY="lim_test_…"

List limits

GET /v1/limits

The workspace’s active limits, newest first (archived=true: the archived ones).

await limitry.limits.list();

limitry.limits.list()

limitry limits list

curl -X GET "https://api.limitry.com/v1/limits" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
`limit`number, query	Items per page, 1–100 (default 25).
`cursor`string, query	Opaque token from a previous page's nextCursor.
`subjectKind`string, query	Only this kind.
`action`string, query	Only this action.
`archived`string, query	`true`: the archived limits instead.

More about this endpoint

Filter by subjectKind and action; paginate with the opaque nextCursor token.

Create a limit

POST /v1/limits

Limits how much of an action a subject may use per window — for example 200 cents of ai-call a month for every user.

await limitry.limits.create({
  name: "AI budget",
  subjectKind: "user",
  action: "ai-call",
  amount: 200,
  window: "month",
});

limitry.limits.create(
    name="AI budget",
    subject_kind="user",
    action="ai-call",
    amount=200,
    window="month",
)

limitry limits create \
  --name 'AI budget' \
  --subject-kind user \
  --action ai-call \
  --amount 200 \
  --window month

curl -X POST "https://api.limitry.com/v1/limits" \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI budget","subjectKind":"user","action":"ai-call","amount":200,"window":"month"}'

Field	Description
`name`string, required	A name for the limit, unique among its environment's active limits.
`subjectKind`string, required	Your own label for who is checked.
`subjectId`string	One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window.
`action`string, required	The action to limit; `*` for every action.
`amount`number, required	How many units each subject may use per window.
`unit`string	What the amount counts (display only). Default: units.
`window`string, required	`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once.
`every`number	How many `window` units a period lasts: `window: "month", every: 3` is a quarter, `window: "hour", every: 5` five hours. Default: 1.
`start`string	Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar.
`rolling`boolean	Count the last window instead of the calendar one (minute, hour or day only). Default: false.
`enabled`boolean	Whether checks enforce it. Default: true.
`failMode`string	What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny). Default: open.

More about this endpoint

Checks enforce it from then on. Names are unique among the environment’s active limits. Owners and admins only, for a person’s token.

Get a limit

GET /v1/limits/{limitId}

One limit: who it applies to, the action, amount and window.

await limitry.limits.get("lim_3f0c…");

limitry.limits.get("lim_3f0c…")

limitry limits get 'lim_3f0c…'

curl -X GET "https://api.limitry.com/v1/limits/lim_3f0c…" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
`limitId`string, path, required

Change a limit

PATCH /v1/limits/{limitId}

Changes any of a limit’s fields; checks use the new rule within a minute.

await limitry.limits.update("lim_3f0c…");

limitry.limits.update("lim_3f0c…")

limitry limits update 'lim_3f0c…'

curl -X PATCH "https://api.limitry.com/v1/limits/lim_3f0c…" \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Field	Description
`limitId`string, path, required
`name`string	A name for the limit, unique among its environment's active limits.
`subjectKind`string	Your own label for who is checked.
`subjectId`string	One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window.
`action`string	The action to limit; `*` for every action.
`amount`number	How many units each subject may use per window.
`unit`string	What the amount counts (display only). Default: units.
`window`string	`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once.
`every`number	How many `window` units a period lasts: `window: "month", every: 3` is a quarter, `window: "hour", every: 5` five hours. Default: 1.
`start`string	Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar.
`rolling`boolean	Count the last window instead of the calendar one (minute, hour or day only). Default: false.
`enabled`boolean	Whether checks enforce it. Default: true.
`failMode`string	What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny). Default: open.

More about this endpoint

Owners and admins only, for a person’s token.

Archive a limit

POST /v1/limits/{limitId}/archive

Stops a limit: checks stop enforcing it within a minute, and it leaves the list.

await limitry.limits.archive("lim_3f0c…");

limitry.limits.archive("lim_3f0c…")

limitry limits archive 'lim_3f0c…'

curl -X POST "https://api.limitry.com/v1/limits/lim_3f0c…/archive" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
`limitId`string, path, required

More about this endpoint

It is archived, not erased — its usage history and credit grants stay, and POST /v1/limits/{limitId}/restore brings it back. Owners and admins only, for a person’s token.

Restore an archived limit

POST /v1/limits/{limitId}/restore

Brings an archived limit back into force — refused while an active limit has its name.

await limitry.limits.restore("lim_3f0c…");

limitry.limits.restore("lim_3f0c…")

limitry limits restore 'lim_3f0c…'

curl -X POST "https://api.limitry.com/v1/limits/lim_3f0c…/restore" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
`limitId`string, path, required

More about this endpoint

Owners and admins only, for a person’s token.

Sync limits from a list

POST /v1/limits/sync

Makes the environment’s limits match limits, by name: creates the missing, changes those that differ (an omitted field means its default) and, with archiveMissing, archives active limits the list doesn’t name.

await limitry.limits.sync({
  limits: [
    {
      name: "AI budget",
      subjectKind: "user",
      action: "ai-call",
      amount: 200,
      unit: "cents",
      window: "month",
    },
  ],
});

limitry.limits.sync(
    limits=[
        {
            "name": "AI budget",
            "subjectKind": "user",
            "action": "ai-call",
            "amount": 200,
            "unit": "cents",
            "window": "month",
        },
    ],
)

limitry sync [file], short for:

limitry limits sync \
  --limits '[{"name":"AI budget","subjectKind":"user","action":"ai-call","amount":200,"unit":"cents","window":"month"}]'

curl -X POST "https://api.limitry.com/v1/limits/sync" \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limits":[{"name":"AI budget","subjectKind":"user","action":"ai-call","amount":200,"unit":"cents","window":"month"}]}'

Field	Description
`limits`array, required	Every limit you want, each described whole: an omitted field is its default, as on create. Names are the key and must be unique in the list. At most 200.
`archiveMissing`boolean	Archive the environment's active limits whose names aren't in `limits` (restorable). Default: false, which leaves them alone.
`dryRun`boolean	Answer what the sync would do and change nothing. Default: false.

More about this endpoint

Running it twice changes nothing the second time. Limitry checks the whole list first, and a problem anywhere changes nothing (400, each problem in details); then it writes every change at once. dryRun answers the plan without writing. For keeping limits in a file in your repository (limitry sync). Owners and admins only, for a person’s token.

List a balance’s grants

GET /v1/limits/{limitId}/grants

Credits added to subjects’ balances for this limit, newest first.

await limitry.limits.grants.list("lim_3f0c…");

limitry.limits.grants.list("lim_3f0c…")

limitry limits grants list 'lim_3f0c…'

curl -X GET "https://api.limitry.com/v1/limits/lim_3f0c…/grants" \
  -H "Authorization: Bearer $LIMITRY_API_KEY"

Field	Description
`limitId`string, path, required

Add credits to a balance

POST /v1/limits/{limitId}/grants

Adds amount to one subject’s balance — a limit whose window is total.

await limitry.limits.grants.create("lim_3f0c…", {
  subject: {
    kind: "team",
    id: "team_42",
  },
  amount: 5000,
});

limitry.limits.grants.create(
    "lim_3f0c…",
    subject={"kind": "team", "id": "team_42"},
    amount=5000,
)

limitry limits grants create \
  'lim_3f0c…' \
  --subject '{"kind":"team","id":"team_42"}' \
  --amount 5000

curl -X POST "https://api.limitry.com/v1/limits/lim_3f0c…/grants" \
  -H "Authorization: Bearer $LIMITRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":{"kind":"team","id":"team_42"},"amount":5000}'

Field	Description
`limitId`string, path, required
`subject`object, required	Who gets the credits, as `{"kind": "team", "id": "team_42"}`.
`amount`number, required	Credits to add; negative to take them back. Not 0.
`note`string	Required when `amount` is negative.

More about this endpoint

A negative amount takes credits back (a refund, a chargeback) and needs a note saying why; the balance may go below zero, and checks are refused until it is topped up. Owners and admins, or a workspace API key; an agent asks a person (the limit.grant approval).