Notifications

GitHub Notifications are powered by watched repositories. Users receive notifications for discussions in repositories they watch including:

Notifications are also sent for discussions in unwatched repositories when the user is involved including:

All Notification API calls require the notifications or repo API scopes. Doing this will give read-only access to some Issue/Commit content. You will still need the “repo” scope to access Issues and Commits from their respective endpoints.

Notifications come back as “threads”. A Thread contains information about the current discussion of an Issue/PullRequest/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 https://api.github.com/notifications
HTTP/1.1 200 OK
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60

# Pass the Last-Modified header exactly
$ curl -I https://api.github.com/notifications
    -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
HTTP/1.1 304 Not Modified
X-Poll-Interval: 60

Notification Reasons

When retrieving responses from the Notifications API, each payload has a key titled reason. These correspond to events that trigger a notification.

Here’s a list of potential reasons for receiving a notification:

Reason Name Description
subscribed The notification arrived because you’re watching the repository
manual The notification arrived because you’ve specifically decided to watch the item (via an Issue or Pull Request)
author The notification arrived because you’ve created the item
comment The notification arrived because you’ve commented on the item
mention The notification arrived because you were specifically @mentioned in the content
team_mention The notification arrived because you were on a team that was mentioned (like @org/team)
state_change The notification arrived because you changed the item state (like closing an Issue or merging a Pull Request)
assign The notification arrived because you were assigned to the Issue

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 your notifications

List all notifications for the current user, grouped by repository.

GET /notifications

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 Filters out any notifications updated before the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Default: Time.now

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "id": "1",
    "repository": {
      "id": 1296269,
      "owner": {
        "login": "octocat",
        "id": 1,
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "somehexcode",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "description": "This your first repo!",
      "private": false,
      "fork": false,
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "html_url": "https://github.com/octocat/Hello-World"
    },
    "subject": {
      "title": "Greetings",
      "url": "https://api.github.com/repos/pengwynn/octokit/issues/123",
      "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123",
      "type": "Issue"
    },
    "reason": "subscribed",
    "unread": true,
    "updated_at": "2012-09-25T07:54:41-07:00",
    "last_read_at": "2012-09-25T07:54:41-07:00",
    "url": "https://api.github.com/notifications/threads/1"
  }
]

List your notifications in a repository

List all notifications for the current user.

GET /repos/:owner/:repo/notifications

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 Filters out any notifications updated before the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Default: Time.now

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "id": "1",
    "repository": {
      "id": 1296269,
      "owner": {
        "login": "octocat",
        "id": 1,
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "somehexcode",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "name": "Hello-World",
      "full_name": "octocat/Hello-World",
      "description": "This your first repo!",
      "private": false,
      "fork": false,
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "html_url": "https://github.com/octocat/Hello-World"
    },
    "subject": {
      "title": "Greetings",
      "url": "https://api.github.com/repos/pengwynn/octokit/issues/123",
      "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123",
      "type": "Issue"
    },
    "reason": "subscribed",
    "unread": true,
    "updated_at": "2012-09-25T07:54:41-07:00",
    "last_read_at": "2012-09-25T07:54:41-07:00",
    "url": "https://api.github.com/notifications/threads/1"
  }
]

Mark as read

Marking a notification as “read” removes it from the default view on GitHub.com.

PUT /notifications

Parameters

Name Type Description
last_read_at string Describes the last point that notifications were checked. Anything updated since this time will not be updated. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Default: Time.now

Response

Status: 205 Reset Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Mark notifications as read in a repository

Marking all notifications in a repository as “read” removes them from the default view on GitHub.com.

PUT /repos/:owner/:repo/notifications

Parameters

Name Type Description
last_read_at string Describes the last point that notifications were checked. Anything updated since this time will not be updated. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Default: Time.now

Response

Status: 205 Reset Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

View a single thread

GET /notifications/threads/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "id": "1",
  "repository": {
    "id": 1296269,
    "owner": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "description": "This your first repo!",
    "private": false,
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "html_url": "https://github.com/octocat/Hello-World"
  },
  "subject": {
    "title": "Greetings",
    "url": "https://api.github.com/repos/pengwynn/octokit/issues/123",
    "latest_comment_url": "https://api.github.com/repos/pengwynn/octokit/issues/comments/123",
    "type": "Issue"
  },
  "reason": "subscribed",
  "unread": true,
  "updated_at": "2012-09-25T07:54:41-07:00",
  "last_read_at": "2012-09-25T07:54:41-07:00",
  "url": "https://api.github.com/notifications/threads/1"
}

Mark a thread as read

PATCH /notifications/threads/:id

Response

Status: 205 Reset Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Get a Thread Subscription

This checks to see if the current user is subscribed to a thread. You can also get a Repository subscription.

GET /notifications/threads/:id/subscription

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "subscribed": true,
  "ignored": false,
  "reason": null,
  "created_at": "2012-10-06T21:34:12Z",
  "url": "https://api.github.com/notifications/threads/1/subscription",
  "thread_url": "https://api.github.com/notifications/threads/1"
}

Set a Thread Subscription

This lets you subscribe to a thread, or ignore it. Subscribing to a thread is unnecessary if the user is already subscribed to the repository. Ignoring a thread will mute all future notifications (until you comment or get @mentioned).

PUT /notifications/threads/:id/subscription

Parameters

Name Type Description
subscribed boolean Determines if notifications should be received from this thread
ignored boolean Determines if all notifications should be blocked from this thread

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "subscribed": true,
  "ignored": false,
  "reason": null,
  "created_at": "2012-10-06T21:34:12Z",
  "url": "https://api.github.com/notifications/threads/1/subscription",
  "thread_url": "https://api.github.com/notifications/threads/1"
}

Delete a Thread Subscription

DELETE /notifications/threads/:id/subscription

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999