Skip to content

Latest commit

 

History

History
105 lines (96 loc) · 13.2 KB

contribute.md

File metadata and controls

105 lines (96 loc) · 13.2 KB

Dashboard REST API reference — Contribute

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 /contribute Public Contribute Landing pkg/dashboard/api_contribute.go:227
GET /contribute/{tab} Public Contribute Landing pkg/dashboard/api_contribute.go:233
GET /api/contribute/ws Public s.contribute Hub.Handle WS pkg/dashboard/api_contribute.go:241
POST /api/contribute/register Public Contribute Register pkg/dashboard/api_contribute.go:242
POST /api/contribute/invite Public Contribute Invite pkg/dashboard/api_contribute.go:248
POST /api/contribute/reissue-token Public Contribute Reissue Token pkg/dashboard/api_contribute.go:249
GET /api/contribute/status Public Contribute Status pkg/dashboard/api_contribute.go:251
GET /api/contribute/repositories Public Contribution-eligible repositories for a contributor repo_scope: {repositories:[{id,forge,host,full_name}],generated_at}, the monitored repos minus hub.disabled_repos; id is {forge}/{host}/{owner}/{name} lower-cased (#12805) pkg/dashboard/api_contribute.go:254
GET /api/contribute/activity Public Contribute Activity pkg/dashboard/api_contribute.go:258
GET /api/contribute/fleet Public Contribute Fleet pkg/dashboard/api_contribute.go:259
GET /api/contribute/events Public Contribute Events (SSE). Every frame carries a monotonic seq; a connection whose channel filled gets a gap frame naming how many events it missed, so a long-lived client can tell "nothing happened" from "I missed events" (#6218) pkg/dashboard/api_contribute.go:263
GET /api/contribute/queue Public Contribute Queue pkg/dashboard/api_contribute.go:266
GET /api/contribute/opportunistic Public Contribute Opportunistic pkg/dashboard/api_contribute.go:270
GET /api/contribute/limits Public Contribute Limits pkg/dashboard/api_contribute.go:275
GET /api/contribute/metrics Public Contribute Metrics pkg/dashboard/api_contribute.go:281
GET /api/contribute/me Public path; caller identity resolved server-side (401 anonymous; a signed-in caller with no profile on this hive gets 200 with has_profile:false and no counters, #12111) The caller's OWN contribution stats — issues worked (24h and all-time), completions that produced a verified PR (24h and all-time, #7894), and failures. No username parameter, so it only ever answers for its caller (#6543) pkg/dashboard/api_contribute.go:291
GET /api/contribute/run-stats/models Public Per-model run evidence for the contributor wall: runs, verified-PR share, and failure rate over the selected window. pkg/dashboard/api_contribute.go
GET /api/contribute/wall Public Contributor wall posts when the hive-wide wall switch is enabled; anonymous readers see visible posts, authors can still see their own hidden posts. pkg/dashboard/api_contribute.go
POST /api/contribute/wall Signed-in contributor Create a 500-character plain-text wall post or one-level reply, with optional model, backend, and repo tags. Returns 401 anonymous, 403 when disabled/revoked/muted, and 429 when rate-limited. pkg/dashboard/api_contribute.go
DELETE /api/contribute/wall/{id} Post author Author deletes their own wall post; action is audit logged. pkg/dashboard/api_contribute.go
POST /api/contribute/wall/{id}/hide Owner/read-write Hide a wall post from public readers while leaving it visible to the author; action is audit logged and pushed over /api/contribute/events. pkg/dashboard/api_contribute.go
POST /api/contribute/wall/{id}/flag Signed-in contributor Flag a wall post for Management review; action is audit logged. pkg/dashboard/api_contribute.go
GET /api/contribute/triage Public Contribute Triage pkg/dashboard/api_contribute.go:312
PUT /api/contribute/queue/order Public Contribute Queue Order pkg/dashboard/api_contribute.go:316
POST /api/contribute/queue/hold Public Contribute Queue Hold pkg/dashboard/api_contribute.go:321
POST /api/contribute/queue/hold/clear Public Contribute Queue Hold Clear pkg/dashboard/api_contribute.go:325
GET /api/contribute/interests Public Contribute Interests pkg/dashboard/api_contribute.go:331
PUT /api/contribute/interests Public Contribute Interests pkg/dashboard/api_contribute.go:332
GET /api/contributors Dashboard auth/session Contributors List pkg/dashboard/api_contribute.go:340
GET /api/contributors/{id} Dashboard auth/session Contributor Get pkg/dashboard/api_contribute.go:341
POST /api/contributors/{id}/wall-mute Owner only Mute or unmute a contributor from posting to the contributor wall; action is audit logged. pkg/dashboard/api_contribute.go
PUT /api/contributors/{id}/trust Owner only Contributor Trust pkg/dashboard/api_contribute.go:343
PUT /api/contributors/{id}/agent-role Owner only Contributor Agent Role pkg/dashboard/api_contribute.go:344
PUT /api/contributors/{id}/agent-role-grants Owner only Contributor Agent Role Grants pkg/dashboard/api_contribute.go:345
POST /api/contributors/{id}/revoke Owner only Contributor Revoke pkg/dashboard/api_contribute.go:346
POST /api/contributors/{id}/requeue Dashboard auth/session Contributor Requeue pkg/dashboard/api_contribute.go:347
DELETE /api/contributors/{id} Owner only Contributor Delete pkg/dashboard/api_contribute.go:348
GET /contribute/dossier/{username} Public Contributor Dossier Page (HTML) pkg/dashboard/api_contribute.go:240
GET /api/contribute/run-stats Public Contribute Run Stats pkg/dashboard/api_contribute.go:299
GET /api/contribute/runs Public Contribute Per-Run History pkg/dashboard/api_contribute.go:389
GET /api/contribute/decisions Owner/read-write Contribute Hub Decisions pkg/dashboard/api_contribute.go:399
GET /api/contribute/dossier Public Contribute Dossier Get pkg/dashboard/api_contribute.go:336
POST /api/contribute/dossier Public Contribute Dossier Update pkg/dashboard/api_contribute.go:337
GET /api/leaderboard/contributor/{username}/heraldry Public Contributor Heraldry pkg/dashboard/api_contribute.go:369
GET /api/cards/player/{asset} Public OpenAPI alias for a cacheable contributor social-card SVG (asset is <github-login>.svg). pkg/dashboard/social_cards.go:112
GET /api/cards/achievement/{login}/{asset} Public OpenAPI alias for a cacheable attained-achievement SVG (asset is <achievement-id>.svg). pkg/dashboard/social_cards.go:113
GET /api/cards/leaderboard/{asset} Public OpenAPI alias for a cacheable leaderboard-summary SVG (contributors.svg, teams.svg, or swarm.svg). pkg/dashboard/social_cards.go:114
GET /cards/player/{asset} Public Cacheable 1200×630 SVG social card for one public contributor profile. pkg/dashboard/social_cards.go:109
GET /cards/achievement/{login}/{asset} Public Cacheable SVG achievement-unlocked card for an attained Achievement System 2.0 badge. pkg/dashboard/social_cards.go:110
GET /cards/leaderboard/{asset} Public Cacheable SVG summary card for contributors, teams, or swarm. pkg/dashboard/social_cards.go:111
GET /share/player/{login} Public Share landing page with Open Graph/Twitter metadata for a contributor card and link to the public dossier. pkg/dashboard/social_cards.go:115
GET /share/achievement/{login}/{achievementID} Public Share landing page with metadata for an unlocked achievement card and link to the public dossier. pkg/dashboard/social_cards.go:116
GET /share/leaderboard/{board} Public Share landing page with metadata for a public leaderboard card and link to live standings. pkg/dashboard/social_cards.go:117
PUT /api/contribute/help-links Owner/read-write Contribute Help Links pkg/dashboard/api_contribute.go:257
GET /api/contribute/operators/message Public path; caller identity resolved server-side (401 anonymous, 403 without a profile) Returns only the signed-in contributor's unacknowledged operator messages; no username/body field can select another recipient (#8461). pkg/dashboard/api_contribute.go:292
POST /api/contribute/operators/message Owner/read-write Sends a sanitized, length-capped one-to-one operator note to a contributor profile, persists it until acknowledgement, and pushes it to matching live relay sockets only (#8461). pkg/dashboard/api_contribute.go:293
POST /api/contribute/operators/message/ack Public path; caller identity resolved server-side Acknowledges the signed-in contributor's own message, optionally recording a short sanitized reply for operators. pkg/dashboard/api_contribute.go:294

Issue claims (#8380)

Method Path Auth Purpose Source
GET /api/claims Dashboard auth Every live worker claim ({enabled, claims:[…]}); enabled:false when claims.enabled: false pkg/dashboard/claims_api.go:54
GET /api/claims/{owner}/{repo}/{number} Dashboard auth {held, claim} for one issue pkg/dashboard/claims_api.go:55
POST /api/claims/{owner}/{repo}/{number} Signed-in / hub-proxied / GitHub-token caller claims as a human under their login; a verified owner token claims as the owner Body {force, ttl_s, session}. 200 with outcome claimed/renewed/taken_over; 409 with outcome held (same rank, retry with force) or refused (higher rank holds it) and a hint pkg/dashboard/claims_api.go:56
DELETE /api/claims/{owner}/{repo}/{number} Same identity rules Body {force, reason}. Releases your claim or a lower-ranked holder's; force with a verified owner role releases regardless of holder pkg/dashboard/claims_api.go:57

/api/v1 contributor subpaths

handleAPIv1 dispatches authenticated contributor API calls below /api/v1. Every request must carry a GitHub personal access token in the Authorization header, using either the Bearer <token> scheme (hosted clients) or the legacy token <token> scheme (what gh auth token and older hive CLIs send). Both are accepted; the legacy scheme is retained for backward compatibility. Credentials in the query string (?token=) are NOT supported and are rejected, because query strings land in ingress and access logs. The same rule applies to the shared dashboard owner token: send it in the Authorization header, not in URLs. Dashboard terminal links use /api/terminal/handoff to mint a ≤60-second single-use code for the browser navigation instead of putting the owner token in the terminal URL.

Authorization: every /api/v1 path except /api/v1/me additionally requires the caller to be in the hive's authorized-users allowlist (any role), and returns 403 otherwise — contributor, activity and knowledge data are hive-private, not world-readable. /api/v1/me is exempt because it only returns the caller's own profile. Client-supplied X-Hive-User, X-Hive-Role and owner-verified headers are stripped at the top of the handler; identity is always resolved server-side from the validated token.

Method Path Auth Purpose Source
GET/POST /api/v1/status GitHub token + allowlist Contributor status summary pkg/dashboard/api_contribute.go:1528
GET/POST /api/v1/queue GitHub token + allowlist Paginated ready-work listing (?limit=<int>&offset=<int>) over the actionable/offerable backlog pkg/dashboard/api_contribute.go:1524
GET/POST /api/v1/activity GitHub token + allowlist Contributor activity feed pkg/dashboard/api_contribute.go:1530
GET/POST /api/v1/contributors GitHub token + allowlist Contributor list pkg/dashboard/api_contribute.go:1532
GET/POST /api/v1/knowledge GitHub token + allowlist Knowledge export pkg/dashboard/api_contribute.go:1534
GET/POST /api/v1/me GitHub token (self-scoped, no allowlist) Current contributor profile pkg/dashboard/api_contribute.go:1536
POST /api/v1/prs/{owner}/{repo}/{number}/queue-automerge GitHub token + merger/owner role (POST only; GET returns 405) Queue PR auto-merge using the validated actor and current PR head pkg/dashboard/api_contribute.go