Explore by product

REST API
English

This version of GitHub Enterprise was discontinued on 2020-11-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Article version: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE
Article version: Enterprise Server 2.19
Free, Pro, and Team Enterprise Server 2.22 Enterprise Server 2.21 Enterprise Server 2.20 Enterprise Server 2.19 GitHub AE

Activity

In this article

Events

The Events API is a read-only API to the GitHub events. These events power the various activity streams on the site.

The Events API can return different types of events triggered by activity on GitHub Enterprise Server. For more information about the specific events that you can receive from the Events API, see "GitHub Event types." An events API for repository issues is also available. For more information, see the "Issue Events API."

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 http(s)://[hostname]/api/v3/users/tater/events
> HTTP/1.1 200 OK
> X-Poll-Interval: 60
> ETag: "a18c3bded88eb5dbb5c849a489412bf3"

# The quotes around the ETag value are important
$ curl -I http(s)://[hostname]/api/v3/users/tater/events \
$    -H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"'
> HTTP/1.1 304 Not Modified
> X-Poll-Interval: 60

Events support 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. For information, see "Traversing with pagination."

Only events created within the past 90 days will be included in timelines. Events older than 90 days will not be included (even if the total number of events in the timeline is less than 300).

List public events

We delay the public events feed by five minutes, which means the most recent event returned by the public events API actually occurred at least five minutes ago.

get /events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/events
JavaScript (@octokit/core.js) 
await octokit.request('GET /events')

Response

Status: 200 OK

Not modified

Status: 304 Not Modified

Forbidden

Status: 403 Forbidden

Service unavailable

Status: 503 Service Unavailable

Notes

get /networks/{owner}/{repo}/events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/networks/octocat/hello-world/events
JavaScript (@octokit/core.js) 
await octokit.request('GET /networks/{owner}/{repo}/events', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

Status: 200 OK

Moved permanently

Status: 301 Moved Permanently

Not modified

Status: 304 Not Modified

Forbidden

Status: 403 Forbidden

Resource not found

Status: 404 Not Found

Notes

get /orgs/{org}/events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

org string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/events
JavaScript (@octokit/core.js) 
await octokit.request('GET /orgs/{org}/events', {
  org: 'org'
})

Response

Status: 200 OK

Notes

get /repos/{owner}/{repo}/events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

owner string path
repo string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/events
JavaScript (@octokit/core.js) 
await octokit.request('GET /repos/{owner}/{repo}/events', {
  owner: 'octocat',
  repo: 'hello-world'
})

Response

Status: 200 OK

Notes

List events for the authenticated user

If you are authenticated as the given user, you will see your private events. Otherwise, you'll only see public events.

get /users/{username}/events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/events
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/events', {
  username: 'username'
})

Response

Status: 200 OK

Notes

List organization events for the authenticated user

This is the user's organization dashboard. You must be authenticated as the user to view this.

get /users/{username}/events/orgs/{org}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
org string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/events/orgs/ORG
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/events/orgs/{org}', {
  username: 'username',
  org: 'org'
})

Response

Status: 200 OK
get /users/{username}/events/public

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/events/public
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/events/public', {
  username: 'username'
})

Response

Status: 200 OK

Notes

List events received by the authenticated user

These are events that you've received by watching repos and following users. If you are authenticated as the given user, you will see private events. Otherwise, you'll only see public events.

get /users/{username}/received_events

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/received_events
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/received_events', {
  username: 'username'
})

Response

Status: 200 OK

Notes

get /users/{username}/received_events/public

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended.

username string path
per_page integer query

Results per page (max 100)
page integer query

Page number of the results to fetch.

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/users/USERNAME/received_events/public
JavaScript (@octokit/core.js) 
await octokit.request('GET /users/{username}/received_events/public', {
  username: 'username'
})

Response

Status: 200 OK

Notes

Feeds

Get feeds

GitHub Enterprise Server provides several timeline resources in Atom format. The Feeds API lists all the feeds available to the authenticated user:

  • Timeline: The GitHub Enterprise Server global public timeline
  • User: The public timeline for any user, using URI template
  • Current user public: The public timeline for the authenticated user
  • Current user: The private timeline for the authenticated user
  • Current user actor: The private timeline for activity created by the authenticated user
  • Current user organizations: The private timeline for the organizations the authenticated user is a member of.
  • Security advisories: A collection of public announcements that provide information about security-related vulnerabilities in software on GitHub Enterprise Server.

Note: Private feeds are only returned when authenticating via Basic Auth since current feed URIs use the older, non revocable auth tokens.

get /feeds

Code samples

Shell 
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/feeds
JavaScript (@octokit/core.js) 
await octokit.request('GET /feeds')

Default response

Status: 200 OK
{
  "timeline_url": "https://github.com/timeline",
  "user_url": "https://github.com/{user}",
  "current_user_public_url": "https://github.com/octocat",
  "current_user_url": "https://github.com/octocat.private?token=abc123",
  "current_user_actor_url": "https://github.com/octocat.private.actor?token=abc123",
  "current_user_organization_url": "",
  "current_user_organization_urls": [
    "https://github.com/organizations/github/octocat.private.atom?token=abc123"
  ],
  "_links": [
    {
      "timeline": {
        "href": "https://github.com/timeline",
        "type": "application/atom+xml"
      },
      "user": {
        "href": "https://github.com/{user}",
        "type": "application/atom+xml"
      },
      "current_user_public": {
        "href": "https://github.com/octocat",
        "type": "application/atom+xml"
      },
      "current_user": {
        "href": "https://github.com/octocat.private?token=abc123",
        "type": "application/atom+xml"
      },
      "current_user_actor": {
        "href": "https://github.com/octocat.private.actor?token=abc123",
        "type": "application/atom+xml"
      },
      "current_user_organization": {
        "href": "",
        "type": ""
      },
      "current_user_organizations": [
        {
          "href": "https://github.com/organizations/github/octocat.private.atom?token=abc123",
          "type": "application/atom+xml"
        }
      ]
    }
  ]
}

Notes

Example of getting an Atom feed

To get a feed in Atom format, you must specify the application/atom+xml type in the Accept header. For example, to get the Atom feed for GitHub security advisories:

curl -H "Accept: application/atom+xml" https://github.com/security-advisories

Response

Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xml:lang="en-US">
  <id>tag:github.com,2008:/security-advisories</id>
  <link rel="self" type="application/atom+xml" href="https://github.com/security-advisories.atom"/>
  <title>GitHub Security Advisory Feed</title>
  <author>
    <name>GitHub</name>
  </author>
  <updated>2019-01-14T19:34:52Z</updated>
     <entry>
      <id>tag:github.com,2008:GHSA-abcd-12ab-23cd</id>
      <published>2018-07-26T15:14:52Z</published>
      <updated>2019-01-14T19:34:52Z</updated>
      <title type="html">[GHSA-abcd-12ab-23cd] Moderate severity vulnerability that affects Octoapp</title>
        <category term="NPM"/>
      <content type="html">
        &lt;p&gt;Octoapp node module before 4.17.5 suffers from a Modification of Assumed-Immutable Data (MAID) vulnerability via defaultsDeep, merge, and mergeWith functions, which allows a malicious user to modify the prototype of &quot;Object&quot; via &lt;strong&gt;proto&lt;/strong&gt;, causing the addition or modification of an existing property that will exist on all objects.&lt;/p&gt;
          &lt;p&gt;&lt;strong&gt;Affected Packages&lt;/strong&gt;&lt;/p&gt;

  &lt;dl&gt;
      &lt;dt&gt;Octoapp&lt;/dt&gt;
      &lt;dd&gt;Ecosystem: npm&lt;/dd&gt;
      &lt;dd&gt;Severity: moderate&lt;/dd&gt;
      &lt;dd&gt;Versions: &amp;lt; 4.17.5&lt;/dd&gt;
        &lt;dd&gt;Fixed in: 4.17.5&lt;/dd&gt;
  &lt;/dl&gt;

          &lt;p&gt;&lt;strong&gt;References&lt;/strong&gt;&lt;/p&gt;

  &lt;ul&gt;
      &lt;li&gt;https://nvd.nist.gov/vuln/detail/CVE-2018-123&lt;/li&gt;
  &lt;/ul&gt;

      </content>
    </entry>
</feed>

Notifications

Users receive notifications for conversations in repositories they watch including:

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

Notifications are also sent for conversations 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 notifications or repo API scopes. Doing this will give read-only access to some issue and 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, pull request, or 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 http(s)://[hostname]/api/v3/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 http(s)://[hostname]/api/v3/notifications
$    -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
> HTTP/1.1 304 Not Modified
> X-Poll-Interval: 60

Notification reasons

When retrieving responses from the Notifications API, each payload has a key titled reason. These correspond to events that trigger a notification.

Here's a list of potential reasons for receiving a notification:

Reason NameDescription
assignYou were assigned to the issue.
authorYou created the thread.
commentYou commented on the thread.
invitationYou accepted an invitation to contribute to the repository.
manualYou subscribed to the thread (via an issue or pull request).
mentionYou were specifically @mentioned in the content.
review_requestedYou, or a team you're a member of, were requested to review a pull request.
state_change