LFE Docs

Watching

Watching a Repository registers the user to receive notifications on new discussions, as well as events in the user’s activity feed. See Repository Starring for simple repository bookmarks.

Watching vs. Starring

In August 2012, we changed the way watching works on GitHub. At the time of that change, many API clients were already using the existing “watcher” endpoints to access starring data. To avoid breaking those applications, the legacy “watcher” endpoints continue to provide starring data.

To provide access to watching data, the v3 Watcher API uses the “subscription” endpoints described below. Check out the Watcher API Change post for more details.

List watchers

GET /repos/:owner/:repo/subscribers

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "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
  }
]

List repositories being watched

List repositories being watched by a user.

GET /users/:username/subscriptions

List repositories being watched by the authenticated user.

GET /user/subscriptions

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "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",
    "clone_url": "https://github.com/octocat/Hello-World.git",
    "git_url": "git://github.com/octocat/Hello-World.git",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "svn_url": "https://svn.github.com/octocat/Hello-World",
    "mirror_url": "git://git.example.com/octocat/Hello-World",
    "homepage": "https://github.com",
    "language": null,
    "forks_count": 9,
    "stargazers_count": 80,
    "watchers_count": 80,
    "size": 108,
    "default_branch": "master",
    "open_issues_count": 0,
    "has_issues": true,
    "has_wiki": true,
    "has_pages": false,
    "has_downloads": true,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    }
  }
]

Get a Repository Subscription

GET /repos/:owner/:repo/subscription

Response if you are subscribed to the repository

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/repos/octocat/example/subscription",
  "repository_url": "https://api.github.com/repos/octocat/example"
}

Response if you are not subscribed to the repository

Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Set a Repository Subscription

PUT /repos/:owner/:repo/subscription

Parameters

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

If you would like to watch a repository, set subscribed to true. If you would like to ignore notifications made within a repository, set ignored to true. If you would like to stop watching a repository, delete the repository’s subscription completely.

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/repos/octocat/example/subscription",
  "repository_url": "https://api.github.com/repos/octocat/example"
}

Delete a Repository Subscription

This endpoint should only be used to stop watching a repository. To control whether or not you wish to receive notifications from a repository, set the repository’s subscription manually.

DELETE /repos/:owner/:repo/subscription

Response

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

Check if you are watching a repository (LEGACY)

Requires for the user to be authenticated.

GET /user/subscriptions/:owner/:repo

Response if this repository is watched by you

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

Response if this repository is not watched by you

Status: 404 Not Found
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Watch a repository (LEGACY)

Requires the user to be authenticated.

PUT /user/subscriptions/:owner/:repo

Note that you’ll need to set Content-Length to zero when calling out to this endpoint. For more information, see “HTTP verbs.”

Response

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

Stop watching a repository (LEGACY)

Requires for the user to be authenticated.

DELETE /user/subscriptions/:owner/:repo

Response

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