REST API endpoints for notifications

Use the REST API to manage GitHub notifications.

About GitHub notifications

Note

These endpoints only support authentication using a personal access token (classic). For more information, see Managing your personal access tokens.

You can use the REST API to manage GitHub 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 https://api.github.com/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 https://api.github.com/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
agent_session_finished A Copilot cloud agent session finished.
approval_requested You were requested to review and approve a deployment. For more information, see Reviewing deployments.
assign You were assigned to the issue.
author You created the thread.
ci_activity A GitHub Actions workflow run that you triggered was completed.
comment You commented on the thread.
invitation You accepted an invitation to contribute to the repository.
manual You subscribed to the thread (via an issue or pull request).
member_feature_requested Organization members have requested to enable a feature such as Copilot.
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.
security_advisory_credit You were credited for contributing to a security advisory.
security_alert GitHub discovered a security vulnerability in your repository.
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.

Note

Most endpoints use Authorization: Bearer <YOUR-TOKEN> and Accept: application/vnd.github+json headers, plus X-GitHub-Api-Version: 2026-03-10. Curl examples below omit these standard headers for brevity.

List notifications for the authenticated user

GET /notifications

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

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/notifications

Response schema (Status: 200):

Array of Thread:

Mark notifications as read

PUT /notifications

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

Headers

Body parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X PUT \
  https://api.github.com/notifications \
  -d '{
  "last_read_at": "2022-06-10T00:00:00Z",
  "read": true
}'

Response schema (Status: 202):

Get a thread

GET /notifications/threads/{thread_id}

Gets information about a notification thread.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/notifications/threads/THREAD_ID

Response schema (Status: 200):

Mark a thread as read

PATCH /notifications/threads/{thread_id}

Marks a thread as "read." Marking a thread as "read" is equivalent to clicking a notification in your notification inbox on GitHub: https://github.com/notifications.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X PATCH \
  https://api.github.com/notifications/threads/THREAD_ID

Response schema (Status: 205):

Mark a thread as done

DELETE /notifications/threads/{thread_id}

Marks a thread as "done." Marking a thread as "done" is equivalent to marking a notification in your notification inbox on GitHub as done: https://github.com/notifications.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X DELETE \
  https://api.github.com/notifications/threads/THREAD_ID

Response schema (Status: 204):

Get a thread subscription for the authenticated user

GET /notifications/threads/{thread_id}/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.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/notifications/threads/THREAD_ID/subscription

Response schema (Status: 200):

Set a thread subscription

PUT /notifications/threads/{thread_id}/subscription

If you are watching a repository, you receive notifications for all threads by default. Use this endpoint to ignore future notifications for threads until you comment on the thread or get an @mention.
You can also use this endpoint to subscribe to threads that you are currently not receiving notifications for or to subscribed to threads that you have previously ignored.
Unsubscribing from a conversation in a repository that you are not watching is functionally equivalent to the Delete a thread subscription endpoint.

Parameters

Headers

Path and query parameters

Body parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X PUT \
  https://api.github.com/notifications/threads/THREAD_ID/subscription \
  -d '{
  "ignored": false
}'

Response schema (Status: 200):

Same response schema as Get a thread subscription for the authenticated user.

Delete a thread subscription

DELETE /notifications/threads/{thread_id}/subscription

Mutes all future notifications for a conversation until you comment on the thread or get an @mention. If you are watching the repository of the thread, you will still receive notifications. To ignore future notifications for a repository you are watching, use the Set a thread subscription endpoint and set ignore to true.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X DELETE \
  https://api.github.com/notifications/threads/THREAD_ID/subscription

Response schema (Status: 204):

List repository notifications for the authenticated user

GET /repos/{owner}/{repo}/notifications

Lists all notifications for the current user in the specified repository.

Parameters

Headers

Path and query parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X GET \
  https://api.github.com/repos/OWNER/REPO/notifications

Response schema (Status: 200):

Same response schema as List notifications for the authenticated user.

Mark repository notifications as read

PUT /repos/{owner}/{repo}/notifications

Marks all notifications in a repository 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 will run an asynchronous process to mark notifications as "read." To check whether any "unread" notifications remain, you can use the List repository notifications for the authenticated user endpoint and pass the query parameter all=false.

Parameters

Headers

Path and query parameters

Body parameters

HTTP response status codes

Code examples

Example

Request:

curl -L \
  -X PUT \
  https://api.github.com/repos/OWNER/REPO/notifications \
  -d '{
  "last_read_at": "2019-01-01T00:00:00Z"
}'

Response schema (Status: 202):