Notifications API

• List your notifications
• List your notifications in a repository
• Mark as read
• Mark notifications as read in a repository
• View a single thread
• Mark a thread as read
• Get a Thread Subscription
• Set a Thread Subscription
• Delete a Thread Subscription

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

• Issues and their comments
• Pull Requests and their comments
• Comments on any commits

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

• @mentions
• Issue assignments
• Commits the user authors or commits
• Any discussion in which the user actively participates

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

List your notifications

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

GET /notifications

Parameters

all

Optional boolean true to show notifications marked as read.

participating

Optional boolean true to show only notifications in which the user is directly participating or mentioned.

since

Optional time filters out any notifications updated before the given time. The time should be passed in as UTC in the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Example: “2012-10-09T23:39:01Z”.

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"
      },
      "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

all

Optional boolean true to show notifications marked as read.

participating

Optional boolean true to show only notifications in which the user is directly participating or mentioned.

since

Optional time filters out any notifications updated before the given time. The time should be passed in as UTC in the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Example: “2012-10-09T23:39:01Z”.

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"
      },
      "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

Input

last_read_at

Optional Time Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now. Expected in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Example: “2012-10-09T23:39:01Z”.

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

Input

last_read_at

Optional Time Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now. Expected in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Example: “2012-10-09T23:39:01Z”.

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"
    },
    "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/1/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/1/subscription

Input

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/1/subscription

Response

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