Notifications

Notification Reasons
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

Users receive notifications for conversations in repositories they watch including:

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

Notifications are also sent for conversations 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

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 subscribe to the thread (via an Issue or Pull Request)
`author`	The notification arrived because you’ve created the thread
`comment`	The notification arrived because you’ve commented on the thread
`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 thread 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": "",
        "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": "",
        "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": "",
      "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.

Note that subscriptions are only generated if a user is participating in a conversation–for example, they’ve replied to the thread, were @mentioned, or manually subscribe to a thread.

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 or unsubscribe from a conversation. Unsubscribing from a conversation mutes all future notifications (until you comment or get @mentioned once more).

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

LFE Docs

Notifications

Notification Reasons

List your notifications

Parameters

Response

List your notifications in a repository

Parameters

Response

Mark as read

Parameters

Response

Mark notifications as read in a repository

Parameters

Response

View a single thread

Response

Mark a thread as read

Response

Get a Thread Subscription

Response

Set a Thread Subscription

Parameters

Response

Delete a Thread Subscription

Response

Overview

Activity

Gists

Git Data

Issues

Miscellaneous

Organizations

Pull Requests

Repositories

Search

Users

Enterprise 2.1