|
| 1 | +--- |
| 2 | +kind:change |
| 3 | +title:Notifications API |
| 4 | +created_at:2012-10-26 |
| 5 | +author_name:technoweenie |
| 6 | +--- |
| 7 | + |
| 8 | +Now that the dust has settled around[Notifications and Stars][newsies], |
| 9 | +we've unleashed all that:sparkles: in a[brand new API][api]. You can now |
| 10 | +view and mark notifications as read. |
| 11 | + |
| 12 | +[api]:http://developer.github.com/v3/activity/notifications/ |
| 13 | +[newsies]:https://github.com/blog/1204-notifications-stars |
| 14 | + |
| 15 | +##Endpoint |
| 16 | + |
| 17 | +The core notifications functionality is under the`/notifications` endpoint. |
| 18 | +You can look for unread notifications: |
| 19 | + |
| 20 | +$ curl https://api.github.com/notifications |
| 21 | + |
| 22 | +You can filter these notifications to a single Repository: |
| 23 | + |
| 24 | +$ curl https://api.github.com/repos/technoweenie/faraday/notifications |
| 25 | + |
| 26 | +You can mark them as read: |
| 27 | + |
| 28 | +# all notifications |
| 29 | +$ curl https://api.github.com/notifications \ |
| 30 | + -X PATCH -d '{"read": true}' |
| 31 | + |
| 32 | +# notifications for a single repository |
| 33 | +$ curl https://api.github.com/repos/technoweenie/faraday/notifications \ |
| 34 | + -X PATCH -d '{"read": true}' |
| 35 | + |
| 36 | +You can also modify subscriptions for a Repository or a single thread. |
| 37 | + |
| 38 | +# subscription details for the thread (either an Issue or Commit) |
| 39 | +$ curl https://api.github.com/notifications/threads/1/subscription |
| 40 | + |
| 41 | +# subscription details for a whole Repository. |
| 42 | +$ curl https://api.github.com/repos/technoweenie/faraday/subscription |
| 43 | + |
| 44 | +##Polling |
| 45 | + |
| 46 | +The Notifications API is optimized for polling by the last modified time: |
| 47 | + |
| 48 | +# Add authentication to your requests |
| 49 | +$ curl -I https://api.github.com/notifications |
| 50 | +HTTP/1.1 200 OK |
| 51 | +Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT |
| 52 | +X-Poll-Interval: 60 |
| 53 | + |
| 54 | +# Pass the Last-Modified header exactly |
| 55 | +$ curl -I https://api.github.com/notifications |
| 56 | + -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT" |
| 57 | +HTTP/1.1 304 Not Modified |
| 58 | +X-Poll-Interval: 60 |
| 59 | + |
| 60 | +You can read about the API details in depth in the[Notifications documentation][api]. |
| 61 | + |
| 62 | + |