refstring
The name of the commit/branch/tag. Default: the repository’s default branch (usually master)
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
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
List repository contributors
Lists contributors to the specified repository and sorts them by the number of commits per contributor in descending order. This endpoint may return information that is a few hours old because the GitHub REST API v3 caches contributor data to improve performance.
GitHub identifies contributors by author email address. This endpoint groups contribution counts by GitHub user, which includes all associated email addresses. To improve performance, only the first 500 author email addresses in the repository link to GitHub users. The rest will appear as anonymous contributors without associated GitHub user information.
get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/contributors
Query Parameters
anonstring
Set to 1 or true to include anonymous contributors in results.
per_pageinteger
Results per page (max 100)
Default:30
pageinteger
Page number of the results to fetch.
Default:1
Path Parameters
ownerstringrequired
repostringrequired
Response
application/json
Response
application/json
if repository contains content
Contributor
loginstring
idinteger
node_idstring
avatar_urlstring(uri)
gravatar_idstring | null
urlstring(uri)
html_urlstring(uri)
followers_urlstring(uri)
following_urlstring
gists_urlstring
starred_urlstring
subscriptions_urlstring(uri)
organizations_urlstring(uri)
repos_urlstring(uri)
events_urlstring
received_events_urlstring(uri)
typestringrequired
site_adminboolean
contributionsintegerrequired
emailstring
namestring
get/repos/{owner}/{repo}/contributors
Path Parameters
Query Parameters
application/json
List deployments
Simple filtering of deployments is available via query parameters:
get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/deployments
Query Parameters
shastring
The SHA recorded at creation time.
Default:none
refstring
The name of the ref. This can be a branch, tag, or SHA.
Default:none
taskstring
The name of the task for the deployment (e.g., deploy or deploy:migrations).
Default:none
environmentstring | null
The name of the environment that was deployed to (e.g., staging or production).
Default:none
per_pageinteger
Results per page (max 100)
Default:30
pageinteger
Page number of the results to fetch.
Default:1
Path Parameters
ownerstringrequired
repostringrequired
Response
200 application/json
Response
200 application/json
Response
A request for a specific ref(branch,sha,tag) to be deployed
urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1
idintegerrequired
Unique identifier of the deployment
Example:42
node_idstringrequired
Example:MDEwOkRlcGxveW1lbnQx
shastringrequired
Example:a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d
refstringrequired
The ref to deploy. This can be a branch, tag, or sha.
Example:topic-branch
taskstringrequired
Parameter to specify a task to execute
Example:deploy
payload
One Ofrequired
Variant 1object
* Additional properties are allowed.
original_environmentstring
Example:staging
environmentstringrequired
Name for the target deployment environment.
Example:production
descriptionstring | nullrequired
Example:Deploy request from hubot
creatorobject | nullrequired
Simple User
Show Child Parameters
created_atstring(date-time)required
Example:2012-07-20T01:19:13Z
updated_atstring(date-time)required
Example:2012-07-20T01:19:13Z
statuses_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example/deployments/1/statuses
repository_urlstring(uri)required
Example:https://api.github.com/repos/octocat/example
transient_environmentboolean
Specifies if the given environment is will no longer exist at some point in the future. Default: false.
Example:true
production_environmentboolean
Specifies if the given environment is one that end-users directly interact with. Default: false.
Example:true
performed_via_github_appobject | null
GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.
Show Child Parameters
get/repos/{owner}/{repo}/deployments
Path Parameters
Query Parameters
200 application/json