GitHub v3 REST API

List matching references

Returns an array of references from your Git database that match the supplied name. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn’t exist in the repository, but existing refs start with :ref, they will be returned as an array.

When you use this endpoint without providing a :ref, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags.

Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see “Checking mergeability of pull requests”.

If you request matching references for a branch named feature but the branch feature doesn’t exist, the response can still include other matching head refs that start with the word feature, such as featureA and featureB.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/matching-refs/{ref}

Query Parameters

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

200 application/json

Response

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
get/repos/{owner}/{repo}/git/matching-refs/{ref}
 
200 application/json

Get a reference

Returns a single reference from your Git database. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn’t match an existing ref, a 404 is returned.

Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see “Checking mergeability of pull requests”.

get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/ref/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
get/repos/{owner}/{repo}/git/ref/{ref}
 
application/json

Create a reference

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

post
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/refs

Path Parameters

ownerstringrequired
repostringrequired

Body

application/json
refstringrequired

The name of the fully qualified reference (ie: refs/heads/master). If it doesn’t start with ‘refs’ and have at least two slashes, it will be rejected.

shastringrequired

The SHA1 value for this reference.

keystring

Example:"refs/heads/newbranch"

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
post/repos/{owner}/{repo}/git/refs

Body

{ "ref": "refs/heads/featureA", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd" }
 
application/json

Update a reference

patch
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/refs/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Body

application/json
shastringrequired

The SHA1 value to set this reference to

forceboolean

Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to false will make sure you’re not overwriting work.

Default:false

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
patch/repos/{owner}/{repo}/git/refs/{ref}

Body

{ "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "force": true }
 
application/json

Delete a reference

delete
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/refs/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

Response

delete/repos/{owner}/{repo}/git/refs/{ref}