GET /api/hub/leaderboard returns {"leaderboard": [...]}. Rows merge
contributors by github_username across public spokes, summing
tasks_completed, tasks_failed, and abandoned. The integer abandoned
field counts abandoned PRs; older spokes that omit it contribute zero, and
merged rows explicitly include "abandoned": 0 when none are reported.
Both full heartbeats and lightweight task-status pushes carry this field.
Private hives, agent rows, and empty usernames are excluded. Contributors
with only abandoned PRs remain visible; rows with no counts and no activity
are omitted. The added count does not change ranking.
Part of the Dashboard REST API reference; see that page for how auth levels and pkg/<file>:<line> source citations are read and checked. Edit this file for routes in this area and run src/scripts/check-api-reference-citations.sh --fix to resync citations.
| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
GET |
/login |
Hub handler-specific | Login | pkg/hub/oauth.go:69 |
GET |
/login/{provider} |
Hub handler-specific | Per-Provider Login (github or OIDC provider) | pkg/hub/oauth.go:72 |
GET |
/api/auth/callback |
Hub handler-specific | OAuth Callback | pkg/hub/oauth.go:73 |
GET |
/api/auth/user |
Hub handler-specific | Auth User | pkg/hub/oauth.go:74 |
POST |
/api/auth/logout |
Hub handler-specific | Logout | pkg/hub/oauth.go:75 |
GET |
/api/openrouter/connect/start |
Hub auth | Hub Open Router Start | pkg/hub/openrouter.go:26 |
GET |
/api/openrouter/qr |
Hub auth | Hub Open Router QR | pkg/hub/openrouter.go:27 |
GET |
/api/openrouter/models |
Hub auth | Hub Open Router Models | pkg/hub/openrouter.go:28 |
GET |
/api/openrouter/credit |
Hub auth | Hub Open Router Credit | pkg/hub/openrouter.go:29 |
GET |
/openrouter/callback |
Hub handler-specific | Hub Open Router Callback | pkg/hub/openrouter.go:30 |
GET |
/dashboard |
Hub handler-specific | Dashboard | pkg/hub/saas.go:369 |
GET |
/access-denied |
Hub handler-specific | Access Denied | pkg/hub/saas.go:370 |
GET |
/api/hub/clusters |
Hub auth | List Clusters | pkg/hub/saas.go:531 |
GET |
/api/hub/image-pulls |
Hub auth | Per-Release Image Pull Series | pkg/hub/saas.go:377 |
POST |
/api/benchmarks/ingest |
Per-hive heartbeat bearer | Spoke push target for anonymized benchmark records: body {hive_id, records[]}; the hub recomputes the hive hash from the authenticated id, rejects records whose source.hive_id differs (401 bad bearer, 403 unregistered hive, 400 malformed), merges accepted records by id into /data/benchmarks/<hash>/<YYYY-MM>.json and returns 202 {accepted, rejected, files} |
pkg/hub/benchmarks.go |
GET |
/api/hub/benchmarks |
Public | Benchmark publisher status: last_ingest_at, last_publish_at, last_publish_files, last_error, pending_files, hive_count, record_count and per-hive-hash hives{} counts; the hub commits pending month files hourly to hivecommons/benchmarks (HIVE_BENCHMARKS_REPO) via its App identity |
pkg/hub/benchmarks.go |
GET |
/api/reach |
Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | pkg/hub/saas.go:522 |
GET |
/fleet |
Hub handler-specific | My-Hives Fleet Page (static; data via /api/saas/my-hives) |
pkg/hub/server.go:1824 |
GET |
/my-hives |
Hub handler-specific | 301 redirect to /fleet (query preserved) |
pkg/hub/server.go:1825 |
GET |
/activity |
Signed-in user | Fleet activity page (#16063): read-only, data-free shell that polls /api/hub/activity every 15 s with If-None-Match. No session → 307 to /login; blocked user → 403. Own Content-Security-Policy (scripts and styles from 'self' only, script-src-attr/style-src-attr 'none'), Cache-Control: no-cache + content ETag. See Hub Fleet activity page |
pkg/hub/activity_page.go |
GET |
/activity/public |
Public | Public-safe Fleet activity page (#15966): the same data-free shell as /activity, served without a session; on this path the page polls /api/hub/activity/public with credentials: 'omit'. Source of the twitch.tv/hivecommonsfleet broadcast. Same CSP and cache headers as /activity. See Hub Fleet activity page |
pkg/hub/activity_public.go |
GET |
/activity/assets/{name} |
Public | The shared tracker assets the Fleet activity page loads, byte-identical: the row asset (pkg/webassets/trackerrow, #16062) and the am.* URL-view and display-playlist helpers (pkg/webassets/trackerview, #16064); only names in trackerrow.Files or trackerview.Files, else 404. Cache-Control: no-cache + content ETag |
pkg/hub/activity_page.go |
POST |
/api/shared-agent-pool/leases |
Hub handler-specific | Acquire or renew a shared CLI session lease | pkg/hub/server.go:1746 |
PUT |
/api/shared-agent-pool/leases |
Hub handler-specific | Renew an active shared CLI session lease | pkg/hub/server.go:1747 |
DELETE |
/api/shared-agent-pool/leases |
Hub handler-specific | Release a shared CLI session lease | pkg/hub/server.go:1748 |
POST |
/api/heartbeat |
Hub handler-specific | Heartbeat. A request carrying X-Hive-Activity-Update is an activity-only update (#15963): body {"activity_update":{"hive_id","activity"}}, the same per-hive bearer, accepted only for a hive already in the registry (404 otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries ok, activity_etag and activity_events_ack (the highest activity event sequence number the hub holds for the hive, #15964; full heartbeat responses carry it too) |
pkg/hub/server.go:1749 |
POST |
/api/task-status |
Hub handler-specific | Task Status | pkg/hub/server.go:1750 |
GET |
/api/registry |
Hub handler-specific | Registry | pkg/hub/server.go:1761 |
GET |
/api/hub/leaderboard |
Hub handler-specific | Leaderboard | pkg/hub/server.go:1762 |
GET |
/api/hub/stats |
Hub handler-specific | Stats | pkg/hub/server.go:1763 |
GET |
/api/fleet-stats |
Hub handler-specific | Fleet Stats | pkg/hub/server.go:1764 |
GET |
/api/hub/evidence |
Hub admin | Read-only cross-hive evidence drill-down from each spoke's stored heartbeat evidence summary (#12116); non-admins get 403. Returns spokes, reporting, pooled calibration (bucket 0–5 → {n, bad, rate, lo, hi}; the hub view folds the six buckets into four reviewer-confidence ranges), findings[] (the plain-language What this says sentences, generated from the same fields; #12456), by_acmm_level (level, hives, merged_90d, revert_rate, and time_to_merge — median_of_hive_medians_s, hives, n — the median of the level's per-hive median time-to-merge, omitted when no hive at the level reports one; #12464), family_false_approve_rate (same/cross/mixed, hives classed by their reviewer vs author family sets), fleet record_coverage (merged PRs with an evidence record over prs_merged_90d), fleet panels (#12370) outcomes_by_author_kind[] (kind, hives, n, merged, reverted, merge_rate, revert_rate), write_counters[] (tier, hives, attempted, blocked, block_rate) and shadow_gate (review_gate / intent → held / passed outcomes with revert_rate), each omitted while no spoke reports it and repeated per by_acmm_level[] row, and per hive hives[] with acmm_level, prs_merged_90d, record_coverage, family_mix, false-approve / false-block / revert rates, families, a calibration series the raw counts behind them (including by_author_kind) so the drill-down can re-pool a hive / ACMM-level selection client-side, and criteria[]: the per-axis criteria table derived hub-side from the quadrant criteria (axis, label, scored, criteria[] with name, label, status met/unmet/not_reported, display/score when measured, reason otherwise; offline, evidence-less or unscored hives are not_reported, never unmet; #12463). Every rate is {n, rate, lo, hi} with a 95% Wilson interval; rate/lo/hi are null when n < 10. Window selection (RFC #12062): `?hours=24 |
168 |
GET |
/api/hub/evidence/report |
Hub admin | Plain-language report of the hub evidence view (#12456), rendered server-side from the same EvidenceView as /api/hub/evidence so every figure reconciles with the modal; non-admins get 403. Same hours= / from= / to= window and hive= / level= filter parameters. format=md (default, text/markdown) or format=html (standalone page, inline CSS, no scripts or external assets, hive names escaped); any other value → 400. download=1 sets `Content-Disposition: attachment; filename="hive-evidence-<hive |
fleet>--.md |
GET |
/api/hub/activity |
Signed-in user | Read-only hub-wide activity view (#15951, RFC #15861) merged from each spoke's heartbeat activity digest, held in hub memory only. Authorization is per user and per hive before aggregation: hub admins see every registered hive; everyone else only hives they own or hold an unexpired grant for; anonymous → 401. Returns hives[] (hive_id, name, status ok/stale/not_reporting/missing, reporting, stale once the block is older than two heartbeats, last_heartbeat, received_at, generated_at, totals — items, by_stage, by_modifier, counting private and truncated items too — truncated and events_dropped), items[] (hive_id, repo, n, kind, title, author_kind, stage, stage_n, since, mods, private) ordered needs-human/needs-decision, stalled, furthest stage, oldest, a response-level truncated (cap 2000), and events[] (#15964: hive_id, received_at, seq, type opened/stage/merged, repo, n, kind, title, from, stage, at, private), oldest first, from a fleet-wide in-memory ring of at most 1,000 events, none held longer than 24 hours (ageing out is not counted in events_dropped; when full, the oldest event of the hive holding the most events is dropped, counted in that hive's events_dropped, so one hive cannot evict the others' events). Events are filtered per user and per hive exactly like items, before aggregation, so an event for a hive the viewer cannot see is never delivered; mod/author_kind filters keep only events whose item is still on the hive's board. A spoke block carries at most 200 events; drops are disclosed per hive as events_dropped. New events change the ETag. Each digest carries at most 100 items by default and never more than the 250-item hub ceiling; private-repository items appear only when the spoke opts in. Filters: hive, repo, stage, mod, author_kind, q (title substring or #<n>), each ≤ 200 characters (else 400). ETag + If-None-Match → 304; Cache-Control: private, no-cache, Vary: Cookie, Authorization. No actions |
pkg/hub/activity.go |
GET |
/api/hub/activity/public |
Public | Public-safe activity view (#15966): the /api/hub/activity shape for anyone, never reading a cookie, token or Authorization header (credentials do not change the response). Only hives the registry lists as public on github.com, and only items and events not marked private; totals, per-hive truncated and events_dropped, hive owners and per-user grants are omitted. Same filters (400 on an invalid one). The body is built at most once per 2 s per parsed filter and shared by every anonymous caller, so rows, generated_at and the ETag change at most every 2 s; query strings that parse to the default view share one entry. Toggling a hive's visibility drops the cache at once. ETag + If-None-Match → 304; Cache-Control: no-cache |
pkg/hub/activity_public.go |
GET |
/api/hub/version |
Hub handler-specific | Hub Version | pkg/hub/server.go:1772 |
DELETE |
/api/hub/registry/{id} |
Hub handler-specific | Registry Delete | pkg/hub/server.go:1782 |
GET |
/api/hub/selfservice/status |
Hub auth | Self-service registration status: {enabled, max_per_user, count, expiry}; always answers so the dashboard can decide whether Register your own hive opens the form or the self-hosting guide (#18060) |
pkg/hub/server.go:1786 |
GET |
/api/hub/selfservice/hives |
Hub auth | The caller's own self-service (byo-) hives: {hives[]} of {id, owner, org, repos, dashboard_url, created_at, ownership_checked_at, last_accepted_heartbeat_at, online}; never a key or a hash. 404 while HIVE_HUB_SELFSERVICE_REGISTRATION is off |
pkg/hub/server.go:1787 |
POST |
/api/hub/selfservice/hives |
Hub auth | Register a self-hosted hive: body {name, org, repos[], dashboard_url}; the ID is byo-<github login>--<name> (the double hyphen keeps IDs unambiguous, since logins contain hyphens but never --). Proves permissions.admin on every owner/name repo with the caller's own stored GitHub token (403 naming the refused repo, nothing stored); 400 invalid or reserved name, a login that contains -- or starts or ends with -, bare-org or ./.. repo, or non-https/private dashboard_url; 409 ID already registered; 429 over HIVE_HUB_SELFSERVICE_MAX_PER_USER (enforced again under the store lock, so concurrent registrations cannot exceed it). 201 {hive, key, hub_url, snippets{docker_compose, podman, kubernetes}}: the raw key appears here once and only its hash is stored. 404 while the flag is off |
pkg/hub/server.go:1788 |
POST |
/api/hub/selfservice/hives/{id}/rotate |
Hub auth | Owner only: mint a new heartbeat key for {id}; the previous key keeps authenticating for overlap (10 minutes). 200 {id, key, hub_url, overlap, snippets}, raw key once. Another user's hive, a missing hive and a hub admin who does not own it all get 404 |
pkg/hub/server.go:1789 |
DELETE |
/api/hub/selfservice/hives/{id} |
Hub auth | Owner or hub admin: revoke the key and remove the registry entry. 200 {removed, id}; another user's hive is 404 |
pkg/hub/server.go:1790 |
POST |
/api/contribute/register |
Hub handler-specific | Contribute Proxy | pkg/hub/server.go:1791 |
GET |
/api/contribute/status |
Hub handler-specific | Contribute Status | pkg/hub/server.go:1792 |
GET |
/api/contribute/ws |
Hub handler-specific | Contribute WSProxy | pkg/hub/server.go:1793 |
POST |
/api/github/webhook |
Hub handler-specific | GitHub Webhook | pkg/hub/server.go:1794 |
GET |
/api/mail/hosts |
hive-mx bearer (HIVE_HUB_MAIL_TOKEN) |
Hosts the mail receiver accepts hive@<host> for (#18395): {hosts[]}, sorted, lower-case: every hosted hive's subdomain host, vanity URL host and reported dashboard URL host. A host claimed by two hives is left out. 401 bad token, 404 while HIVE_HUB_MAIL_TOKEN is unset. Cache-Control: no-store |
pkg/hub/mail_relay.go |
POST |
/api/mail/inbound |
hive-mx bearer (HIVE_HUB_MAIL_TOKEN) |
One parsed mail delivery from hive-mx (pkg/mailin/wire.Delivery): JSON, or multipart/form-data for a large files delivery, routed by the X-Hive-Mail-Delivery, X-Hive-Mail-Kind and X-Hive-Mail-Recipient headers (at most 48 MiB, HIVE_HUB_MAIL_MAX_BODY_BYTES, this route only; without the headers, JSON of at most 8 MiB). The body is spooled to disk, never held whole in memory. The hub matches the recipient host to a hosted hive, signs the body byte for byte with that hive's relay key (X-Hive-Relay-Timestamp, X-Hive-Relay-Signature-256 bound to X-Hive-Relay-Delivery) and forwards it to the spoke's /api/meetings/invites, /api/inbox/email or /api/meetings/calendar-emails/proof by kind, behind the webhook relay's private-address guard and without following redirects. A files delivery that is multipart or larger than one piece (HIVE_HUB_MAIL_CHUNK_BYTES, 768 KiB) goes to /api/inbox/email/chunk in signed pieces instead (#18564). Stores nothing once relayed; logs the delivery id only. 202 delivered; 400 invalid delivery; 404 no such hive; 413 too large; 422 the spoke refused it (permanent); 502/503 hive not reachable yet or unavailable (hive-mx asks the sender to retry) |
pkg/hub/mail_relay.go |
GET |
/gh-setup |
Hub handler-specific | GitHub App Setup Router | pkg/hub/server.go:1797 |
GET |
/learn |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1798 |
GET |
/get-started |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1799 |
GET |
/api/docs |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1802 |
GET |
/api/reading-list |
Hub handler-specific | Reading List | pkg/hub/server.go:1805 |
GET |
/reading |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1806 |
GET |
/cncf-reference-architecture |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1813 |
GET |
/cncf-reference-architecture/console |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1814 |
GET |
/cncf-reference-architecture/bluefin |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1815 |
GET |
/{$} |
Hub handler-specific | Static HTML page | pkg/hub/server.go:1832 |
GET |
/og-card.png |
Hub handler-specific | OGCard | pkg/hub/server.go:1837 |
GET |
/ |
Public | Static asset fallback (http.FileServerFS over the embedded static/ tree) for any path no other route claims |
pkg/hub/server.go:1839 |
GET |
/api/marketplace/workflows |
Public | Workflow-model marketplace index (#17620 phase 7): {generatedAt, entries:[{name, version, hash, tier, description, source, states, columns, publishedAt, publishedBy, sourceSHA?, newerIngestAvailable, adoption:{}, ratings:{}, benchmarks:{}}]}. Strong ETag (sha256 of the body) + Cache-Control: no-cache; If-None-Match → 304. Tiers: built-in, curated, ingested-unreviewed, local-published. 404 when HIVE_HUB_MARKETPLACE_DISABLED is set |
pkg/hub/marketplace.go:36 |
GET |
/api/marketplace/workflows/{name}/{version}/bundle |
Public | One immutable signed bundle ({apiVersion, model, profile, hash, createdAt, createdBy, tier}), Cache-Control: immutable; 404 unknown, 400 malformed key |
pkg/hub/marketplace.go:37 |
POST |
/api/marketplace/workflows |
Spoke heartbeat bearer + X-Hive-ID, or Hub admin session |
Publish a bundle. Body = bundle (≤ 4 MiB); the hub re-verifies the hash and recompiles the model before storing. Publisher may assert tier local/local-published (normalised to local-published) or ingested-unreviewed; curated/built-in require a hub admin session (403 otherwise). 201 {published, created:true, entry}; identical republish 200 created:false; different content under an existing name@version 409; verification failure 422; unknown hive 403; no hub secret 503 |
pkg/hub/marketplace.go:38 |
POST |
/api/marketplace/refresh |
Spoke heartbeat bearer + X-Hive-ID, or Hub admin session |
On-demand ingest of the CNCF corpus (+ HIVE_HUB_MARKETPLACE_EXTRA_REPOS). Without ?repo= starts a background run → 202 {accepted, repos} (409 when one is already running); ?repo=owner/name runs that repository synchronously → 200 {accepted, repo, result}. Spokes are rate-limited across all hives (one full run per hour, 10 ?repo= runs per minute) → 429 + Retry-After; admins are not. 401 anonymous, 403 non-admin session or unknown hive |
pkg/hub/marketplace.go:39 |
GET |
/api/marketplace/status |
Public; ?verbose=1 requires spoke heartbeat bearer + X-Hive-ID or Hub admin session |
{entries, byTier, etag, generatedAt, corpusRepos, trackedRepos, failingRepos, failing:[{repo, error, checkedAt}], pendingRepos, lastRefreshErrors, refreshing, schedule, lastRefresh, lastCheckedAt} — last refresh summary (persisted across restarts), counts by tier and the failing repos with their fetch errors (no secrets). ?verbose=1 adds pending:[repo] (corpus repos never ingested) |
pkg/hub/marketplace.go:40 |