Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2653 Docs: document health stream limits and narrowed snapshots in the swamp serve REST API reference

Opened by stack72 · 9/28/2026

content/manual/reference/swamp-serve/rest-api.md lists only 200 and 401 for GET /api/v1/health/stream and GET /api/v1/health. The following behaviour is shipped (#2680) or shipping (swamp-club/swamp#2683) and needs documenting:

  • GET /api/v1/health/stream returns 429 Too Many Requests with Retry-After: 30 when the token already holds 10 open streams (counted across every mint of the token name), or when its principal holds 20 open streams across all of its tokens.
  • Any valid server token may read both endpoints (#2680). Admins see the full snapshot. Other tokens see only the runs, schedules and webhooks of workflows and models they may read, without run principals, workers or components. Instance status, uptime and aggregate metrics are visible to every reader.
  • One collected snapshot serves every reader for up to 1 s, so snapshots may be up to a second old.
  • After a tag edit that changes which grants match, a non-admin reader's filtered view may take up to 5 s to update.

Suggested change: add a 429 row to the stream Response table, and add a short note on per-token narrowing and freshness under both endpoints.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/29/2026, 11:35:29 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/29/2026, 11:33:58 PM

Docs fix in swamp-club PR 1265 (one PR covering #2626, #2653, #2661, #2679, #2692, #2694, #2701, #2728, #2733, #2740).

stack72 commented 9/29/2026, 11:35:29 PM

Documented in swamp-club PR 1265. rest-api.md adds a What each token sees subsection: admins get the full snapshot; other tokens get only the runs, schedules and webhooks of what they may read, with principalId null and empty workers and components. It also covers 1s snapshot freshness and the 5s tag-edit lag. The stream endpoint gains 429 rows (10 streams per token name, 20 per principal, Retry-After: 30, plus the request rate limiter). The response-body table was rewritten to the real field names (deploymentMode, uptimeMs, activeRuns, metrics, scheduling.schedules, ...).

Sign in to post a ripple.