@@ -0,0 +1,79 @@ |
| 1 | +# Stargazers / starred lists |
| 2 | + |
| 3 | +Read-only directory pages that mirror GitHub's stargazer surfaces: |
| 4 | +list the users who starred a repo, or list the repos a user has |
| 5 | +starred. The existing `/api/v1/user/starred` + per-repo PUT/DELETE |
| 6 | +routes (the caller-self star management surface) are documented |
| 7 | +separately in [`users.md`](./users.md). |
| 8 | + |
| 9 | +Scopes: |
| 10 | + |
| 11 | +- `repo:read` on the per-repo stargazer list |
| 12 | +- `user:read` on the per-user starred list |
| 13 | + |
| 14 | +## Endpoints |
| 15 | + |
| 16 | +``` |
| 17 | +GET /api/v1/repos/{owner}/{repo}/stargazers users who starred this repo |
| 18 | +GET /api/v1/users/{username}/starred repos this user has starred |
| 19 | +``` |
| 20 | + |
| 21 | +Both endpoints are paginated with the standard `Link:` headers |
| 22 | +(default per_page 30, max 100) and recency-sorted (newest star |
| 23 | +first). |
| 24 | + |
| 25 | +## Stargazers list |
| 26 | + |
| 27 | +``` |
| 28 | +GET /api/v1/repos/alice/demo/stargazers |
| 29 | +``` |
| 30 | + |
| 31 | +```json |
| 32 | +[ |
| 33 | + { |
| 34 | + "user_id": 42, |
| 35 | + "username": "bob", |
| 36 | + "display_name": "Bob", |
| 37 | + "starred_at": "2026-05-12T18:00:00Z" |
| 38 | + } |
| 39 | +] |
| 40 | +``` |
| 41 | + |
| 42 | +Visibility follows the repo: a private-repo stargazer list is only |
| 43 | +visible to callers with `repo:read` access to that repo. Cross-actor |
| 44 | +attempts return `404` to avoid leaking existence. |
| 45 | + |
| 46 | +## User starred list |
| 47 | + |
| 48 | +``` |
| 49 | +GET /api/v1/users/alice/starred |
| 50 | +``` |
| 51 | + |
| 52 | +```json |
| 53 | +[ |
| 54 | + { |
| 55 | + "repo_id": 17, |
| 56 | + "owner": "alice", |
| 57 | + "name": "demo", |
| 58 | + "description": "demo repo", |
| 59 | + "visibility": "public", |
| 60 | + "star_count": 3, |
| 61 | + "primary_language": "Go", |
| 62 | + "updated_at": "2026-05-12T17:00:00Z", |
| 63 | + "starred_at": "2026-05-12T18:00:00Z" |
| 64 | + } |
| 65 | +] |
| 66 | +``` |
| 67 | + |
| 68 | +For cross-user views the list is post-filtered: repos the caller |
| 69 | +can't read (private repos they're not a collaborator on) are |
| 70 | +silently dropped from the response. The total reflected in the |
| 71 | +`Link:` header reflects the raw star count for the user; the |
| 72 | +returned page may therefore contain fewer items than `per_page` |
| 73 | +when private stars are filtered out. |
| 74 | + |
| 75 | +## Errors |
| 76 | + |
| 77 | +- `404` — repo or username doesn't exist (uniform envelope; can't |
| 78 | + enumerate via response shape). |
| 79 | +- `403` — PAT lacks the required scope. |