shithub Public

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

Watching / subscriptions

Mirrors GitHub's /repos/{owner}/{repo}/subscription family — manage the authenticated user's watch level on a repo.

shithub's internal vocabulary is watch; the public URL uses the gh-flavored noun subscription so existing CLI ports keep working without churn.

Scopes:

  • repo:read on GETs
  • user:write on PUT/DELETE (watching is a user-scoped preference, not a repo mutation)

Watch levels

Level Meaning
all Notify on every event in the repo.
participating Notify only when @-mentioned or directly involved (the implicit default; matches gh's "Participating and @mentions").
ignore Mute. Excluded from subscriber lists.

Endpoints

GET    /api/v1/repos/{owner}/{repo}/subscribers          paginated list of watchers
GET    /api/v1/repos/{owner}/{repo}/subscription         viewer's current watch level
PUT    /api/v1/repos/{owner}/{repo}/subscription         set an explicit level
DELETE /api/v1/repos/{owner}/{repo}/subscription         revert to the implicit default

List subscribers

GET /api/v1/repos/alice/demo/subscribers[?page=&per_page=]

Paginated, recency-sorted, excludes users at ignore level and suspended users.

[
  {
    "user_id":      42,
    "username":     "bob",
    "display_name": "Bob",
    "level":        "all",
    "updated_at":   "2026-05-12T15:00:00Z"
  }
]

Get your subscription

GET /api/v1/repos/alice/demo/subscription

{ "level": "participating", "explicit": false }

explicit: false means the caller hasn't set an explicit watch row — they're on the implicit participating default. After a PUT, follow-up GETs return explicit: true.

Set / clear your subscription

PUT /api/v1/repos/alice/demo/subscription
Content-Type: application/json

{ "level": "all" }

DELETE /api/v1/repos/alice/demo/subscription

DELETE removes the explicit row and reverts to the implicit default; returns 204 No Content. PUT returns 200 with the new subscription shape.

Errors

  • 404 — repo not visible to the caller.
  • 403 — PAT lacks the required scope.
  • 422 — level is not one of all / participating / ignore.
View source
1 # Watching / subscriptions
2
3 Mirrors GitHub's `/repos/{owner}/{repo}/subscription` family —
4 manage the authenticated user's watch level on a repo.
5
6 shithub's internal vocabulary is **watch**; the public URL uses
7 the gh-flavored noun **subscription** so existing CLI ports
8 keep working without churn.
9
10 Scopes:
11
12 - `repo:read` on GETs
13 - `user:write` on PUT/DELETE (watching is a user-scoped
14 preference, not a repo mutation)
15
16 ## Watch levels
17
18 | Level | Meaning |
19 |-------|---------|
20 | `all` | Notify on every event in the repo. |
21 | `participating` | Notify only when @-mentioned or directly involved (the **implicit default**; matches gh's "Participating and @mentions"). |
22 | `ignore` | Mute. Excluded from subscriber lists. |
23
24 ## Endpoints
25
26 ```
27 GET /api/v1/repos/{owner}/{repo}/subscribers paginated list of watchers
28 GET /api/v1/repos/{owner}/{repo}/subscription viewer's current watch level
29 PUT /api/v1/repos/{owner}/{repo}/subscription set an explicit level
30 DELETE /api/v1/repos/{owner}/{repo}/subscription revert to the implicit default
31 ```
32
33 ### List subscribers
34
35 ```
36 GET /api/v1/repos/alice/demo/subscribers[?page=&per_page=]
37 ```
38
39 Paginated, recency-sorted, **excludes** users at `ignore` level
40 and suspended users.
41
42 ```json
43 [
44 {
45 "user_id": 42,
46 "username": "bob",
47 "display_name": "Bob",
48 "level": "all",
49 "updated_at": "2026-05-12T15:00:00Z"
50 }
51 ]
52 ```
53
54 ### Get your subscription
55
56 ```
57 GET /api/v1/repos/alice/demo/subscription
58 ```
59
60 ```json
61 { "level": "participating", "explicit": false }
62 ```
63
64 `explicit: false` means the caller hasn't set an explicit watch
65 row — they're on the implicit `participating` default. After a
66 PUT, follow-up GETs return `explicit: true`.
67
68 ### Set / clear your subscription
69
70 ```http
71 PUT /api/v1/repos/alice/demo/subscription
72 Content-Type: application/json
73
74 { "level": "all" }
75 ```
76
77 ```
78 DELETE /api/v1/repos/alice/demo/subscription
79 ```
80
81 DELETE removes the explicit row and reverts to the implicit
82 default; returns `204 No Content`. PUT returns `200` with the
83 new subscription shape.
84
85 ## Errors
86
87 - `404` — repo not visible to the caller.
88 - `403` — PAT lacks the required scope.
89 - `422` — `level` is not one of `all` / `participating` /
90 `ignore`.