API tier gating: Glassmkr documentation

#Overview

Free tier: the full read+write API (keys carry read, write, or admin scope), all 65 rules, all six notification channels, predictive trend warnings, and full web-dashboard access. Up to 3 nodes, 7-day metric retention, one trial AI analysis per server.
Pro tier: every Free capability, plus more than 3 nodes (at $3 per node per month), 90-day metric retention, and unlimited AI analysis.

The API itself is not tier-gated by HTTP verb anymore. A Free account can create servers, manage channels, acknowledge alerts, and rotate keys programmatically, bounded only by the 3-node quota and the standard rate limits. The only endpoints that return a Pro prompt are the ones that drive a Pro-only feature (additional AI analyses once the per-server trial is used).

#What is Free

The full programmatic API for your own account, read and write. Account API keys can be minted with read, write, or admin scope. Everything below is available on a Free plan, bounded by the 3-node quota and the rate limits:

All reads: GET /api/v1/servers, GET /api/v1/servers/{id}, /alerts, /health, /history, /metrics, /disk-health.
Channel CRUD: GET / POST /api/v1/channels, PUT / DELETE /api/v1/channels/{id}, POST /api/v1/channels/{id}/test (all six channel types).
Alert mutations: POST /api/v1/alerts/{id}/acknowledge, POST /api/v1/alerts/{id}/resolve, and GET / POST / DELETE /api/v1/servers/{id}/mutes.
Server management: POST /api/v1/servers (up to the 3-node quota), PATCH, DELETE, POST /api/v1/servers/{id}/rotate-key, /restore, /restore-all.
Trend warnings: GET /api/v1/servers/{id}/trend-warnings, POST / DELETE /api/v1/trend-warnings/{id}/feedback, GET /api/v1/trend-warnings/track-record.
Account management: GET /api/v1/account/audit (30-day retention on Free), GET / POST /api/v1/account/keys, POST /api/v1/account/keys/{id}/rotate, DELETE /api/v1/account/keys/{id}.
One trial AI analysis per server: POST /api/v1/servers/{id}/analyze, GET /api/v1/servers/{id}/analyses.
All auth endpoints (/auth/login, /auth/register, /auth/me, etc.) and all billing endpoints (/billing/checkout, /billing/status, etc.).
Crucible agent ingest: POST /api/v1/ingest (collector key, never gated).
GET /api/v1/version and the public health probe GET /api/v1/health (unauthenticated).

#What is Pro

Pro is not a different API surface. It lifts three limits on the same surface:

More than 3 nodes. Past the free quota, each node is $3 per month. POST /api/v1/servers beyond the quota requires an active Pro subscription with a card on file.
Retention beyond 7 days. Pro retains 90 days of full metric history (Free retains 7); the audit log retains 365 days on Pro versus 30 on Free.
Unlimited AI analysis. Free gets one trial analysis per server; after that, additional calls to POST /api/v1/servers/{id}/analyze require Pro.

Notification channels, the read+write API, and trend warnings are not Pro; they are on every plan.

#What a 402 response looks like

When a Free-tier request crosses one of the three Pro limits (for example, an extra AI analysis after the per-server trial is used, or a server beyond the 3-node quota), Glassmkr returns 402 Payment Required:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "pro_required",
  "message": "This requires the Pro plan. Visit app.glassmkr.com/settings to upgrade.",
  "upgrade_url": "https://app.glassmkr.com/settings",
  "documentation_url": "https://glassmkr.com/docs/programmatic-api"
}

The shape is stable; error is the machine-readable code, message is human-readable, upgrade_url points to the billing flow. Integrators on the Free tier should handle 402 explicitly and route it to an upgrade-prompt UI rather than a generic auth-error path. Note that most of the API never returns 402 on Free; it is reserved for the three Pro limits above.

402 is distinct from 403 (insufficient_scope) and 401 (auth_failed); the codes are stable and safe to branch on.

#Web dashboard

The web dashboard (session cookie auth) is fully functional on every plan, exactly like the API. Free customers see the full UI; the three Pro limits render upgrade prompts where appropriate (an extra AI analysis, a fourth node, longer retention), but nothing else is withheld.

The API and the dashboard apply the same three limits. There is no API-only or dashboard-only gating.

#Free trial quotas

The one Pro feature with a Free trial quota is AI analysis:

AI analysis: each Free server gets one trial analysis. After that, additional analyses require Pro. The trial counter is per-server and persistent, and applies identically whether you trigger it from the dashboard or via POST /api/v1/servers/{id}/analyze.

Once a server's trial is used, further analyze calls return 402 immediately without re-consuming the trial budget.

#How we keep this honest

A CI lint (pnpm lint:tier-gating) enforces that every endpoint under /api/v1 declares its tier, either via inline marker or via the explicit allowlist at scripts/tier-gating-allowlist.json. CI fails if any new endpoint ships without a declaration. There should be no silent leakage between Free and Pro.