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 a subject may use per window — for example 200 cents a month for every user.

await limitry.limits.create({
  subject: {
    kind: "user",
  },
  amount: 200,
  window: "month",
});

limitry.limits.create(
    subject={"kind": "user"},
    amount=200,
    window="month",
)

limitry limits create \
  --subject '{"kind":"user"}' \
  --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 '{"subject":{"kind":"user"},"amount":200,"window":"month"}'

Field	Description
`name`string	A name, unique among the environment's active limits. Default: the sentence the limit reads as, such as "200 cents per user per month". If a limit already has that name, the answer is 409: give this one a name.
`subject`object, required	Who it applies to: `{"kind": "user"}` for every user, `{"kind": "user", "id": "usr_123"}` for one.
`action`string	The action to limit. Default: `*`, every action.
`amount`number, required	How many units each subject may use per window.
`unit`string	What the amount counts, in words. Default: units.
`window`string, required	`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, reset where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, raised by credits. `concurrent`: at most `amount` open 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). `billing_date`: from the subject's billing date, set with `subjects.update` (its first check until then), so an annual plan can reset 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

Only subject.kind, amount and window are needed: action defaults to every action (*), unit to units, and name to the sentence the limit reads as. Checks enforce it from then on. What it counts (subject, action, unit, window, every, start, rolling) is fixed once created. 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("lmt_3f0c…");

limitry.limits.get("lmt_3f0c…")

limitry limits get 'lmt_3f0c…'

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

Field	Description
`limitId`string, path, required

Change a limit

PATCH /v1/limits/{limitId}

Changes a limit’s name, amount, fail mode or whether it is enabled; checks use the new rule at once.

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

limitry.limits.update("lmt_3f0c…")

limitry limits update 'lmt_3f0c…'

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

Field	Description
`limitId`string, path, required
`name`string	A new name, unique among the environment's active limits.
`amount`number	How many units each subject may use per window.
`enabled`boolean	Whether checks enforce it.
`failMode`string	What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny).
`subject`object	Who it applies to. Fixed once the limit is created: to change it, create a new limit and archive this one.
`action`string	The action. Fixed once the limit is created: to change it, create a new limit and archive this one.
`unit`string	What the amount counts. Fixed once the limit is created: to change it, create a new limit and archive this one.
`window`string	The window. Fixed once the limit is created: to change it, create a new limit and archive this one.
`every`number	How many windows a period lasts. Fixed once the limit is created: to change it, create a new limit and archive this one.
`start`string	Where a period begins. Fixed once the limit is created: to change it, create a new limit and archive this one.
`rolling`boolean	Whether it counts the last window. Fixed once the limit is created: to change it, create a new limit and archive this one.

More about this endpoint

What a limit counts (subject, action, unit, window, every, start, rolling) is fixed: a different value is refused (400) — create a new limit and archive this one. Owners and admins only, for a person’s token.

Archive a limit

POST /v1/limits/{limitId}/archive

Stops a limit: checks stop enforcing it at once, and it leaves the list.

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

limitry.limits.archive("lmt_3f0c…")

limitry limits archive 'lmt_3f0c…'

curl -X POST "https://api.limitry.com/v1/limits/lmt_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 credits 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("lmt_3f0c…");

limitry.limits.restore("lmt_3f0c…")

limitry limits restore 'lmt_3f0c…'

curl -X POST "https://api.limitry.com/v1/limits/lmt_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",
      subject: {
        kind: "user",
      },
      action: "ai-call",
      amount: 200,
      unit: "cents",
      window: "month",
    },
  ],
});

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

limitry sync [file], short for:

limitry limits sync \
  --limits '[{"name":"AI budget","subject":{"kind":"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","subject":{"kind":"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. What a limit counts (subject, action, unit, window, every, start, rolling) is fixed: to change it, rename the entry, which creates a new limit. At most 200.
`archiveMissing`boolean	Archive the environment's active limits whose names aren't in `limits` (restorable). Default: false, which leaves them alone.
`preview`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. What a limit counts is fixed: a different subject, action, unit or window under an existing name is refused until the entry is renamed. preview answers what it would do 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 credits

GET /v1/limits/{limitId}/credits

Credits added to (or taken back from) subjects’ balances for this limit, newest first.

await limitry.limits.credits.list("lmt_3f0c…");

limitry.limits.credits.list("lmt_3f0c…")

limitry limits credits list 'lmt_3f0c…'

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

Field	Description
`limitId`string, path, required

Add credits to a balance

POST /v1/limits/{limitId}/credits

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

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

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

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

curl -X POST "https://api.limitry.com/v1/limits/lmt_3f0c…/credits" \
  -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 more credits are added. Owners and admins, or a workspace API key; an agent asks a person (the limit.credit approval).