shithub Public

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

Issue events / timeline

Read-only access to an issue's recorded timeline events: every state mutation (labeled, unlabeled, milestoned, demilestoned, locked, unlocked, closed, reopened, referenced, …) inserts a row in issue_events and surfaces here.

Scope: repo:read.

Endpoint

GET /api/v1/repos/{owner}/{repo}/issues/{number}/events

Paginated with the standard Link: headers (default per_page 30, max 100). Events are sorted oldest-first to match gh and the HTML issue view.

Response shape

[
  {
    "id":              17,
    "kind":            "labeled",
    "actor_user_id":   42,
    "actor_username":  "alice",
    "meta": {
      "label_id":   8,
      "label_name": "bug"
    },
    "ref_target_id":   null,
    "created_at":      "2026-05-12T18:00:00Z"
  }
]
  • kind is the event discriminator. Known values today include closed, reopened, locked, unlocked, labeled, unlabeled, milestoned, demilestoned, referenced, merged, and head_ref_force_pushed (the last two on PR threads). New event kinds are added over time; clients should treat unknown kinds as opaque.
  • actor_user_id / actor_username are omitted when the event was system-emitted (no actor) or when the actor row was hard- deleted. The timeline is historical truth — suspending or deleting a user does not retroactively erase their authored events.
  • meta is the event's structured payload, returned verbatim as it was recorded. The keys vary by kind; e.g. labeled/ unlabeled carry label_id + label_name, closed may carry comment_id when the close was paired with a comment.
  • ref_target_id is populated for referenced events (the cross-referenced issue's id) and otherwise omitted.

Errors

  • 404 — repo or issue doesn't exist (uniform envelope; can't enumerate via response shape).
  • 403 — PAT lacks repo:read.

The PR-side equivalent (review submissions, push events, merge events) is recorded into the same issue_events table because PR records share the underlying issues row; both surfaces are served by this endpoint.

For higher-level activity feeds, see Events / activity (repo-scoped and user-scoped domain events).

View source
1 # Issue events / timeline
2
3 Read-only access to an issue's recorded timeline events: every
4 state mutation (labeled, unlabeled, milestoned, demilestoned,
5 locked, unlocked, closed, reopened, referenced, …) inserts a row
6 in `issue_events` and surfaces here.
7
8 Scope: `repo:read`.
9
10 ## Endpoint
11
12 ```
13 GET /api/v1/repos/{owner}/{repo}/issues/{number}/events
14 ```
15
16 Paginated with the standard `Link:` headers (default per_page 30,
17 max 100). Events are sorted **oldest-first** to match gh and the
18 HTML issue view.
19
20 ## Response shape
21
22 ```json
23 [
24 {
25 "id": 17,
26 "kind": "labeled",
27 "actor_user_id": 42,
28 "actor_username": "alice",
29 "meta": {
30 "label_id": 8,
31 "label_name": "bug"
32 },
33 "ref_target_id": null,
34 "created_at": "2026-05-12T18:00:00Z"
35 }
36 ]
37 ```
38
39 - `kind` is the event discriminator. Known values today include
40 `closed`, `reopened`, `locked`, `unlocked`, `labeled`,
41 `unlabeled`, `milestoned`, `demilestoned`, `referenced`,
42 `merged`, and `head_ref_force_pushed` (the last two on PR
43 threads). New event kinds are added over time; clients should
44 treat unknown kinds as opaque.
45 - `actor_user_id` / `actor_username` are omitted when the event
46 was system-emitted (no actor) or when the actor row was hard-
47 deleted. The timeline is historical truth — suspending or
48 deleting a user does not retroactively erase their authored
49 events.
50 - `meta` is the event's structured payload, returned verbatim as
51 it was recorded. The keys vary by `kind`; e.g. `labeled`/
52 `unlabeled` carry `label_id` + `label_name`, `closed` may carry
53 `comment_id` when the close was paired with a comment.
54 - `ref_target_id` is populated for `referenced` events (the
55 cross-referenced issue's id) and otherwise omitted.
56
57 ## Errors
58
59 - `404` — repo or issue doesn't exist (uniform envelope; can't
60 enumerate via response shape).
61 - `403` — PAT lacks `repo:read`.
62
63 ## Related
64
65 The PR-side equivalent (review submissions, push events, merge
66 events) is recorded into the same `issue_events` table because PR
67 records share the underlying `issues` row; both surfaces are
68 served by this endpoint.
69
70 For higher-level activity feeds, see [Events / activity](./events.md)
71 (repo-scoped and user-scoped domain events).