Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Dashboard REST API reference — Hub SaaS

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.

MethodPathAuthPurposeSource
GET/api/saas/my-hivesHub authMy Hives. Each row carries quadrant and the payload carries fleet_quadrant (#12458): axes[] of {axis, score, scored, reason?, delta, nudge?, criteria[], measured, unmeasured, summary?, n?} where each criteria[] entry is {name, label, measured, value, display?, score, weight, how, good, reason?, n?}; every criterion maps to 0–100 on a fixed named curve, an axis is the weighted mean of its measured criteria only (an unmeasured criterion is listed with reason and excluded, never scored 0), composite averages the scored axes, and fleet_quadrant is the per-axis median across hives in view (aggregate: "median", n hives) with each criterion’s median value. delta is the hive minus the fleet median. Shape is additive over the earlier axes[]{axis,score,scored,reason,delta,nudge}/composite/scored_axes payload. See Fleet quadrantpkg/hub/saas.go:363, pkg/hub/quadrant.go
GET/api/hub/widgetHub authiPhone fleet widget (#12148): every hive the caller can see (hub admins: all; others: hives they own or hold a role on; pool placeholders excluded), sorted by act_issues + act_prs descending. Per hive id, project, url, online, acmm_level, issues, prs (all open, from the heartbeat; 0 from spokes that do not report them), act_issues, act_prs, agents_running, agents_total, last_heartbeat; totals (hives, online, need_you, the same counts summed) and history (fleet act_issues/act_prs per 15-minute bucket, t in Unix seconds, at most 48 points). See iOS widgetpkg/hub/saas.go:364
GET/api/saas/usageHub authUsagepkg/hub/saas.go:373
POST/api/saas/hivesHub authCreate Hivepkg/hub/saas.go:383
GET/api/saas/hives/{id}/statusHub authHive Statuspkg/hub/saas.go:384
POST/api/saas/hives/{id}/pin-digestHub auth (owner or admin)Pin Digest - hold the spoke at an immutable image digest ({"digest":"sha256:..."} or {"sha":"<short git SHA>"}, optional reason)pkg/hub/digest_pin.go
POST/api/saas/hives/{id}/unpin-digestHub auth (owner or admin)Unpin Digest - lift the pin and return to the tracked channel or branch tagpkg/hub/digest_pin.go
GET/api/saas/hives/{id}/digest-pinHub auth (owner or admin)Digest Pin - the pin with provenance and whether the spoke reports running itpkg/hub/digest_pin.go
GET/api/saas/hives/{id}/openHub handler-specificOpen Hivepkg/hub/saas.go:389
DELETE/api/saas/hives/{id}Hub auth (owner or admin)Delete Hivepkg/hub/saas.go:390
POST/api/saas/hives/{id}/upgradeHub authUpgrade Hive - arms heartbeat delivery (200 {"status":"upgrading"}); a spoke already at its reachable target is a no-op 200 {"status":"current","current","target","channel","message"}, not an errorpkg/hub/saas.go:391
POST/api/saas/hives/{id}/switch-branchHub authSwitch Branchpkg/hub/saas.go:392
PUT/api/saas/hives/{id}/visibilityHub authToggle Visibilitypkg/hub/saas.go:399
PUT/api/saas/hives/{id}/auto-upgradeHub authToggle Auto Upgradepkg/hub/saas.go:400
PUT/api/saas/hives/{id}/nameHub authRename Hivepkg/hub/saas.go:404
POST/api/saas/hives/{id}/forgeHub authSwitch Forgepkg/hub/saas.go:409
POST/api/saas/hives/{id}/reset-appHub authReset Apppkg/hub/saas.go:410
POST/api/saas/hives/{id}/restart-spokeHub authRestart Spokepkg/hub/saas.go:415
POST/api/saas/hives/{id}/breakerHub authPause / Resume Hive (fleet breaker)pkg/hub/saas.go:418
GET/api/saas/hive-config/{hiveID}Hub authProxy Hive Configpkg/hub/saas.go:419
GET/api/saas/latest-shaHub handler-specificLatest SHApkg/hub/saas.go:420
GET/api/hub/release/stable-promotionPublicStable Promotion Statepkg/hub/saas.go:422
POST/api/saas/hub/upgradeHub handler-specificHub Self Upgradepkg/hub/saas.go:423
PUT/api/saas/hub/auto-upgradeHub handler-specificHub Auto Upgradepkg/hub/saas.go:424
PUT/api/hub/release/stable-promotionHub adminStable Promotion Toggle (audit-logged)pkg/hub/saas.go:425
GET/api/saas/auth-checkHub handler-specificSaa SAuth Checkpkg/hub/saas.go:430
POST/api/saas/user-tokenHub authUser Tokenpkg/hub/saas.go:441
GET/api/saas/hives/{id}/accessHub authAccess Listpkg/hub/saas.go:442
GET/api/saas/grantable-usersHub authGrantable Userspkg/hub/saas.go:443
POST/api/saas/hives/{id}/accessHub authAccess Addpkg/hub/saas.go:444
DELETE/api/saas/hives/{id}/access/{username}Hub authAccess Removepkg/hub/saas.go:445
POST/api/saas/hives/{id}/request-accessHub authRequest Accesspkg/hub/saas.go:446
GET/api/saas/hives/{id}/requestsHub authGet Requestspkg/hub/saas.go:447
GET/api/saas/hives/{id}/timelineHub authHive Timelinepkg/hub/saas.go:448
POST/api/saas/hives/{id}/requests/{username}/approveHub authApprove Requestpkg/hub/saas.go:450
POST/api/saas/hives/{id}/requests/{username}/denyHub authDeny Requestpkg/hub/saas.go:451
PUT/api/saas/hives/{id}/approve-access/{username}Hub authApprove Accesspkg/hub/saas.go:452
DELETE/api/saas/hives/{id}/deny-access/{username}Hub authDeny Accesspkg/hub/saas.go:453
GET/api/saas/access-statusHub handler-specificAccess Statuspkg/hub/saas.go:454
POST/api/saas/request-provisionHub authRequest Provisionpkg/hub/saas.go:462
PUT/api/saas/approve-provision/{username}Hub handler-specificApprove Provisionpkg/hub/saas.go:463
DELETE/api/saas/deny-provision/{username}Hub handler-specificDeny Provisionpkg/hub/saas.go:464
GET/api/saas/admin/available-placeholdersHub handler-specificAvailable Placeholderspkg/hub/saas.go:465
GET/api/saas/admin/usersHub handler-specificAdmin Userspkg/hub/saas.go:468

GET /api/saas/admin/users includes cached affiliation, affiliation_source, profile_bio, profile_location, public_activity, top_repo, and top_repo_url fields for the Hub Admin — Users AFFILIATION column. The cache identifies who a signup appears affiliated with from public GitHub/GHE footprint only, ranked as profile company, contributed-to repo owner/org (excluding the personal namespace), public org membership, then top-repo owner/independent fallback; bio/location are supporting tooltip context, and public_activity buckets recent public events as quiet, active, or prolific. Provider API refreshes are asynchronous and daily, so the table never blocks on GitHub/GHE and never requires Hive activity.

| PUT | /api/saas/admin/users/{username} | Hub handler-specific | Admin Update User | pkg/hub/saas.go:491 | | DELETE | /api/saas/admin/users/{username} | Hub handler-specific | Admin Delete User | pkg/hub/saas.go:492 | | POST | /api/saas/admin/impersonate/exit | Hub handler-specific | Impersonate Exit | pkg/hub/saas.go:498 | | POST | /api/saas/admin/impersonate/{username} | Hub handler-specific | Impersonate Start | pkg/hub/saas.go:499 | | GET | /api/saas/impersonation-status | Hub auth | Impersonation Status | pkg/hub/saas.go:500 | | POST | /api/saas/hives/{id}/assign | Hub auth | Assign Hive | pkg/hub/saas.go:501 | | POST | /api/saas/hives/{id}/reset-assignment | Hub handler-specific | Reset Assignment | pkg/hub/saas.go:505 | | GET | /api/saas/cluster-health | Hub handler-specific | Cluster Health | pkg/hub/saas.go:506 | | POST | /api/saas/admin/alert-ack | Hub handler-specific | Alert Ack | pkg/hub/saas.go:519 | | GET | /api/saas/admin/cluster-app-keys | Hub handler-specific | Get Cluster App Keys | pkg/hub/saas.go:523 | | PUT | /api/saas/admin/cluster-app-keys/{clusterID} | Hub handler-specific | Put Cluster App Key | pkg/hub/saas.go:524 | | POST | /api/saas/admin/hub-banner | Hub handler-specific | Send Hub Banner | pkg/hub/saas.go:525 | | DELETE | /api/saas/admin/hub-banner | Hub handler-specific | Clear Hub Banner | pkg/hub/saas.go:526 | | GET | /api/saas/admin/hub-banner | Hub handler-specific | Get Hub Banner | pkg/hub/saas.go:527 | | POST | /api/saas/slack/user/{username} | Hub auth | Slack Message User | pkg/hub/saas.go:534 | | POST | /api/saas/hives/{id}/slack | Hub auth | Slack Message Hive Owner | pkg/hub/saas.go:535 | | POST | /api/saas/admin/slack/broadcast | Hub handler-specific | Slack Broadcast | pkg/hub/saas.go:536 | | POST | /api/saas/admin/journey-snooze | Hub handler-specific | Journey Snooze | pkg/hub/saas.go:537 | | GET | /api/saas/admin/journey-status | Hub handler-specific | Journey Status | pkg/hub/saas.go:538 | | GET | /api/saas/me/country | Hub auth | My Country Get | pkg/hub/saas.go:380 | | PUT | /api/saas/me/country | Hub auth | My Country Set (write blocked while impersonating) | pkg/hub/saas.go:381 | | POST | /api/saas/lite/enroll | Hub auth | Hive Lite Enroll | pkg/hub/saas.go:382 | | PUT | /api/saas/hives/{id}/secondary-app | Hub auth | Assign Secondary GitHub App | pkg/hub/saas.go:414 | | POST | /api/saas/hives/{id}/agents/{agent}/restarts/reset | Hub auth | Reset Agent Restart Counter | pkg/hub/saas.go:405 | | GET | /api/saas/upgrade-pause | Hub admin | Upgrade Kill-Switch State | pkg/hub/saas.go:428 | | POST | /api/saas/upgrade-pause | Hub admin | Upgrade Kill-Switch Toggle (audit-logged) | pkg/hub/saas.go:429 | | GET | /api/saas/whoami | Hub handler-specific | Session Identity (stable key + profile) | pkg/hub/saas.go:436 | | GET | /api/saas/dibs/repos | Hub handler-specific | Dibs Repo/Owner List (public, short shared cache) | pkg/hub/saas.go:440 | | GET | /api/saas/hives/{id}/access-log | Hub auth | Permission-Change Audit Log | pkg/hub/saas.go:449 | | GET | /api/saas/admin/scale-settings | Hub admin | Placeholder Pool Scale Settings Get | pkg/hub/saas.go:466 | | POST | /api/saas/admin/scale-settings | Hub admin | Placeholder Pool Scale Settings Set | pkg/hub/saas.go:467 | | GET | /api/saas/admin/user-countries | Hub admin | User Country Rollup | pkg/hub/saas.go:476 | | GET | /api/saas/admin/auth-rollout | Hub admin | Auth Rollout Readiness Summary | pkg/hub/saas.go:481 | | GET | /api/saas/admin/notifications | Hub admin | Hub Notifications Get | pkg/hub/saas.go:482 | | PUT | /api/saas/admin/notifications | Hub admin | Hub Notifications Update + hot reload | pkg/hub/saas.go:483 | | GET | /api/saas/admin/key-generations | Hub admin | Token-Crypto Key Generations | pkg/hub/saas.go:489 | | POST | /api/saas/admin/rotate-master-key | Hub admin | Rotate Token Master Key (double-call refused) | pkg/hub/saas.go:490 | | GET | /api/saas/admin/advisory-diagnostics | Hub admin | Fleet Advisory/App-State Diagnostics | pkg/hub/saas.go:516 | | POST | /api/saas/hives/bulk | Hub auth | Bulk Hive Action | pkg/hub/saas_bulk.go:89 | | GET | /api/saas/build-contains | Hub auth | Does each hive’s running build contain a PR or commit (#18915): ?q=<PR number or commit SHA> returns {query:{kind,pr?,commit?}, commit?, reason?, hives:[{id,name?,commit?,channel?,contains,reason?}]} for the hives the caller can see in My Hives. contains is yes, no or unknown, computed from the hive’s already-reported commit and repository ancestry: yes when the PR’s merge commit (or the SHA) is the running commit or an ancestor, no when ancestry resolved and it is not (an unmerged PR is no), unknown (with reason) when the commit cannot be resolved or the lookup failed. Never a guess. 400 when q is neither a PR number nor a SHA. See Build visibility | pkg/hub/build_contains.go:225 | | GET | /api/saas/me/country | Hub auth | My Country Get | pkg/hub/saas.go:380 | | PUT | /api/saas/me/country | Hub auth | My Country Set (write blocked while impersonating) | pkg/hub/saas.go:381 | | POST | /api/saas/lite/enroll | Hub auth | Hive Lite Enroll | pkg/hub/saas.go:382 | | PUT | /api/saas/hives/{id}/secondary-app | Hub auth | Assign Secondary GitHub App | pkg/hub/saas.go:414 | | POST | /api/saas/hives/{id}/agents/{agent}/restarts/reset | Hub auth | Reset Agent Restart Counter | pkg/hub/saas.go:405 | | GET | /api/saas/upgrade-pause | Hub admin | Upgrade Kill-Switch State | pkg/hub/saas.go:428 | | POST | /api/saas/upgrade-pause | Hub admin | Upgrade Kill-Switch Toggle (audit-logged) | pkg/hub/saas.go:429 | | GET | /api/saas/whoami | Hub handler-specific | Session Identity (stable key + profile) | pkg/hub/saas.go:436 | | GET | /api/saas/dibs/repos | Hub handler-specific | Dibs Repo/Owner List (public, short shared cache) | pkg/hub/saas.go:440 | | GET | /api/saas/hives/{id}/access-log | Hub auth | Permission-Change Audit Log | pkg/hub/saas.go:449 | | GET | /api/saas/admin/scale-settings | Hub admin | Placeholder Pool Scale Settings Get | pkg/hub/saas.go:466 | | POST | /api/saas/admin/scale-settings | Hub admin | Placeholder Pool Scale Settings Set | pkg/hub/saas.go:467 | | GET | /api/saas/admin/user-countries | Hub admin | User Country Rollup | pkg/hub/saas.go:476 | | GET | /api/saas/admin/auth-rollout | Hub admin | Auth Rollout Readiness Summary | pkg/hub/saas.go:481 | | GET | /api/saas/admin/notifications | Hub admin | Hub Notifications Get | pkg/hub/saas.go:482 | | PUT | /api/saas/admin/notifications | Hub admin | Hub Notifications Update + hot reload | pkg/hub/saas.go:483 | | GET | /api/saas/admin/key-generations | Hub admin | Token-Crypto Key Generations | pkg/hub/saas.go:489 | | POST | /api/saas/admin/rotate-master-key | Hub admin | Rotate Token Master Key (double-call refused) | pkg/hub/saas.go:490 | | GET | /api/saas/admin/advisory-diagnostics | Hub admin | Fleet Advisory/App-State Diagnostics | pkg/hub/saas.go:516 |