---

title: Upcoming Changes to Watcher and Star APIs

---

We recently [changed the Watcher behavior][change-watching] on GitHub. What

used to be known as "Watching", is now "Starring". Starring is basically

a way to bookmark interesting repositories. Watching is a way to indicate that

you want to receive email or web notifications on a Repository.

[change-watching]: https://github.com/blog/1204-notifications-stars

This works well on GitHub.com, but poses a problem for the GitHub API. How do

we change this in a way that developers can gracefully upgrade their

applications? We're currently looking at rolling out the changes in three

phases over an extended period of time.

## Current Status

The current [Repository Starring][starring-api] methods look like this:

* `/repos/:owner/:repo/watchers` - A list of users starring the repository.

* `/users/:user/watched` - A list of repositories that a user has starred.

* `/users/watched` - A list of repositories the current user has starred.

[starring-api]: http://developer.github.com/v3/repos/watching/

## Phase 1: Add Watchers as Subscriptions

In addition to this, we'll expose Watchers as "Subscriptions". This is to

keep from clashing with the legacy endpoint.

* `/repos/:owner/:repo/subscribers` - A list of users watching the repository.

* `/users/subscriptions` - A list of repositories the current user is watching.

Note: we don't plan to expose what other users are watching.

We'll also add a copy of the legacy Watchers API in the new endpoint:

* `/repos/:owner/:repo/stargazers` - A list of users starring the repository.

* `/users/:user/starred` - A list of repositories that a user has starred.

* `/users/starred` - A list of repositories the current user has starred.

This will be done with the current mime type for the API:

application/vnd.github.beta+json

If you care about your application not breaking, make sure all outgoing API

requests pass that value for the "Accept" header.

# Accesses a user's starred repositories.

curl https://api.github.com/users/watched \

-H "Accept: application/vnd.github.beta+json"

## Phase 2: Switch `/watchers` API Endpoint

The "watch" endpoints will now be a copy of the "subscription" endpoints. You

will have to use `/users/starred` to get a user's starred repositories, not

`/users/watched`.

This requires a new mime type value:

application/vnd.github.v3+json

We will release this change in an experimental mode first, letting developers

gracefully upgrade their applications by specifying the new mime value for the

Accept header.

# Accesses a user's watched repositories.

curl https://api.github.com/users/watched \

-H "Accept: application/vnd.github.v3+json"

## Phase 3: Remove `/subscribers` API Endpoint.

This phase involves disabling the subscription endpoints completely. At this

point, you should be using the starring endpoints for starred repositories, and

the watch endpoints for watched repositories.