OAuth2 is a protocol that lets external apps request authorization to private
details in a user's GitHub account without getting their password. This is
preferred over Basic Authentication because tokens can be limited to specific
types of data, and can be revoked by users at any time.
oauth_2_0
Request
Query parameters
access_token (string
) Used to send a valid OAuth 2 access token. Do not use together with
the "Authorization" header
Headers
Authorization: Used to send a valid OAuth 2 access token. Do not use together with
the "access_token" query string parameter.
q (string
) The search terms. This can be any combination of the supported repository
search parameters:
'Search In' Qualifies which fields are searched. With this qualifier you
can restrict the search to just the repository name, description, readme,
or any combination of these.
'Size' Finds repositories that match a certain size (in kilobytes).
'Forks' Filters repositories based on the number of forks, and/or whether
forked repositories should be included in the results at all.
'Created' and 'Last Updated' Filters repositories based on times of
creation, or when they were last updated.
'Users or Repositories' Limits searches to a specific user or repository.
'Languages' Searches repositories based on the language they're written in.
'Stars' Searches repositories based on the number of stars.
sort (string
) If not provided, results are sorted by best match.
q (string
) The search terms. This can be any combination of the supported code
search parameters:
'Search In' Qualifies which fields are searched. With this qualifier
you can restrict the search to just the file contents, the file path,
or both.
'Languages' Searches code based on the language it's written in.
'Forks' Filters repositories based on the number of forks, and/or
whether code from forked repositories should be included in the results
at all.
'Size' Finds files that match a certain size (in bytes).
'Path' Specifies the path that the resulting file must be at.
'Extension' Matches files with a certain extension.
'Users' or 'Repositories' Limits searches to a specific user or repository.
sort (string
) Can only be 'indexed', which indicates how recently a file has been indexed
by the GitHub search infrastructure. If not provided, results are sorted
by best match.
q (string
) The search terms. This can be any combination of the supported user
search parameters:
'Search In' Qualifies which fields are searched. With this qualifier you
can restrict the search to just the username, public email, full name,
location, or any combination of these.
'Repository count' Filters users based on the number of repositories they
have.
'Location' Filter users by the location indicated in their profile.
'Language' Search for users that have repositories that match a certain
language.
'Created' Filter users based on when they joined.
'Followers' Filter users based on the number of followers they have.
sort (string
) If not provided, results are sorted by best match.
List issues.
List all issues across all the authenticated user's visible repositories.
Request
Query parameters
filter (string
) Issues assigned to you / created by you / mentioning you / you're
subscribed to updates for / All issues the authenticated user can see
state (string
)
labels (string
) String list of comma separated Label names. Example - bug,ui,@high.
sort (string
)
direction (string
)
since (string
) Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
Only issues updated at or after this time are returned.
List your notifications.
List all notifications for the current user, grouped by repository.
Request
Query parameters
all (string
) True to show notifications marked as read.
participating (string
) True to show only notifications in which the user is directly participating
or mentioned.
since (string
) 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
Http Status code
200
Content-Type: application/json
Example
Schema
PUT
/notifications
Description
Mark as read.
Marking a notification as "read" removes it from the default view on GitHub.com.
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).
List issues.
List all issues for a given organization for the authenticated user.
Request
Uri Parameters
orgId (integer
) Id of organisation.
Query parameters
filter (string
) Issues assigned to you / created by you / mentioning you / you're
subscribed to updates for / All issues the authenticated user can see
state (string
)
labels (string
) String list of comma separated Label names. Example - bug,ui,@high.
sort (string
)
direction (string
)
since (string
) Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
Only issues updated at or after this time are returned.
Members list.
List all users who are members of an organization. A member is a user that
belongs to at least 1 team in the organization. If the authenticated user
is also an owner of this organization then both concealed and public members
will be returned. If the requester is not an owner of the organization the
query will be redirected to the public members list.
Request
Uri Parameters
orgId (integer
) Id of organisation.
Response
Http Status code
200
Content-Type: application/json
Example
Schema
Http Status code
302
Response if requester is not an organization member.
Remove a member.
Removing a user from this list will remove them from all teams and they
will no longer have any access to the organization's repositories.
Get team member.
In order to get if a user is a member of a team, the authenticated user must
be a member of the team.
Request
Uri Parameters
userId (integer
) Id of a member.
teamsId (integer
) Id of a team.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Http Status code
204
User is a member.
Http Status code
404
User is not a member.
PUT
/teams/{teamsId}/members/{userId}
Description
Add team member.
In order to add a user to a team, the authenticated user must have 'admin'
permissions to the team or be an owner of the org that the team is associated
with.
Request
Uri Parameters
userId (integer
) Id of a member.
teamsId (integer
) Id of a team.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Http Status code
204
Team member added.
Http Status code
422
If you attempt to add an organization to a team, you will get this.
Content-Type: application/json
Example
Schema
DELETE
/teams/{teamsId}/members/{userId}
Description
Remove team member.
In order to remove a user from a team, the authenticated user must have 'admin'
permissions to the team or be an owner of the org that the team is associated
with.
NOTE This does not delete the user, it just remove them from the team.
Request
Uri Parameters
userId (integer
) Id of a member.
teamsId (integer
) Id of a team.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
List all public repositories.
This provides a dump of every public repository, in the order that they
were created.
Note: Pagination is powered exclusively by the since parameter. is the
Link header to get the URL for the next page of repositories.
Secured by null
Secured by oauth_2_0
Request
Query parameters
since (string
) The integer ID of the last Repository that you've seen.
access_token (string
) Used to send a valid OAuth 2 access token. Do not use together with
the "Authorization" header
Headers
Authorization: Used to send a valid OAuth 2 access token. Do not use together with
the "access_token" query string parameter.
List languages.
List languages for the specified repository. The value on the right of a
language is the number of bytes of code written in that language.
Get a Blob.
Since blobs can be any arbitrary binary data, the input and responses for
the blob API takes an encoding parameter that can be either utf-8 or
base64. If your data cannot be losslessly sent as a UTF-8 string, you can
base64 encode it.
Create a Tag Object.
Note that creating a tag object does not create the reference that makes a
tag in Git. If you want to create an annotated tag in Git, you have to do
this call to create the tag object, and then create the refs/tags/[tag]
reference. If you want to create a lightweight tag, you only have to create
the tag reference - this call would be unnecessary.
Create a Tree.
The tree creation API will take nested entries as well. If both a tree and
a nested path modifying that tree are specified, it will overwrite the
contents of that tree with the new path contents and write a new tree out.
filter (string
) Issues assigned to you / created by you / mentioning you / you're
subscribed to updates for / All issues the authenticated user can see
state (string
)
labels (string
) String list of comma separated Label names. Example - bug,ui,@high.
sort (string
)
direction (string
)
since (string
) Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
Only issues updated at or after this time are returned.
Response
Http Status code
200
Content-Type: application/json
Example
Schema
POST
/repos/{ownerId}/{repoId}/issues
Description
Create an issue.
Any user with pull access to a repository can create an issue.
List your notifications in a repository
List all notifications for the current user.
Request
Uri Parameters
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Query parameters
all (string
) True to show notifications marked as read.
participating (string
) True to show only notifications in which the user is directly participating
or mentioned.
since (string
) 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
Http Status code
200
Content-Type: application/json
Example
Schema
PUT
/repos/{ownerId}/{repoId}/notifications
Description
Mark notifications as read in a repository.
Marking all notifications in a repository as "read" removes them from the
default view on GitHub.com.
Create a comment.
description: |
Alternative Input.
Instead of passing commit_id, path, and position you can reply to an
existing Pull Request Comment like this:
body
Required string
in_reply_to
Required number - Comment id to reply to.
List.
When authenticating as an organization owner of an organization-owned
repository, all organization owners are included in the list of
collaborators. Otherwise, only users with access to the repository are
returned in the collaborators list.
Get contents.
This method returns the contents of a file or directory in a repository.
Files and symlinks support a custom media type for getting the raw content.
Directories and submodules do not support custom media types.
Note: This API supports files up to 1 megabyte in size.
Here can be many outcomes. For details see "http://developer.github.com/v3/repos/contents/"
Request
Uri Parameters
path (string
)
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Query parameters
path (string
) The content path.
ref (string
) The String name of the Commit/Branch/Tag. Defaults to 'master'.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Http Status code
200
Content-Type: application/json
Example
Schema
PUT
/repos/{ownerId}/{repoId}/contents/{path}
Description
Create a file.
Request
Uri Parameters
path (string
)
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Content-Type: application/json
Body
Schema
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Http Status code
200
Content-Type: application/json
Example
Schema
DELETE
/repos/{ownerId}/{repoId}/contents/{path}
Description
Delete a file.
This method deletes a file in a repository.
Request
Uri Parameters
path (string
)
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Content-Type: application/json
Body
Schema
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Get archive link.
This method will return a 302 to a URL to download a tarball or zipball
archive for a repository. Please make sure your HTTP framework is
configured to follow redirects or you will need to use the Location header
to make a second GET request.
Note: For private repositories, these links are temporary and expire quickly.
Request
Uri Parameters
archive_format (string
)
path (string
) Valid Git reference, defaults to 'master'.
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Create a new download (Part 1: Create the resource).
For part 2 see http://developer.github.com/v3/repos/downloads/#create-a-new-download-part-2-upload-file-to-s3
Create a fork.
Forking a Repository happens asynchronously. Therefore, you may have to wait
a short period before accessing the git objects. If this takes longer than 5
minutes, be sure to contact Support.
Test a push hook.
This will trigger the hook with the latest push to the current repository
if the hook is subscribed to push events. If the hook is not subscribed
to push events, the server will respond with 204 but no test POST will
be generated.
Note: Previously /repos/:owner/:repo/hooks/:id/test
Request
Uri Parameters
hookId (integer
) Id of the hook.
ownerId (integer
) Id of the owner.
repoId (integer
) Id of repository.
Headers
X-GitHub-Media-Type: You can check the current version of media type in responses.
Accept: Is used to set specified media type.
X-RateLimit-Limit:
X-RateLimit-Remaining:
X-RateLimit-Reset:
X-GitHub-Request-Id:
Response
Http Status code
403
API rate limit exceeded. See http://developer.github.com/v3/#rate-limiting
for details.
Get the last year of commit activity data.
Returns the last year of commit activity grouped by week. The days array
is a group of commits per day, starting on Sunday.
Get the number of commits per hour in each day.
Each array contains the day number, hour number, and number of commits
0-6 Sunday - Saturday
0-23 Hour of day
Number of commits
For example, [2, 14, 25] indicates that there were 25 total commits, during
the 2.00pm hour on Tuesdays. All times are based on the time zone of
individual commits.
List events performed by a user.
If you are authenticated as the given user, you will see your private events.
Otherwise, you'll only see public events.
List email addresses for a user.
In the final version of the API, this method will return an array of hashes
with extended information for each email address indicating if the address
has been verified and if it's the user's primary email address for GitHub.
Until API v3 is finalized, use the application/vnd.github.v3 media type to
get other response format.
Request
Response
Http Status code
200
Content-Type: application/json
Example
Schema
POST
/user/emails
Description
Add email address(es).
You can post a single email address or an array of addresses.
Request
Response
DELETE
/user/emails
Description
Delete email address(es).
You can include a single email address or an array of addresses.
List your public keys.
Lists the current user's keys. Management of public keys via the API requires
that you are authenticated through basic auth, or OAuth with the 'user' scope.
List issues.
List all issues across owned and member repositories for the authenticated
user.
Request
Query parameters
filter (string
) Issues assigned to you / created by you / mentioning you / you're
subscribed to updates for / All issues the authenticated user can see
state (string
)
labels (string
) String list of comma separated Label names. Example - bug,ui,@high.
sort (string
)
direction (string
)
since (string
) Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
Only issues updated at or after this time are returned.
List repositories for the authenticated user. Note that this does not include
repositories owned by organizations which the user can access. You can list
user organizations and list organization repositories separately.
Request
Query parameters
type (string
)
Response
Http Status code
200
Content-Type: application/json
Example
Schema
POST
/user/repos
Description
Create a new repository for the authenticated user. OAuth users must supply
repo scope.
Get all users.
This provides a dump of every user, in the order that they signed up for GitHub.
Note: Pagination is powered exclusively by the since parameter. Use the Link
header to get the URL for the next page of users.
Request
Query parameters
since (integer
) The integer ID of the last User that you've seen.