API Docs

REST API for automation of common tasks for debian, rpm, rubygems, and python packages.

Getting Started

Important Info

Before getting started there are a handful of important things to know:

  1. All API requests must be made over HTTPS. There is no plain-text HTTP support.
  2. Most API requests are authenticated using an API token. API tokens are supplied to the API via HTTP basic authentication. Provide your API token as the username and leave the password empty. The APIs which are not authenicated in this way will be marked explicitly as so below.
  3. The API is versioned. This document describes v1 and the URLs start with https://packagecloud.io/api/v1/.

HTTP Response Codes

HTTP Response codes returned by the API:

  • 200 OK
    An API request was successfully processed.
  • 201 Created
    An API request was successfully processed and a new resource was created.
  • 401 Unauthorized
    The username and password are incorrect or when the API token used for a request is invalid.
  • 404 Not Found
    The specified API resource was not found.
  • 422 Unprocessable Entity
    A parameter to the API was provided but was unexpected, malformed, not supported, or otherwise invalid. The response will be a JSON object mapping the erroneous field name to error message(s).

Error responses have a JSON body with a human readable string with a more detailed error explanation.

API Client Libraries

Our client libraries are open sourced on our GitHub account. We gladly accept pull requests and appreciate any issues being filed against the GitHub repositories.

Ruby

https://github.com/computology/packagecloud-ruby

Java

https://github.com/computology/io.packagecloud.client

Go

https://github.com/mlafeldt/pkgcloud

https://github.com/edwarnicke/pkgcloud

Pagination

Any endpoint returning a list of things (like the Search, Versions and Packages API) uses the following headers for pagination information:

  • Link: Links for the next, previous and last page, according to the proposed RFC-5988 standard for Web linking. Example:
    Link:
         <https://packagecloud.io/api/v1/repos/julio/test/packages.json?page=5>; rel="last",
         <https://packagecloud.io/api/v1/repos/julio/test/packages.json?page=2>; rel="next"
  • Total: How many items exist in the total collection.
  • Per-Page: How many items are rendered in this response.
  • Max-Per-Page: Maximum number of items that can be returned per page.

Note: pass a ?per_page parameter to restrict how many items are returned per page. Default is 30. Any per_page parameter greater than Max-Per-Page will be ignored and the maximum set of items allowed per page will be returned instead.

API Tokens


In order to interact with the API, you will need to first obtain your access token. If you login, your token will appear on this page.

All API requests must contain a valid API token in the username field of HTTP basic authentication. For example, a request to the distributions endpoint would look like this: 

curl https://somevalidapitoken:@packagecloud.io/api/v1/distributions

A request with a missing or invalid API token will result in a 401 Unauthorized response.

This token can also be retrieved programmatically via an API request which must be authenticated with your the email address and password associated with your packagecloud account.

To retrieve your token programmatically, you can make the following API call: 

GET https://email:password@packagecloud.io/api/v1/token.json

An example CURL request: 

curl "https://hi%40hi.com:Asdd45VvaarT4591@packagecloud.io/api/v1/token.json"

Parameters:

  • email must be your packagecloud account email address.
  • password must be your packagecloud password

Be sure to URL encode your username and password.

Responses

If successful, you will receive 200 OK response and the response body will be JSON hash mapping the key token to your API token.

An example response:

{"token":"f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0"}

You will use this API token for making all other API requests.

If unsuccessful, you will receive 401 Unauthorized and the error response body will be a JSON hash containing the key error whose value is a string describing the error in more detail.

An example error response:

{"error":"Unauthenticated"}

distributions

index

GET /api/v1/distributions

Response:

Hash<String, Distribution> The response will be a JSON hash with the keys "deb", "dsc", and "rpm" whose values will be an array of hashes describing each distribution. This distribution hash will have an key called "versions" whose value is an array of JSON hashes describing each version of a particular Linux distribution which supports the package type.

Example request(s):

curl https://packagecloud.io/api/v1/distributions.json

Example response:

{
  "deb": [
      {
          "display_name": "Ubuntu",
          "index_name": "ubuntu",
          "versions": [
              {
                  "id": 4,
                  "display_name": "5.10 Breezy Badger",
                  "index_name": "breezy"
              },
              {
                  "id": 5,
                  "display_name": "6.06 LTS Dapper Drake",
                  "index_name": "dapper"
              },
              {
                  "id": 6,
                  "display_name": "6.10 Edgy Eft",
                  "index_name": "edgy"
              },
          ]
      },
      {
          "display_name": "Debian",
          "index_name": "debian",
          "versions": [
              {
                  "id": 22,
                  "display_name": "4.0 etch",
                  "index_name": "etch"
              },
              ...
          ]
       },
    ...
  ]
}

gpg_keys

index

List gpg keys for a repository.

GET /api/v1/repos/:user_id/:repo/gpg_keys.json

Response:

Array<GPGKey> An array of GPG key objects that belong to this repository.

Example request(s):

curl https://packagecloud.io/api/v1/repos/username/reponame/gpg_keys.json

Example response:

< HTTP/1.1 200 OK

{
  "gpg_keys" : [
     {
        "self" : "/api/v1/repos/username/reponame/gpg_keys/username-reponame-85D7FBF915DFCBC6.pub.gpg.json",
        "download_url" : "https://packagecloud.io/username/reponame/gpgkey/username-reopname-85D7FBF915DFCBC6.pub.gpg",
        "keytype" : "repo",
        "destroy_url" : "/api/v1/repos/username/reponame/gpg_keys/username-reponame-85D7FBF915DFCBC6.pub.gpg.json",
        "fingerprint" : "26F67F3E5E89BB30DCD7AC6E85D7FBF915DFCBC6",
        "name" : "username-reponame-85D7FBF915DFCBC6.pub.gpg"
     }
  ]
}

create

Create a GPG key.

POST /api/v1/repos/:user_id/:repo/gpg_keys.json

URL Params:

  • :user_id String The username to which the repo belongs.
  • :repo String The name of the repo.
  • gpg_key[keydata] String The GPG key file to use when creating a key.

Response:

GPGKey The newly created GPG key object.

Example request(s):

curl -X POST -F "gpg_key[keydata]=@/path/to/key.gpg" https://packagecloud.io/api/v1/repos/username/reponame/gpg_keys.json

Example response:

{
   "self" : "/api/v1/repos/username/reponame/gpg_keys/username-reopname-85D7FBF915DFCBC6.pub.gpg.json",
   "download_url" : "https://packagecloud.io/username/reponame/gpgkey/username-reopname-85D7FBF915DFCBC6.pub.gpg",
   "fingerprint" : "26F67F3E5E89BB30DCD7AC6E85D7FBF915DFCBC6",
   "keytype" : "package",
   "name" : "username-reponame-85D7FBF915DFCBC6.pub.gpg",
   "destroy_url" : "/api/v1/repos/username/reponame/gpg_keys/username-reponame-85D7FBF915DFCBC6.pub.gpg.json"
}

destroy