This version of GitHub Enterprise was discontinued on 2023-03-15. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

After a site administrator upgrades your Enterprise Server instance to Enterprise Server 3.9 or later, the REST API will be versioned. To learn how to find your instance's version, see "About versions of GitHub Docs". For more information, see "About API versioning."

Notifications

Use the REST API to manage GitHub Enterprise Server notifications.

About GitHub Enterprise Server notifications

You can use the REST API to manage GitHub Enterprise Server notifications. For more information about notifications, see "About notifications."

All calls to these endpoints require the notifications or repo scopes. You will need the repo scope to access issues and commits from their respective endpoints.

Notifications are returned as "threads". A thread contains information about the current discussion of an issue, pull request, or commit.

Notifications are optimized for polling with the Last-Modified header. If there are no new notifications, you will see a 304 Not Modified response, leaving your current rate limit untouched. There is an X-Poll-Interval header that specifies how often (in seconds) you are allowed to poll. In times of high server load, the time may increase. Please obey the header.

# Add authentication to your requests
$ curl -I http(s)://HOSTNAME/api/v3/notifications
HTTP/2 200
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60

# Pass the Last-Modified header exactly
$ curl -I http(s)://HOSTNAME/api/v3/notifications
$    -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
> HTTP/2 304
> X-Poll-Interval: 60

About notification reasons

These GET endpoints return a reason key. These reasons correspond to events that trigger a notification.

There are a few potential reasons for receiving a notification.

Reason Name	Description
`assign`	You were assigned to the issue.
`author`	You created the thread.
`comment`	You commented on the thread.
`ci_activity`	A GitHub Actions workflow run that you triggered was completed.
`invitation`	You accepted an invitation to contribute to the repository.
`manual`	You subscribed to the thread (via an issue or pull request).
`mention`	You were specifically @mentioned in the content.
`review_requested`	You, or a team you're a member of, were requested to review a pull request.
`state_change`	You changed the thread state (for example, closing an issue or merging a pull request).
`subscribed`	You're watching the repository.
`team_mention`	You were on a team that was mentioned.

Note that the reason is modified on a per-thread basis, and can change, if the reason on a later notification is different.

For example, if you are the author of an issue, subsequent notifications on that issue will have a reason of author. If you're then @mentioned on the same issue, the notifications you fetch thereafter will have a reason of mention. The reason remains as mention, regardless of whether you're ever mentioned again.

List notifications for the authenticated user

List all notifications for the current user, sorted by most recently updated.

Parameters for "List notifications for the authenticated user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.
Query parameters
Name, Type, Description
`all` boolean If `true`, show notifications marked as read. Default: `false`
`participating` boolean If `true`, only shows notifications in which the user is directly participating or mentioned. Default: `false`
`since` string Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`before` string Only show notifications updated before the given time. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`page` integer Page number of the results to fetch. Default: `1`
`per_page` integer The number of results per page (max 50). Default: `50`

HTTP response status codes for "List notifications for the authenticated user"

Status code	Description
`200`	OK
`304`	Not modified
`401`	Requires authentication
`403`	Forbidden
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "List notifications for the authenticated user"

get/notifications

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  http(s)://HOSTNAME/api/v3/notifications

Response

Status: 200

[
  {
    "id": "1",
    "repository": {
      "id": 1296269,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "owner": {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://HOSTNAME/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://HOSTNAME/users/octocat/followers",
        "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
        "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
        "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
        "organizations_url": "https://HOSTNAME/users/octocat/orgs",
        "repos_url": "https://HOSTNAME/users/octocat/repos",
        "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
        "received_events_url": "https://HOSTNAME/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "private": false,
      "html_url": "https://github.com/octocat/Hello-World",
      "description": "This your first repo!",
      "fork": false,
      "url": "https://HOSTNAME/repos/octocat/Hello-World",
      "archive_url": "https://HOSTNAME/repos/octocat/Hello-World/{archive_format}{/ref}",
      "assignees_url": "https://HOSTNAME/repos/octocat/Hello-World/assignees{/user}",
      "blobs_url": "https://HOSTNAME/repos/octocat/Hello-World/git/blobs{/sha}",
      "branches_url": "https://HOSTNAME/repos/octocat/Hello-World/branches{/branch}",
      "collaborators_url": "https://HOSTNAME/repos/octocat/Hello-World/collaborators{/collaborator}",
      "comments_url": "https://HOSTNAME/repos/octocat/Hello-World/comments{/number}",
      "commits_url": "https://HOSTNAME/repos/octocat/Hello-World/commits{/sha}",
      "compare_url": "https://HOSTNAME/repos/octocat/Hello-World/compare/{base}...{head}",
      "contents_url": "https://HOSTNAME/repos/octocat/Hello-World/contents/{+path}",
      "contributors_url": "https://HOSTNAME/repos/octocat/Hello-World/contributors",
      "deployments_url": "https://HOSTNAME/repos/octocat/Hello-World/deployments",
      "downloads_url": "https://HOSTNAME/repos/octocat/Hello-World/downloads",
      "events_url": "https://HOSTNAME/repos/octocat/Hello-World/events",
      "forks_url": "https://HOSTNAME/repos/octocat/Hello-World/forks",
      "git_commits_url": "https://HOSTNAME/repos/octocat/Hello-World/git/commits{/sha}",
      "git_refs_url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs{/sha}",
      "git_tags_url": "https://HOSTNAME/repos/octocat/Hello-World/git/tags{/sha}",
      "git_url": "git:github.com/octocat/Hello-World.git",
      "issue_comment_url": "https://HOSTNAME/repos/octocat/Hello-World/issues/comments{/number}",
      "issue_events_url": "https://HOSTNAME/repos/octocat/Hello-World/issues/events{/number}",
      "issues_url": "https://HOSTNAME/repos/octocat/Hello-World/issues{/number}",
      "keys_url": "https://HOSTNAME/repos/octocat/Hello-World/keys{/key_id}",
      "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/labels{/name}",
      "languages_url": "https://HOSTNAME/repos/octocat/Hello-World/languages",
      "merges_url": "https://HOSTNAME/repos/octocat/Hello-World/merges",
      "milestones_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones{/number}",
      "notifications_url": "https://HOSTNAME/repos/octocat/Hello-World/notifications{?since,all,participating}",
      "pulls_url": "https://HOSTNAME/repos/octocat/Hello-World/pulls{/number}",
      "releases_url": "https://HOSTNAME/repos/octocat/Hello-World/releases{/id}",
      "ssh_url": "git@github.com:octocat/Hello-World.git",
      "stargazers_url": "https://HOSTNAME/repos/octocat/Hello-World/stargazers",
      "statuses_url": "https://HOSTNAME/repos/octocat/Hello-World/statuses/{sha}",
      "subscribers_url": "https://HOSTNAME/repos/octocat/Hello-World/subscribers",
      "subscription_url": "https://HOSTNAME/repos/octocat/Hello-World/subscription",
      "tags_url": "https://HOSTNAME/repos/octocat/Hello-World/tags",
      "teams_url": "https://HOSTNAME/repos/octocat/Hello-World/teams",
      "trees_url": "https://HOSTNAME/repos/octocat/Hello-World/git/trees{/sha}",
      "hooks_url": "http://HOSTNAME/repos/octocat/Hello-World/hooks"
    },
    "subject": {
      "title": "Greetings",
      "url": "https://HOSTNAME/repos/octokit/octokit.rb/issues/123",
      "latest_comment_url": "https://HOSTNAME/repos/octokit/octokit.rb/issues/comments/123",
      "type": "Issue"
    },
    "reason": "subscribed",
    "unread": true,
    "updated_at": "2014-11-07T22:01:45Z",
    "last_read_at": "2014-11-07T22:01:45Z",
    "url": "https://HOSTNAME/notifications/threads/1",
    "subscription_url": "https://HOSTNAME/notifications/threads/1/subscription"
  }
]

Mark notifications as read

Marks all notifications as "read" for the current user. If the number of notifications is too large to complete in one request, you will receive a 202 Accepted status and GitHub Enterprise Server will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List notifications for the authenticated user endpoint and pass the query parameter all=false.

Parameters for "Mark notifications as read"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.
Body parameters
Name, Type, Description
`last_read_at` string Describes the last point that notifications were checked. Anything updated since this time will not be marked as read. If you omit this parameter, all notifications are marked as read. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Default: The current timestamp.