Skip to content

Latest commit

 

History

History
85 lines (79 loc) · 22.5 KB

hub-server.md

File metadata and controls

85 lines (79 loc) · 22.5 KB

Dashboard REST API reference — Hub server

Merged contributor leaderboard

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