---
title: Upcoming Changes to Watcher and Star APIs
author_name: technoweenie
---
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.
* `/user/watched` - A list of repositories the current user has starred.
[starring-api]: /v3/activity/starring/
## Phase 1: Add Watchers as Subscriptions
This phase exposes Watchers as "Subscriptions". This is to
keep from clashing with the legacy endpoints. This phase will happen
automatically and will not break your application until Phase 3 starts.
(**UPDATE**: API v3 will continue to support this functionality indefinitely.)
* `/repos/:owner/:repo/subscribers` - A list of users watching the repository.
* `/users/:user/subscriptions` - A list of repositories that a user is watching.
* `/user/subscriptions` - A list of repositories the current user is 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.
* `/user/starred` - A list of repositories the current user has starred.
This is in place _now_ with the current media 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. You should do this now. This
can be verified by checking the `X-GitHub-Media-Type` header on all API
responses.
``` command-line
# Accesses a user's starred repositories.
$ curl https://api.github.com/user/watched \
$ -H "Accept: application/vnd.github.beta+json"
```
-This Phase will be broken once Phase 3 starts. Phase 3 removes all support for
the "beta" media type, and makes the "v3" media type the implicit default
for API requests.
## UPDATE - November 6, 2013
API v3 will continue to officially support the functionality described in Phase 1 above. This functionality will remain intact for the lifetime of API v3.
API v3 will not include Phases 2 and 3 (below). Those phases will likely be part of the next major version of the API. (We have not announced a timeline for the next major version of the API.)
/watchers
API Endpoint/user/starred
to get a user's starred repositories, not
/user/watched
.application/vnd.github.v3+json
# Accesses a user's watched repositories. curl https://api.github.com/user/watched \ -H "Accept: application/vnd.github.v3+json"
/subscribers
API Endpoint.