API reference

Plan limits (status line)

POST /v1/status/claude-code — the Claude plan's 5-hour and weekly use, from the status-line script.

The Agentower status-line script sends the Claude plan's usage windows here, so the app can show them live. Scope: ingest. Setup for people is in Plan limits.

#POST /v1/status/claude-code

Field	Type	Notes
`v`	number	`1`
`five_hour`	object	`{ "used": 42, "resets_at": 1790000000 }` — percent used (0–100) and the reset time in seconds since 1970
`seven_day`	object	The same, for the weekly window
`session_id`	string	Optional. The Claude Code session, so its model can be recorded
`model`	string	Optional. The model's name, e.g. `claude-opus-5-5`
`effort`	string or null	Optional. The effort level the session works at, e.g. `high` (Claude Code: `low`, `medium`, `high`, `xhigh`, `max`); lower-case letters, up to 12. `null` = the model has no effort level (clears it); left out = unchanged
`account`	string	Optional. Your name for this Claude account (`AGENTOWER_ACCOUNT`), e.g. `work`: letters, digits, spaces and `. _ -`, up to 40

Either window can be left out. A reset time more than a year from now is ignored.

Plan limits

curl -X POST "$AGENTOWER_URL/v1/status/claude-code" \
  -H "authorization: Bearer $AGENTOWER_KEY" \
  -H "content-type: application/json" \
  -d '{"v":1,"five_hour":{"used":42,"resets_at":1790000000},"seven_day":{"used":61,"resets_at":1790500000},"session_id":"3f1c9a52-docs-example","model":"claude-opus-5-5"}'

Response · 200

{ "ok": true, "accepted": 1, "agent": "BIL-02", "name": "Sarah" }

agent is the session's short ID, which the status line shows at the start of the line (null when the session isn't known yet). The call also works as a heartbeat: it counts as a sign of life, so the session's agent stays on the board while it keeps arriving. It only ever keeps an agent open longer: when it stops, the usual limits apply from the last activity or heartbeat (an idle agent is done 4 hours later).

With no usable window — for example from a Claude Code session signed in with an API key, which has no plan limits — the answer is { "ok": true, "accepted": 0, "agent": … }: no plan numbers are stored, but the heartbeat and ID still work.

Agentower keeps the latest numbers per person and account (see Usage and several accounts).