---
name: limitry
description: Use when working with Limitry (limitry.com) — reading or changing a workspace in Limitry through its MCP tools, the `limitry` command line or its API. Covers signing in, choosing the workspace, every operation, errors and pagination.
---

# Limitry

Limitry is the runtime that decides, at request time, whether a user, workspace, API key or agent may do something at a given cost — usage, credits, quotas, budgets, concurrency and entitlements in one check.

Everything belongs to a **workspace**. You act as the person who signed
you in, with their role in that workspace and only the access they
granted — if they could not do something in the app, neither can you.

## Choose how to connect

- **MCP tools** (preferred when your client has them — names like `workspace_get`): the server is `https://mcp.limitry.com/mcp`. Connecting opens the person's browser to sign in, pick ONE workspace and the access. The tools you see are exactly what they allowed.
- **Command line** `limitry` (`npm install -g @limitry/cli`): `limitry login` signs in through the browser; without a browser, the person sets `LIMITRY_TOKEN` to a personal access token. Add `--json` to EVERY command: output is the API's JSON, errors are JSON on stderr, exit code 0 means success.
- **HTTP API** `https://api.limitry.com/v1` with `Authorization: Bearer <token>`; the OpenAPI document is `https://api.limitry.com/v1/openapi.json`.

## Rules

- Find the workspace first (`limitry workspace list --json`); pass `--workspace <slug>` or ask the person which one. Never guess a slug.
- Read before you change anything, and say what you will change before you do.
- An operation that cannot be undone (a delete) needs the person's explicit go-ahead — only then pass `--yes`.
- Lists return one page: pass `nextCursor` as `cursor` (`--cursor`) for the next.
- Writes are safe to retry: the CLI sends an `Idempotency-Key`; over HTTP, send your own.
- Errors carry `code` and `message`: `unauthorized` → sign in again; `forbidden` → this sign-in lacks the access or role (tell the person what is missing — never work around it); `rate_limited` → wait for `Retry-After`; `invalid_request` → fix the input from `details`.

## Operations

| Command | MCP tool | What it does |
| --- | --- | --- |
| `limitry checks create` | `checks_create` | Check whether a subject may act |
| `limitry limit-grants list <limitId>` | `limit_grants_list` | List a balance's grants |
| `limitry limits create` | `limits_create` | Create a limit |
| `limitry limits delete <limitId>` | `limits_delete` | Delete a limit |
| `limitry limits get <limitId>` | `limits_get` | Get a limit |
| `limitry limits list` | `limits_list` | List limits |
| `limitry limits update <limitId>` | `limits_update` | Change a limit |
| `limitry reservations commit <id>` | `reservations_commit` | Commit a reservation |
| `limitry reservations extend <id>` | `reservations_extend` | Extend a reservation |
| `limitry reservations release <id>` | `reservations_release` | Release a reservation |
| `limitry usage query` | `usage_query` | A limit's usage over time |
| `limitry usage subjects` | `usage_subjects` | Who is using a limit now |
| `limitry user me` | — | Identify the authenticated user |
| `limitry user revoke-token` | — | Revoke the token making this request |
| `limitry workspace approval-actions list` | `workspace_approval_actions_list` | List the actions you can ask approval for |
| `limitry workspace approval-requests create` | `workspace_approval_requests_create` | Ask a person to approve an action |
| `limitry workspace approval-requests get <requestId>` | `workspace_approval_requests_get` | Check an approval request |
| `limitry workspace audit-events list` | `workspace_audit_events_list` | List workspace audit events |
| `limitry workspace event-types list` | `workspace_event_types_list` | List event types |
| `limitry workspace get` | `workspace_get` | Identify the authenticated workspace |
| `limitry workspace invitations list` | `workspace_invitations_list` | List pending invitations |
| `limitry workspace members list` | `workspace_members_list` | List workspace members |
| `limitry workspace teams list` | `workspace_teams_list` | List teams |
| `limitry workspace usage` | `workspace_usage` | Get the workspace's usage this month |
| `limitry workspace webhook-deliveries list <endpointId>` | `workspace_webhook_deliveries_list` | List an endpoint's deliveries |
| `limitry workspace webhook-deliveries redeliver <endpointId> <deliveryId>` | `workspace_webhook_deliveries_redeliver` | Redeliver an event |
| `limitry workspace webhook-endpoints get <endpointId>` | `workspace_webhook_endpoints_get` | Get a webhook endpoint |
| `limitry workspace webhook-endpoints list` | `workspace_webhook_endpoints_list` | List webhook endpoints |
| `limitry workspace webhook-endpoints test <endpointId>` | `workspace_webhook_endpoints_test` | Send a test event |

`limitry <command> --help` lists each command's inputs; `limitry api <method> <path>` calls any endpoint directly.

## For people only

Never do these yourself, even if you could — ask for approval (below) or tell the person to do it in the app, and why:

- Add credits to a balance: Adding credits gives value away; an agent asks a person (limit.grant approval)
- Redeem an approved request (command line): Returns a secret; secrets never enter an agent's conversation — the command line writes them to a file.
- Add a webhook endpoint: Changes where workspace data is sent. A person configures webhook endpoints (Settings → Webhooks in the app).
- Remove a webhook endpoint: Changes where workspace data is sent. A person configures webhook endpoints (Settings → Webhooks in the app).
- Re-enable a webhook endpoint: Changes where workspace data is sent. A person configures webhook endpoints (Settings → Webhooks in the app).

## When a person must approve

Some actions are never yours to take alone — creating an API key, adding or removing a webhook endpoint, and others the product lists. ASK instead, and wait for a person:

- MCP: `workspace_approval_actions_list` shows what can be asked and its input; `workspace_approval_requests_create` files it with your reason — show the person the returned `approveUrl`; `approval_requests_get` tells you when it is decided. A secret it creates is shown to the approving person, never to you.
- Command line: `limitry workspace approval-actions list --json`; `limitry workspace approval-requests create --action <id> --input '{…}' --reason "…" --json` (show the person the `approveUrl`); then, for an action that creates a secret, `limitry workspace approval-requests redeem <id> --wait --write-env .env` — it waits for the decision and writes the secret into the file WITHOUT printing it. Never ask the person to paste a secret to you.
- Requests expire after 24 hours; a denied request is final — ask the person what they want instead.

## More

- Documentation for agents: https://limitry.com/docs/llms.txt (index) and https://limitry.com/docs/llms-full.txt (everything)
- Errors: https://limitry.com/docs/errors/

## What Limitry is

Limitry decides, at request time, whether a **subject** (a user,
workspace, API key or agent of the person's own product) may do an
**action** at a **cost**. The answer is allowed or not allowed, with what
remains — a "not allowed" is a normal answer, not an error to retry.

## Limits

A limit says how much of an action a subject may use per window
(`limits list|get|create|update|delete`, or the `limits_*` tools).
Before creating one, confirm with the person: which subjects (kind, and
one id or all), which action (or `*`), how many per `minute`, `hour`,
`day` or `month` (`rolling: true` for "in any 24 hours" — no burst at
midnight), or at once (`concurrent`), and whether their product should allow or deny when
Limitry is unreachable (`failMode`, default `open` = allow). Creating
and changing limits needs an owner's or admin's token.

## Usage

To answer "how much is X using?": `usage subjects` (`GET /v1/usage/subjects?limitId=`)
lists a limit's subjects in the current window — used, left, denied — and
`usage query` (`GET /v1/usage?limitId=`) gives a series by day or hour.
This is Limitry's usage of the person's limits — not the person's own
Limitry plan (`workspace usage`). Reports trail live checks by up to a
minute.

## Checks

`checks create` (`POST /v1/checks`, the `checks_create` tool) asks
whether a subject may do an action at a cost, and — in the default
`consume` mode — uses it. The answer is ALWAYS 200: read `allowed`; a
`false` is a normal answer to act on (show `remaining`, wait
`retryAfterSeconds`), never an error to retry. Use `mode: "preview"` to
ask without using. Send an `Idempotency-Key` when the caller may retry.

When users share an allowance (a team's pool), pass the team as
`shared: [{ kind: "team", id }]` on each user's check — define the pool
as a limit on the team. Prepaid credits are a limit with window `total`
(a balance); never add credits yourself — ask the person (the
`limit.grant` approval). An agent's budget is a limit in `cents` on
`agent`, action `*`, with each check's `cost` the price.

When the cost is known only afterwards (an AI call's tokens), use
`mode: "reserve"` with an estimate, then `reservations commit` with the
actual cost — or `reservations release` if the work did not happen.
Always settle (a `finally`): an unsettled hold blocks the estimate until
it expires. For "at most N at once" use a `concurrent` limit: each
reservation holds one slot until settled; for work longer than the hold,
call `reservations extend` as a heartbeat.

When adding Limitry to a person's code: put the check right before the
costly work, pass the real subject (their user, key or agent id) and
action names that match the limits, and honour each limit's `failMode`
when Limitry is unreachable (`open` = carry on). Ask the person before
creating or changing limits.