Compose a PRView SourceOpen Issue

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 — Health, status, events

Contributor pool counters

GET /api/status includes contributorPool.abandoned, the sum of persisted abandoned-PR counters across all registered profiles, and contributorPool.abandoned_by_login, an object keyed by lowercase GitHub login. Offline and revoked contributors remain included; zero-count logins are present. An empty registry returns abandoned: 0 and abandoned_by_login: {}. These are historical adoption counts, not failed tasks or disconnected task runs. GET /api/contributors provides each profile’s abandoned and abandoned_prs records (repo, pr, adopted_into_pr, reason, at). The Contributors tile shows a nonzero count with the five most recent records in its tooltip. See Abandoned contributor PRs for counting semantics.

Endpoints

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/versionDashboard auth/sessionBuild/version metadata; includes upgradeMarker (target, current, attempts, maxAttempts, failed, requestedAt, lastError) while a self-upgrade is in flight or has failed (#6765), the hub-delivered upgradePolicy (hub_managed, spoke_managed, schedule, schedule_hour, schedule_timezone, schedule_weekday, paused, branch, channel, target_sha, target_resolved, armed_target, and next_update_at — the hub’s RFC3339 ETA for the next promotion into the stable channel, omitted when unknown (#10256)) when available, and an autoUpdate object (enabled, state — one of disabled/up_to_date/behind/retrying/failed/unknown — healthy, period, targetBranch, targetCommit, currentCommit, commitsBehind, lastAttemptAt, lastError, detail, and nextUpdateAt — the hub’s RFC3339 ETA for the next update, omitted when unknown, disabled or paused (#10257)) that never reports a failed or unknown update as healthy (#6962, #6963). Also startedAt (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say “Restarted” vs “Upgraded”) and, until the first status is published, startupPhase/startupPhaseLabel (the boot phase a fresh pod is in) (#15788)pkg/dashboard/api.go:45
GET/api/version/release-notesDashboard auth/sessionChangelog gap between two revisions: ?from=<sha>&to=<channel-branch-tag-or-sha> returns {from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?} — the CHANGELOG.md release sections present at to and absent at from, newest first, plus (when to is not a release tag) the changelog.d/ fragments new at to under an Unreleased (in this build) section. Fetch failures return source: "unavailable" with error rather than an error status; results are cached per (from, to) for an hour (#11065)pkg/dashboard/api.go:46
POST/api/release-channelOwner onlyHosted spoke self-service release-channel selector; relays stable/candidate/edge to the hub’s existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image landspkg/dashboard/api.go:70
GET/api/healthPublicBasic health probepkg/dashboard/server.go:1745
GET/api/health/deepPublicDeep health probepkg/dashboard/server.go:1746
GET/api/livezPublicKubernetes liveness probepkg/dashboard/server.go:1747
GET/metricsRegistered only when HIVE_METRICS_ENABLED; requires `Authorization: ****** (403 if the token is unset)Prometheus metricspkg/dashboard/server.go:1753
GET/api/statusDashboard auth/sessionDashboard aggregate status; labelPresets[] (\{key,label,description,labels[],states[]\}) lists the built-in label-filter presets for the Projects cards, led by needs-human whose labels[] are the effective hard-suppress labels plus needs-signal, the hold labels, stage/071-needs-author and the reporter-trust awaiting label (#12172); accepts ?fields=a,b for top-level selection and ?omit=repos to drop heavy sections, and honors Accept-Encoding: gzip; agents[] includes busy-pane visibility fields (kicksUndeliverable, busySince, lastTranscriptActivity, condition, conditionMessage) when a Working pane cannot accept kicks; a working agent also carries agents[].run — the live per-run line (#14576): \{since, elapsedS, costUSD, tokens, priced, tests, filesChanged\}, the estimated spend/tokens since the kick was delivered (lastKickAt, falling back to busySince) (delta of the token collector’s per-agent cumulative figure; priced:false when the agent has none yet), the last visible test-runner result (pass/fail/empty) and the last N files changed git summary (-1 when none) parsed from the captured pane; top-level fleetRun \{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced\} is the governor strip’s rotating running N · $X this hour / today / this week / this month figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger’s last snapshot, windowsPriced:false when there is no ledger yet; sla (fleet) and repos[].sla (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: windows.\{7d,30d\}.\{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge\} as \{p50_h,p95_h,n\} (hours, nearest-rank), history[] of up to 30 daily buckets \{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged\} persisted under /data/sla-history.json, stale_in_progress[] (\{number,repo,started_at,age_h,agent\} — issues carrying hive/in-progress longer than the agent claim TTL with no linked PR), stale_count, merged_7d, claim_ttl_s and, on the fleet block, the effective targets (start_to_pr_h, pr_to_merge_h, open_to_merge_h); staleSince and repos[].countsStale / countsStaleSince mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache’s last-good counts (#13376); ci_failure_signals \{count, last, kicks, unmatched\} is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one \{repo, number, head_sha, check, conclusion, details_url, agent, at\}, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; workflow_approvals \{approved, denied, permission_errors, last\} counts the hive’s approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), 403/404 refusals for want of actions: write, and the most recent decision \{repo, number, head, run_id, outcome, at\}; hotspots \{count, actionable, filed\} is the merge-hotspot advisor’s one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on GET /api/hotspots; writeback.dedupe \{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s\} is the write-back gate’s content layer — the effective writeback.dedupe.* settings and the last-hour counts of writes held as duplicate, burst and rate-capped (each also listed under GET /api/writeback/suppressed); referenceRepos[] \{full, tier, reference_tier\} lists project.reference_repos apart from repos[] — reference_tier is read-only, issues, prs or issues+prs (tier is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); config.gate_regressions[] \{gate, previous, effective, source\} is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (review.require_labels, project.issue_filter.require_labels, project.paused_repos[<repo>], writeback.per_repo[<repo>].mode), empty on a healthy bootpkg/dashboard/server.go:1758
GET/api/status/summaryDashboard auth/sessionCompact agent/governor/budget status summary for pollers; honors Accept-Encoding: gzippkg/dashboard/server.go:1759
GET/api/overview/issues.csvDashboard auth/sessionCached Overview issue-band export as browser-compatible CSV; filters band, repo/repos, stale, and held are ANDed.pkg/dashboard/server.go:1760
GET/api/overview/issues.jsonDashboard auth/sessionCached Overview issue-band export as typed JSON with bands[] metadata and row fields matching the CSV columns.pkg/dashboard/server.go:1761
GET/api/overview/prs.csvDashboard auth/sessionCached Overview PR-band export as browser-compatible CSV; filters band, repo/repos, stale, and held are ANDed.pkg/dashboard/server.go:1762
GET/api/overview/prs.jsonDashboard auth/sessionCached Overview PR-band export as typed JSON with bands[] metadata and row fields matching the CSV columns.pkg/dashboard/server.go:1763
GET/api/eventsDashboard auth/sessionServer-sent event streampkg/dashboard/server.go:1764
GET/api/swarmDashboard auth/sessionCurrent swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields.pkg/dashboard/swarm.go:310
POST/api/swarmOwner onlyStart a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body \{"repo":"owner/name","force":true\} is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured.pkg/dashboard/swarm.go:311
DELETE/api/swarmOwner onlyEnd the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured.pkg/dashboard/swarm.go:312
GET/api/swarm/historyDashboard auth/sessionCompleted swarm history, aggregate repo leaderboard, and top player records.pkg/dashboard/swarm.go:313
GET/api/swarm/playersDashboard auth/sessionPer-player swarm records and earned achievement catalog.pkg/dashboard/swarm.go:314
GET/api/swarm/themesDashboard auth/sessionDefault and per-repo swarm theme configuration.pkg/dashboard/swarm.go:315
PUT/api/swarm/themesOwner onlySet a per-repo swarm theme (event_name, call_to_arms, leaderboard_title).pkg/dashboard/swarm.go:316
PATCH/api/swarm/objectivesOwner onlyUpdate the active swarm SDLC objective checklist completion state.pkg/dashboard/swarm.go:317
GET/api/leaderboard/swarmPublicStable public JSON record of swarm history, leaderboard, top players, and achievements.pkg/dashboard/swarm.go:318
GET/api/runsDashboard auth/sessionActive staged runs projected from task leases, plans, and lifecycle timeline. Returns an array of Run objects: canonical key (owner/repo#number), current-stage lease_key, title, repo (owner/repo), stage, gen, stage_started_at, waiting_on (agent, remote, human, ci, none), waiting_since, assignee, last_receipt, plan_epic_id, and stages[] (name, status, gen, receipt).pkg/dashboard/api.go:91
GET/api/runs/auditOwner onlyRead-only cross-repo audit query over existing retained artifacts. Query repo, canonical run (owner/repo#number), RFC3339 since/until, kind, limit (default 100, max 500), and page_token. Returns \{items,next_page_token,retention\}; each item has source (audit_log, timeline, lease_receipt, plan_epic), kind, run, repo, at, actor, artifact_id, attrs, or an explicit kind=expired,status=expired,state=Unknown marker when requested history may have aged out.pkg/dashboard/api.go:92
POST/api/runs/auditOwner onlyActivate the convergence audit campaign over a scope directory. Body \{"campaign_key":"audit-campaign","scope_dir":"/data/convergence/audit/scope","store":"audit","generation":1,"run_key":"","run_url":""\}; scope_dir defaults to /data/convergence/audit/scope, store defaults to audit, auditor, scanner, supervisor, then the first configured bead store. Runs inspection even when publication.enabled is false, but then skips the publisher and returns publication_skipped:true with reason publication.disabled.pkg/dashboard/api.go:93
GET/api/runs/\{key\}/checkpointDashboard auth/sessionCompact mobile/chat checkpoint review payload for a held run. Returns run_key, stage, lease gen, repo, title, capped plain-text summary, approve/reject decisions, dashboard deep link, lease_gen staleness fence, and verified-owner approver rule.pkg/dashboard/api.go:95
POST/api/runs/\{key\}/checkpointOwner onlyResolve a compact checkpoint decision. Body `{“action”:“approve”“reject”,“gen”:<lease generation>}`; refuses stale generations with 409 and non-owner callers with 403 before mutating the plan.
GET/api/runs/\{key\}Dashboard auth/sessionOne run by URL-escaped canonical run key (owner/repo%23number); early lease-shaped keys (repo!run-key:stage) and queued Wavefront run-stage keys (owner/repo!graph:node) are also accepted. Includes timeline-derived stage history in the same Run shape as /api/runs when a lease/timeline exists. History entries that came from an owner reset carry the owner’s reason. When the key belongs to a wired convergence campaign, the detail response also includes an optional burndown block with source, satisfied, remaining, unknown, and scope; the list endpoint omits this block.pkg/dashboard/api.go:97
POST/api/runs/\{key\}/resetOwner onlyMove a run’s lease back to an earlier stage (for example implement to plan after a rejected plan). Body \{"to": "<stage>", "reason": "<why>"\}, both required. Mints a new generation so the relay holding the old one can no longer resume, persists before answering, and records the reason on the agent audit sink, the lifecycle timeline, and the stage_completed hook payload (attrs.reset = "true"). Returns \{ok, key, stage_from, stage, gen, reason\}. 400 for the same or a later stage or a missing reason, 404 when no live staged lease holds the key, 409 when the lease expired, 500 when the registry could not be written.pkg/dashboard/api.go:98
GET/api/campaignsDashboard auth/sessionList resumable campaigns from archived Inception sessions and retained Spektacular (Spek) runs. Query search/q, repo, stage, status, and owner; each campaign is keyed by stable spec/session id and includes title, source, repos, current stage/step, artifact links, linked issues/PRs, contributors, last activity, status, engine, type, run link when applicable, superseded_by when a newer Revise revision exists, and recheck status (enabled, interval, last_at, next_at, in_flight, last_delta_count, external_count, sources_failed).pkg/dashboard/api.go:99
GET/api/campaigns/\{id\}Dashboard auth/sessionReturn one campaign by URL-escaped stable campaign id or run key, using the same campaign shape as /api/campaigns; recheck revisions may include a drift block with codebase_changed, prior_revision, delta_count, recheck_reason, external[] (source, kind, title, url, published_at, summary), external_count, and sources_failed.pkg/dashboard/api.go:100
POST/api/campaigns/\{id\}/resumeOwner onlyResume or pick up a campaign. Archived Inception campaigns take a durable campaign lease, restore their saved state and wiki working files; Spek campaigns return the retained run detail plus a CLI status command that reloads state from Spek artifacts. Body may include `{ “surface”: “chat”“contributor”
POST/api/campaigns/\{id\}/releaseOwner onlyRelease the caller’s Inception campaign lease and write a campaign_release audit entry so another user can continue it. Run-backed Spektacular campaigns return 409 Conflict; this endpoint never revokes their run-lifecycle stage leases.pkg/dashboard/api.go:102
POST/api/campaigns/\{id\}/reviseOwner onlyCreate a linked revision campaign (revision_of, revision) for revisiting shipped or parked Inception/Spek work without overwriting the previous campaign. The new revision is leased to the caller and audit-logged as campaign_revise.pkg/dashboard/api.go:103
DELETE/api/campaigns/\{id\}Owner onlyDelete a campaign record: removes the archived Inception state and wiki snapshot for the stable campaign id and audit-logs campaign_delete. Knowledge-base facts, Jam threads, scaffolded repo files and other revisions in the same chain are kept; deleting the live L1 session clears it. Run-backed Spektacular campaigns return 409 Conflict; unknown ids 404.pkg/dashboard/api.go:104
POST/api/campaigns/\{id\}/recheckOwner onlyCreate an immediate linked Spek recheck revision using the cadence path. Returns 409 Conflict when a recheck revision is already in flight, 404 Not Found when recheck is disabled unless ?force=true is supplied, and records campaign_recheck.pkg/dashboard/api.go:105
GET/api/campaigns/\{id\}/jamDashboard auth/sessionReturn the per-campaign Jam workspace: section-anchored threads, comments, suggestions, polls, poll decisions, current spec revision and attributed revision history.pkg/dashboard/api.go:106
POST/api/campaigns/\{id\}/jamRead-write roleRecord an attributed spec revision for a campaign. Body includes spec_content, optional reason, and optional agent/model attribution fields.pkg/dashboard/api.go:107
GET/api/campaigns/\{id\}/jam/threadsDashboard auth/sessionList async Jam threads anchored to spec sections, including comments and author attribution.pkg/dashboard/api.go:108
POST/api/campaigns/\{id\}/jam/threadsRead-write roleCreate a section-anchored Jam thread or add a comment to an existing thread. Body includes section and body, or thread_id and body.pkg/dashboard/api.go:109
POST/api/campaigns/\{id\}/jam/agentsMaintainer onlyInvite Spektacular or a configured hive agent into a Jam thread. The agent reply is posted as an attributed thread comment and an open suggestion for human accept/reject; no spec revision is auto-applied.pkg/dashboard/api.go:110
GET/api/campaigns/\{id\}/jam/suggestionsDashboard auth/sessionList Jam suggestions with open/accepted/rejected status, proposed text, attribution and applied revision id when accepted.pkg/dashboard/api.go:111
POST/api/campaigns/\{id\}/jam/suggestionsRead-write role; maintainer for acceptCreate a suggestion (section, proposed_text) or resolve it with action: "accept"/"reject" and suggestion_id. Accepting records a new attributed spec revision.pkg/dashboard/api.go:112
GET/api/campaigns/\{id\}/jam/pollsDashboard auth/sessionList Jam polls, advisory vote tallies and maintainer decisions stored against spec revisions.pkg/dashboard/api.go:113
POST/api/campaigns/\{id\}/jam/pollsRead-write role; maintainer for decideCreate polls (section, question, options), cast/update advisory votes (action: "vote"), or record a maintainer decision with rationale (action: "decide").pkg/dashboard/api.go:114
GET/api/campaigns/\{id\}/jam/project-syncDashboard auth/sessionReturn the campaign’s GitHub Projects sync configuration, last published items, last status, and retry guidance for failures.pkg/dashboard/api.go:115
POST/api/campaigns/\{id\}/jam/project-syncMaintainer onlyEnable/disable opt-in GitHub Projects sync, publish campaign specs/decisions/derived issues to the linked project, or record inbound project status updates without losing local Jam decisions.pkg/dashboard/api.go:116
GET/api/campaigns/\{id\}/jam/wsDashboard auth/sessionUpgrade to a Jam WebSocket for live participant presence, section focus, and conflict-aware spec co-edit messages. Live edits require read-write role and stale base_revision_id values are rejected with a conflict message.pkg/dashboard/api.go:117
GET/api/runs/\{key\}/traceDashboard auth/sessionResolve Hive-Run, Hive-Plan, and Hive-Spec commit trailers for ?sha=..., returning the linked plan section, spek clause, approval audit record, rationale audit entries, and typed no-linkage results when trailers are missing.pkg/dashboard/api.go:94