API reference

Plan limits for any tool

POST /v1/limits — send a coding tool's plan limits (percent used and reset time per window) for the Usage page.

POST /v1/limits puts any tool's plan limits on the Usage page, next to Claude's (from the status line). The Agentower hook uses it for Codex. Scope: ingest; the limits belong to the key's person.

#The body

Field	Type	Notes
`provider`	string	Required. Lower case, e.g. `codex`, `grok`: letters, digits and `-`, up to 30
`account`	string	Optional. Your own name for the account, e.g. `work` (letters, digits, spaces, `. _ -`, up to 40). Anything else is dropped
`windows`	array	Required. 1–4 windows
`windows[].id`	string	Optional. Your name for the window, e.g. `primary`
`windows[].used` or `used_percent`	number	Required. 0–100
`windows[].resets_at`	number	Optional. When it resets, in seconds since 1970
`windows[].window_minutes`	number	Optional. Its length; labels it ("5 h", "Week") and orders windows, shortest first
`windows[].label`	string	Optional. Your own label, up to 20 characters

One set is kept per person, provider and account. Within a window (same reset time) the highest figure wins, so several sessions reporting at once don't make it go backwards.

Send Codex-style limits

curl -X POST "$AGENTOWER_URL/v1/limits" \
  -H "authorization: Bearer $AGENTOWER_KEY" \
  -H "content-type: application/json" \
  -d '{"provider":"codex","account":"team","windows":[{"id":"primary","used_percent":12,"window_minutes":300,"resets_at":1790700000},{"id":"secondary","used_percent":61,"window_minutes":10080,"resets_at":1791000000}]}'

Response · 200

{ "ok": true, "accepted": 1 }

No windows

curl -X POST "$AGENTOWER_URL/v1/limits" \
  -H "authorization: Bearer $AGENTOWER_KEY" \
  -H "content-type: application/json" \
  -d '{"provider":"codex","windows":[]}'

Response · 400

{ "error": "invalid_limits", "hint": "{ provider, account?, windows: [{ used, resets_at?, window_minutes? }] } — up to 4 windows" }

Each person keeps at most 6 accounts; the least recently heard is dropped first. Requests share the reporting rate limit (see Errors and limits); bodies up to 2 kB.