Oct 26, 2012 · Sep 28, 2012 · Oct 2, 2012 · Oct 2, 2012 · Oct 3, 2012 · Oct 9, 2012
diff --git a/content/v3/activity.md b/content/v3/activity.md
 ---
 title:Activity | GitHub API
 ---

 Serving up the 'social' in Social Coding™, the Activity APIs provide access to
 notifications, subscriptions, and timelines.

 ##Notifications

 Notifications of new comments are delivered to users.  The Notifications API
 lets you view these notifications, and mark them as read.

 ##Starring

 Repository Starring is a feature that lets users bookmark repositories.  Stars
 are shown next to repositories to show an approximate level of interest.  Stars
 have no effect on notifications or the activity feed.

 ##Watching

 Watching a Repository registers the user to receive notificactions on new
 discussions, as well as events in the user's activity feed.

 ##Events

 This is a read-only API of the events that power the various activity streams
 on GitHub.

diff --git a/content/v3/events.md → content/v3/activity/events.md b/content/v3/events.md → content/v3/activity/events.md
 * TOC
 {:toc}

 Events are optimized for polling with the "ETag" header.  If no new events have
 been triggered, you will see a "304 Not Modified" response, and your current
 rate limit will be untouched.  There is also 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.

    $ curl -I https://api.github.com/users/tater/events
    HTTP/1.1 200 OK
    X-Poll-Interval: 60
    ETag: "a18c3bded88eb5dbb5c849a489412bf3"

    # The quotes around the ETag value are important
    $ curl -I https://api.github.com/users/tater/events \
        -H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"'
    HTTP/1.1 304 Not Modified
    X-Poll-Interval: 60

 Events support [pagination](/v3/#pagination),
 however the `per_page` option is unsupported. The fixed page size is 30 items.
 Fetching up to ten pages is supported, for a total of 300 events.
diff --git a/content/v3/events/types.md → content/v3/activity/events/types.md b/content/v3/events/types.md → content/v3/activity/events/types.md
diff --git a/content/v3/activity/notifications.md b/content/v3/activity/notifications.md
 ---
 title: Notifications | GitHub API
 ---

 # Notifications API

 * TOC
 {:toc}

 GitHub Notifications are powered by [watched repositories](/v3/repos/watching/).
 Users receive notifications for discussions in repositories they watch
 including:

 * Issues and their comments
 * Pull Requests and their comments
 * Comments on any commits

 Notifications are also sent for discussions in unwatched repositories when the
 user is involved including:

 * **@mentions**
 * Issue assignments
 * Commits the user authors or commits
 * Any discussion in which the user actively participates

 All Notification API calls require the <strong>"notifications"</strong> API
 scope.  Doing this will give read-only access to some Issue/Commit content.
 You will still need the "repo" scope to access Issues and Commits from their
 respective endpoints.

 Notifications come back as "threads".  A Thread contains information about the
 current discussion of an Issue/PullRequest/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/1.1 200 OK
    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/1.1 304 Not Modified
    X-Poll-Interval: 60

 ## List your notifications

 List all notifications for the current user, grouped by repository.

    GET /notifications

 ### Parameters

 all
 : _Optional_ **boolean** `true` to show notifications marked as read.

 participating
 : _Optional_ **boolean** `true` to show only notifications in which the user is
 directly participating or mentioned.

 since
 : _Optional_ **time** filters out any notifications updated before the given
 time.  The time should be passed in as UTC in the ISO 8601 format:
 `YYYY-MM-DDTHH:MM:SSZ`.  Example: "2012-10-09T23:39:01Z".

 ### Response

 <%= headers 200 %>
 <%= json(:thread) { |h| [h] } %>

 ## List your notifications in a repository

 List all notifications for the current user.

    GET /repos/:owner/:repo/notifications

 ### Parameters

 all
 : _Optional_ **boolean** `true` to show notifications marked as read.

 participating
 : _Optional_ **boolean** `true` to show only notifications in which the user is
 directly participating or mentioned.

 since
 : _Optional_ **time** filters out any notifications updated before the given
 time.  The time should be passed in as UTC in the ISO 8601 format:
 `YYYY-MM-DDTHH:MM:SSZ`.  Example: "2012-10-09T23:39:01Z".

 ### Response

 <%= headers 200 %>
 <%= json(:thread) { |h| [h] } %>

 ## Mark as read

 Marking a notification as "read" removes it from the [default view
 on GitHub.com](https://github.com/notifications).

    PUT /notifications

 ### Input

 unread
 : **Boolean** Changes the unread status of the threads.

 read
 : **Boolean** Inverse of "unread".

 last_read_at
 : _Optional_ **Time** Describes the last point that notifications were checked.  Anything
 updated since this time will not be updated.  Default: Now.  Expected in ISO
 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.  Example: "2012-10-09T23:39:01Z".

 ### Response

 <%= headers 205 %>

 ## Mark notifications as read in a repository

 Marking all notifications in a repository as "read" removes them
 from the [default view on GitHub.com](https://github.com/notifications).

    PUT /repos/:owner/:repo/notifications

 ### Input

 unread
 : **Boolean** Changes the unread status of the threads.

 read
 : **Boolean** Inverse of "unread".

 last_read_at
 : _Optional_ **Time** Describes the last point that notifications were checked.  Anything
 updated since this time will not be updated.  Default: Now.  Expected in ISO
 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.  Example: "2012-10-09T23:39:01Z".

 ### Response

 <%= headers 205 %>

 ## View a single thread

    GET /notifications/threads/:id

 ### Response

 <%= headers 200 %>
 <%= json(:thread) { |h| [h] } %>

 ## Mark a thread as read

    PATCH /notifications/threads/:id

 ### Input

 unread
 : **Boolean** Changes the unread status of the threads.

 read
 : **Boolean** Inverse of "unread".

 ### Response

 <%= headers 205 %>

 ## Get a Thread Subscription

 This checks to see if the current user is subscribed to a thread.  You can also
 [get a Repository subscription](http://localhost:3000/v3/activity/watching/#get-a-repository-subscription).

    GET /notifications/threads/1/subscription

 ### Response

 <%= headers 200 %>
 <%= json :subscription %>

 ## Set a Thread Subscription

 This lets you subscribe to a thread, or ignore it.  Subscribing to a thread
 is unnecessary if the user is already subscribed to the repository.  Ignoring
 a thread will mute all future notifications (until you comment or get
 @mentioned).

    PUT /notifications/threads/1/subscription

 ### Input

 subscribed
 : **boolean** Determines if notifications should be received from this
 repository.

 ignored
 : **boolean** Deterimines if all notifications should be blocked from this
 repository.

 ### Response

 <%= headers 200 %>
 <%= json :subscription %>

 ## Delete a Thread Subscription

    DELETE /notifications/threads/1/subscription

 ### Response

 <%= headers 204 %>

diff --git a/content/v3/activity/settings.md b/content/v3/activity/settings.md
 ---
 title: Notification Settings | GitHub API
 ---

 # Notification Settings API

 This API is not implemented.  This documentation is a placeholder for when it
 is ready for public consumption.

 ## View Settings

    GET /notifications/settings

 ## Update Settings

 Update the notification settings for the authenticated user.

    PATCH /notifications/settings

 ### Parameters

 participating.email
 : _Optional_ **boolean** `true` to receive participating notificationsn via
 email.

 participating.web
 : _Optional_ **boolean** `true` to receive participating notificationsn via
 web.

 watching.email
 : _Optional_ **boolean** `true` to receive watching notificationsn via
 email.

 watching.web
 : _Optional_ **boolean** `true` to receive watching notificationsn via
 web.

 <%= json \
  :participating => {:email => true, :web => false},
  :watching => {:email => true, :web => false} %>

 ## Get notification email settings

    GET /notifications/emails

 ## Get the global email settings

    GET /notifications/global/emails

 ## Get notification email settings for an organization

    GET /notifications/organization/:org/emails

 ## Update email settings

    PATCH /notifications/emails

 ## Update global email settings

    PUT /notifications/global/emails

 ### Parameters

 email
 : _Required_ **string** Email address to which to send notifications to the
 authenticated user for discussions related to projects for this organization.

 ## Update Organization email settings

 Update the notification settings for the authenticated user.

    PUT /notifications/organization/:org/emails

 ### Parameters

 email
 : _Required_ **string** Email address to which to send notifications to the
 authenticated user for discussions related to projects for this organization.

diff --git a/content/v3/repos/starring.md → content/v3/activity/starring.md b/content/v3/repos/starring.md → content/v3/activity/starring.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,28 @@
		---
		title:Activity \| GitHub API
		---

		Serving up the 'social' in Social Coding™, the Activity APIs provide access to
		notifications, subscriptions, and timelines.

		##Notifications

		Notifications of new comments are delivered to users. The Notifications API
		lets you view these notifications, and mark them as read.

		##Starring

		Repository Starring is a feature that lets users bookmark repositories. Stars
		are shown next to repositories to show an approximate level of interest. Stars
		have no effect on notifications or the activity feed.

		##Watching

		Watching a Repository registers the user to receive notificactions on new
		discussions, as well as events in the user's activity feed.

		##Events

		This is a read-only API of the events that power the various activity streams
		on GitHub.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,6 +10,23 @@ various activity streams on the site.
		* TOC
		{:toc}

		Events are optimized for polling with the "ETag" header. If no new events have
		been triggered, you will see a "304 Not Modified" response, and your current
		rate limit will be untouched. There is also 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.

		$ curl -I https://api.github.com/users/tater/events
		HTTP/1.1 200 OK
		X-Poll-Interval: 60
		ETag: "a18c3bded88eb5dbb5c849a489412bf3"

		# The quotes around the ETag value are important
		$ curl -I https://api.github.com/users/tater/events \
		-H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"'
		HTTP/1.1 304 Not Modified
		X-Poll-Interval: 60

		Events support [pagination](/v3/#pagination),
		however the `per_page` option is unsupported. The fixed page size is 30 items.
		Fetching up to ten pages is supported, for a total of 300 events.
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,218 @@
		---
		title: Notifications \| GitHub API
		---

		# Notifications API

		* TOC
		{:toc}

		GitHub Notifications are powered by [watched repositories](/v3/repos/watching/).
		Users receive notifications for discussions in repositories they watch
		including:

		* Issues and their comments
		* Pull Requests and their comments
		* Comments on any commits

		Notifications are also sent for discussions in unwatched repositories when the
		user is involved including:

		* @mentions
		* Issue assignments
		* Commits the user authors or commits
		* Any discussion in which the user actively participates

		All Notification API calls require the <strong>"notifications"</strong> API
		scope. Doing this will give read-only access to some Issue/Commit content.
		You will still need the "repo" scope to access Issues and Commits from their
		respective endpoints.

		Notifications come back as "threads". A Thread contains information about the
		current discussion of an Issue/PullRequest/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/1.1 200 OK
		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/1.1 304 Not Modified
		X-Poll-Interval: 60

		## List your notifications

		List all notifications for the current user, grouped by repository.

		GET /notifications
Copy link Contributor pezraOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. It might be better to use a URI template here: `/notifications{?all,participating,since} Copy link ContributorAuthor technoweenieOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Ah dang, I should make all the urls into templates. Thanks for reminding me. Copy link ContributorAuthor technoweenieOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Also, do you prefer parameters or endpoints like`/notifications/all` and`/notifications/participating`? I guess they are technically separate collections.

		### Parameters

		all
		: _Optional_ boolean `true` to show notifications marked as read.

		participating
		: _Optional_ boolean `true` to show only notifications in which the user is
		directly participating or mentioned.

		since
		: _Optional_ time filters out any notifications updated before the given
		time. The time should be passed in as UTC in the ISO 8601 format:
		`YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".

		### Response

		<%= headers 200 %>
		<%= json(:thread) { \|h\| [h] } %>

		## List your notifications in a repository

		List all notifications for the current user.

		GET /repos/:owner/:repo/notifications

		### Parameters

		all
		: _Optional_ boolean `true` to show notifications marked as read.

		participating
		: _Optional_ boolean `true` to show only notifications in which the user is
		directly participating or mentioned.

		since
		: _Optional_ time filters out any notifications updated before the given
		time. The time should be passed in as UTC in the ISO 8601 format:
		`YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".

		### Response

		<%= headers 200 %>
		<%= json(:thread) { \|h\| [h] } %>

		## Mark as read

		Marking a notification as "read" removes it from the [default view
		on GitHub.com](https://github.com/notifications).

		PUT /notifications

		### Input

		unread
		: Boolean Changes the unread status of the threads.

		read
		: Boolean Inverse of "unread".

		last_read_at
		: _Optional_ Time Describes the last point that notifications were checked. Anything
		updated since this time will not be updated. Default: Now. Expected in ISO
		8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".

		### Response

		<%= headers 205 %>

		## Mark notifications as read in a repository

		Marking all notifications in a repository as "read" removes them
		from the [default view on GitHub.com](https://github.com/notifications).

		PUT /repos/:owner/:repo/notifications

		### Input

		unread
		: Boolean Changes the unread status of the threads.

		read
		: Boolean Inverse of "unread".

		last_read_at
		: _Optional_ Time Describes the last point that notifications were checked. Anything
		updated since this time will not be updated. Default: Now. Expected in ISO
		8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".

		### Response

		<%= headers 205 %>

		## View a single thread

		GET /notifications/threads/:id

		### Response

		<%= headers 200 %>
		<%= json(:thread) { \|h\| [h] } %>

		## Mark a thread as read

		PATCH /notifications/threads/:id

		### Input

		unread
		: Boolean Changes the unread status of the threads.

		read
		: Boolean Inverse of "unread".

		### Response

		<%= headers 205 %>

		## Get a Thread Subscription

		This checks to see if the current user is subscribed to a thread. You can also
		[get a Repository subscription](http://localhost:3000/v3/activity/watching/#get-a-repository-subscription).

		GET /notifications/threads/1/subscription

		### Response

		<%= headers 200 %>
		<%= json :subscription %>

		## Set a Thread Subscription

		This lets you subscribe to a thread, or ignore it. Subscribing to a thread
		is unnecessary if the user is already subscribed to the repository. Ignoring
		a thread will mute all future notifications (until you comment or get
		@mentioned).

		PUT /notifications/threads/1/subscription

		### Input

		subscribed
		: boolean Determines if notifications should be received from this
		repository.

		ignored
		: boolean Deterimines if all notifications should be blocked from this
		repository.

		### Response

		<%= headers 200 %>
		<%= json :subscription %>

		## Delete a Thread Subscription

		DELETE /notifications/threads/1/subscription

		### Response

		<%= headers 204 %>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,79 @@
		---
		title: Notification Settings \| GitHub API
		---

		# Notification Settings API

		This API is not implemented. This documentation is a placeholder for when it
		is ready for public consumption.

		## View Settings

		GET /notifications/settings

		## Update Settings

		Update the notification settings for the authenticated user.

		PATCH /notifications/settings
Copy link Contributor pezraOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I think`PUT` would be a better method for this. Even if we don't want clients to have to send the full representation we should still use`PUT`. A PUT w/o a complete long form representation is not a "partial put" unless the server is unable to take that representation and convert it into the full representation using the existing state of the system in an idempotent manner. So PUTs with a range header are partial and not ok because if you repeat them they are not idempotent. PUTs with a "lite" representation of the resource arenot partial puts, even though that "lite" representation does not include all the resource information. Copy link ContributorAuthor technoweenieOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Well, we use PATCH everywhere else. Had a big discussion internally and on Twitter back when I was designing the API. Seems like a difference in the vague specs are interpreted. At least for now, I think going with PATCH for consistency is best. Copy link Contributor pezraOct 25, 2012 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. probably, i just hate patch so much fo this type of use case.

		### Parameters

		participating.email
		: _Optional_ boolean `true` to receive participating notificationsn via
		email.

		participating.web
		: _Optional_ boolean `true` to receive participating notificationsn via
		web.

		watching.email
		: _Optional_ boolean `true` to receive watching notificationsn via
		email.

		watching.web
		: _Optional_ boolean `true` to receive watching notificationsn via
		web.

		<%= json \
		:participating => {:email => true, :web => false},
		:watching => {:email => true, :web => false} %>

		## Get notification email settings

		GET /notifications/emails

		## Get the global email settings

		GET /notifications/global/emails

		## Get notification email settings for an organization

		GET /notifications/organization/:org/emails

		## Update email settings

		PATCH /notifications/emails

		## Update global email settings

		PUT /notifications/global/emails

		### Parameters

		email
		: _Required_ string Email address to which to send notifications to the
		authenticated user for discussions related to projects for this organization.

		## Update Organization email settings

		Update the notification settings for the authenticated user.

		PUT /notifications/organization/:org/emails

		### Parameters

		email
		: _Required_ string Email address to which to send notifications to the
		authenticated user for discussions related to projects for this organization.