per_pageinteger
Results per page (max 100)
Default:30
pageinteger
Page number of the results to fetch.
Default:1
List commit statuses for a reference
Users with pull access in a repository can view commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name. Statuses are returned in reverse chronological order. The first status in the list will be the latest one.
This resource is also available via a legacy route: GET /repos/:owner/:repo/statuses/:ref.
get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/commits/{ref}/statuses
Query Parameters
Path Parameters
ownerstringrequired
repostringrequired
refstringrequired
ref parameter
Response
application/json
Response
application/json
Response
The status of a commit.
urlstringrequired
avatar_urlstring | nullrequired
idintegerrequired
node_idstringrequired
statestringrequired
descriptionstringrequired
target_urlstringrequired
contextstringrequired
created_atstringrequired
updated_atstringrequired
creatorobject | nullrequired
Simple User
Show Child Parameters
get/repos/{owner}/{repo}/commits/{ref}/statuses
Path Parameters
Query Parameters
application/json
Compare two commits
The basehead param is comprised of two parts: base and head. Both must be branch names in repo. To compare branches across other repositories in the same network as repo, use the format <USERNAME>:branch.
The response from the API is equivalent to running the git log base..head command; however, commits are returned in chronological order. Pass the appropriate media type to fetch diff and patch formats.
The response also includes details on the files that were changed between the two commits. This includes the status of the change (for example, if a file was added, removed, modified, or renamed), and details of the change itself. For example, files with a renamed status have a previous_filename field showing the previous filename of the file, and files with a modified status have a patch field showing the changes made to the file.
Working with large comparisons
The response will include a comparison of up to 250 commits. If you are working with a larger commit range, you can use the List commits to enumerate all commits in the range.
For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long
to generate. You can typically resolve this error by using a smaller commit range.
Signature verification object
The response will include a verification object that describes the result of verifying the commit’s signature. The following fields are included in the verification object:
| Name | Type | Description |
|---|---|---|
verified |
boolean |
Indicates whether GitHub considers the signature in this commit to be verified. |
reason |
string |
The reason for verified value. Possible values and their meanings are enumerated in table below. |
signature |
string |
The signature that was extracted from the commit. |
payload |
string |
The value that was signed. |
These are the possible values for reason in the verification object:
| Value | Description |
|---|---|
expired_key |
The key that made the signature is expired. |
not_signing_key |
The “signing” flag is not among the usage flags in the GPG key that made the signature. |
gpgverify_error |
There was an error communicating with the signature verification service. |
gpgverify_unavailable |
The signature verification service is currently unavailable. |
unsigned |
The object does not include a signature. |
unknown_signature_type |
A non-PGP signature was found in the commit. |
no_user |
No user was associated with the committer email address in the commit. |
unverified_email |
The committer email address in the commit was associated with a user, but the email address is not verified on her/his account. |
bad_email |
The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
unknown_key |
The key that made the signature has not been registered with any user’s account. |
malformed_signature |
There was an error parsing the signature. |
invalid |
The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
valid |
None of the above errors applied, so the signature is considered to be verified. |
get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/compare/{basehead}
Path Parameters
ownerstringrequired
repostringrequired
baseheadstringrequired
The base branch and head branch to compare. This parameter expects the format {base}...{head}.
Response
application/json
Response
application/json
Response
Commit Comparison
Commit Comparison
urlstring(uri)required
Example:https://api.github.com/repos/octocat/Hello-World/compare/master...topic
html_urlstring(uri)required
Example:https://github.com/octocat/Hello-World/compare/master...topic
permalink_urlstring(uri)required
Example:https://github.com/octocat/Hello-World/compare/octocat:bbcd538c8e72b8c175046e27cc8f907076331401...octocat:0328041d1152db8ae77652d1618a02e57f745f17
diff_urlstring(uri)required
Example:https://github.com/octocat/Hello-World/compare/master...topic.diff
patch_urlstring(uri)required
Example:https://github.com/octocat/Hello-World/compare/master...topic.patch
base_commitobjectrequired
Commit
Show Child Parameters
merge_base_commitobjectrequired
Commit
Show Child Parameters
statusstringrequired
Allowed values:divergedaheadbehindidentical
Example:ahead
ahead_byintegerrequired
Example:4
behind_byintegerrequired
Example:5
total_commitsintegerrequired
Example:6
commitsarray[object]required
Commit
Show Child Parameters
filesarray[object]
Diff Entry
Show Child Parameters
get/repos/{owner}/{repo}/compare/{basehead}
Path Parameters
application/json
Get repository content
Gets the contents of a file or directory in a repository. Specify the file path or directory in :path. If you omit
:path, you will receive the contents of the repository’s root directory. See the description below regarding what the API response includes for directories.
Files and symlinks support a custom media type for
retrieving the raw content or rendered HTML (when supported). All content types support a custom media
type to ensure the content is returned in a consistent
object format.
Note:
- To get a repository’s contents recursively, you can recursively get the tree.
- This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the Git Trees
API. - This API supports files up to 1 megabyte in size.
If the content is a directory
The response will be an array of objects, one object for each item in the directory.
When listing the contents of a directory, submodules have their “type” specified as “file”. Logically, the value
should be “submodule”. This behavior exists in API v3 for backwards compatibility purposes.
In the next major version of the API, the type will be returned as “submodule”.
If the content is a symlink
If the requested :path points to a symlink, and the symlink’s target is a normal file in the repository, then the
API responds with the content of the file (in the format shown in the example. Otherwise, the API responds with an object
describing the symlink itself.
If the content is a submodule
The submodule_git_url identifies the location of the submodule repository, and the sha identifies a specific
commit within the submodule repository. Git uses the given URL when cloning the submodule repository, and checks out
the submodule at that specific commit.
If the submodule repository is not hosted on github.com, the Git URLs (git_url and _links["git"]) and the
github.com URLs (html_url and _links["html"]) will have null values.
get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/contents/{path}
Query Parameters
refstring
The name of the commit/branch/tag. Default: the repository’s default branch (usually master)
Path Parameters
ownerstringrequired
repostringrequired
pathstringrequired
path parameter
Response
Response
Response
Content Tree
Content Tree
typestringrequired
sizeintegerrequired
namestringrequired
pathstringrequired
shastringrequired
urlstring(uri)required
git_urlstring | null(uri)required
html_urlstring | null(uri)required
download_urlstring | null(uri)required
entriesarray[object]
Show Child Parameters
_linksobjectrequired
Show Child Parameters
get/repos/{owner}/{repo}/contents/{path}
Path Parameters
Query Parameters
Create or update file contents
Creates a new file or replaces an existing file in a repository.
put
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/contents/{path}
Path Parameters
ownerstringrequired
repostringrequired
pathstringrequired
path parameter
Body
application/json
Body
application/json
messagestringrequired
The commit message.
contentstringrequired
The new file content, using Base64 encoding.
shastring
Required if you are updating a file. The blob SHA of the file being replaced.
branchstring
The branch name. Default: the repository’s default branch (usually master)
committerobject
The person that committed the file. Default: the authenticated user.
Show Child Parameters
authorobject
The author of the file. Default: The committer or the authenticated user if you omit committer.
Show Child Parameters
Response
application/json
Response
application/json
Response
File Commit
File Commit
contentobject | nullrequired
Show Child Parameters
commitobjectrequired
Show Child Parameters
put/repos/{owner}/{repo}/contents/{path}
Path Parameters
Body
{
"message": "my commit message",
"committer": {
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}
application/json
Delete a file
Deletes a file in a repository.
You can provide an additional committer parameter, which is an object containing information about the committer. Or, you can provide an author parameter, which is an object containing information about the author.
The author section is optional and is filled in with the committer information if omitted. If the committer information is omitted, the authenticated user’s information is used.
You must provide values for both name and email, whether you choose to use author or committer. Otherwise, you’ll receive a 422 status code.
delete
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/contents/{path}
Path Parameters
ownerstringrequired
repostringrequired
pathstringrequired
path parameter
Body
application/json
Body
application/json
messagestringrequired
The commit message.
shastringrequired
The blob SHA of the file being replaced.
branchstring
The branch name. Default: the repository’s default branch (usually master)
committerobject
object containing information about the committer.
Show Child Parameters
authorobject
object containing information about the author.
Show Child Parameters
Response
application/json
Response
application/json
Response
File Commit
File Commit
contentobject | nullrequired
Show Child Parameters
commitobjectrequired
Show Child Parameters
delete/repos/{owner}/{repo}/contents/{path}
Path Parameters
Body
{
"message": "my commit message",
"committer": {
"name": "Monalisa Octocat",
"email": "octocat@github.com"
},
"sha": "329688480d39049927147c162b9d2deaf885005f"
}
application/json