shithub Public

Watch 1 Fork 0 Star 0
markdown · 2054 bytes Raw Blame History

Stargazers / starred lists

Read-only directory pages that mirror GitHub's stargazer surfaces: list the users who starred a repo, or list the repos a user has starred. The existing /api/v1/user/starred + per-repo PUT/DELETE routes (the caller-self star management surface) are documented separately in users.md.

Scopes:

  • repo:read on the per-repo stargazer list
  • user:read on the per-user starred list

Endpoints

GET /api/v1/repos/{owner}/{repo}/stargazers     users who starred this repo
GET /api/v1/users/{username}/starred             repos this user has starred

Both endpoints are paginated with the standard Link: headers (default per_page 30, max 100) and recency-sorted (newest star first).

Stargazers list

GET /api/v1/repos/alice/demo/stargazers

[
  {
    "user_id":      42,
    "username":     "bob",
    "display_name": "Bob",
    "starred_at":   "2026-05-12T18:00:00Z"
  }
]

Visibility follows the repo: a private-repo stargazer list is only visible to callers with repo:read access to that repo. Cross-actor attempts return 404 to avoid leaking existence.

User starred list

GET /api/v1/users/alice/starred

[
  {
    "repo_id":          17,
    "owner":            "alice",
    "name":             "demo",
    "description":      "demo repo",
    "visibility":       "public",
    "star_count":       3,
    "primary_language": "Go",
    "updated_at":       "2026-05-12T17:00:00Z",
    "starred_at":       "2026-05-12T18:00:00Z"
  }
]

For cross-user views the list is post-filtered: repos the caller can't read (private repos they're not a collaborator on) are silently dropped from the response. The total reflected in the Link: header reflects the raw star count for the user; the returned page may therefore contain fewer items than per_page when private stars are filtered out.

Errors

  • 404 — repo or username doesn't exist (uniform envelope; can't enumerate via response shape).
  • 403 — PAT lacks the required scope.
View source
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.