shithub Public

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

Notifications

User-scoped inbox for the authenticated PAT. Mirrors GitHub's /notifications API; each "thread" in the GitHub sense maps to one row in shithub's notifications table.

Scopes:

  • user:read — list and fetch
  • user:write — mark read/unread, mark all read

All endpoints are implicitly scoped to the authenticated user. There is no admin-level "read another user's inbox" surface.

List notifications

GET /api/v1/notifications[?all=true|false&page=&per_page=]
  • all (default false) returns unread only. Pass all=true to include read notifications.
  • Standard page / per_page pagination (per_page ≤ 100, default 30). Link: headers emit first/prev/next/last.
  • Sorted by last_event_at DESC.
[
  {
    "id":            5142,
    "unread":        true,
    "reason":        "mention",
    "kind":          "issue_comment",
    "updated_at":    "2026-05-12T15:00:00Z",
    "last_event_at": "2026-05-12T15:00:00Z",
    "subject": {
      "title":  "fix race in fanout worker",
      "type":   "issue",
      "number": 42
    },
    "repository": {
      "owner_login": "alice",
      "name":        "demo",
      "full_name":   "alice/demo"
    }
  }
]

subject.type is one of issue / pull_request, or empty for threadless system notifications.

Get a single notification

GET /api/v1/notifications/threads/{id}

Cross-user probes return 404 (existence-leak guard) so a caller can't enumerate other users' notification ids.

Mark a notification read / unread

PATCH /api/v1/notifications/threads/5142
Content-Type: application/json

{ "unread": false }
  • Empty body or unread: false → mark read (gh's default).
  • unread: true → flip back to unread (shithub extension — useful for "I'll come back to this").

Returns 204 No Content.

Mark all read

PUT /api/v1/notifications

Returns 204 No Content once every unread row for the caller has been flipped to read. Idempotent.

Errors

  • 404 — notification id doesn't exist, or belongs to another user.
  • 403 — PAT lacks the required scope.
View source
1 # Notifications
2
3 User-scoped inbox for the authenticated PAT. Mirrors GitHub's
4 `/notifications` API; each "thread" in the GitHub sense maps to
5 one row in shithub's `notifications` table.
6
7 Scopes:
8
9 - `user:read` — list and fetch
10 - `user:write` — mark read/unread, mark all read
11
12 All endpoints are implicitly scoped to the authenticated user.
13 There is no admin-level "read another user's inbox" surface.
14
15 ## List notifications
16
17 ```
18 GET /api/v1/notifications[?all=true|false&page=&per_page=]
19 ```
20
21 - `all` (default `false`) returns **unread only**. Pass
22 `all=true` to include read notifications.
23 - Standard `page` / `per_page` pagination (per_page ≤ 100,
24 default 30). `Link:` headers emit `first`/`prev`/`next`/`last`.
25 - Sorted by `last_event_at DESC`.
26
27 ```json
28 [
29 {
30 "id": 5142,
31 "unread": true,
32 "reason": "mention",
33 "kind": "issue_comment",
34 "updated_at": "2026-05-12T15:00:00Z",
35 "last_event_at": "2026-05-12T15:00:00Z",
36 "subject": {
37 "title": "fix race in fanout worker",
38 "type": "issue",
39 "number": 42
40 },
41 "repository": {
42 "owner_login": "alice",
43 "name": "demo",
44 "full_name": "alice/demo"
45 }
46 }
47 ]
48 ```
49
50 `subject.type` is one of `issue` / `pull_request`, or empty for
51 threadless system notifications.
52
53 ## Get a single notification
54
55 ```
56 GET /api/v1/notifications/threads/{id}
57 ```
58
59 Cross-user probes return 404 (existence-leak guard) so a caller
60 can't enumerate other users' notification ids.
61
62 ## Mark a notification read / unread
63
64 ```http
65 PATCH /api/v1/notifications/threads/5142
66 Content-Type: application/json
67
68 { "unread": false }
69 ```
70
71 - Empty body or `unread: false` → mark **read** (gh's default).
72 - `unread: true` → flip back to unread (shithub extension —
73 useful for "I'll come back to this").
74
75 Returns `204 No Content`.
76
77 ## Mark all read
78
79 ```
80 PUT /api/v1/notifications
81 ```
82
83 Returns `204 No Content` once every unread row for the caller
84 has been flipped to read. Idempotent.
85
86 ## Errors
87
88 - `404` — notification id doesn't exist, or belongs to another
89 user.
90 - `403` — PAT lacks the required scope.