API

Note

Unless otherwise noted all arguments are of the str type.

API Object

CircleCI API Module

copyright:
  1. 2017 by Lev Lazinskiy
license:

MIT, see LICENSE for more details.

class circleci.api.Api(token, url='https://circleci.com/api/v1.1')

A python interface into the CircleCI API

Instantiate a new circleci.Api object.

Parameters:
_download(url, destdir=None, filename=None)

File download helper.

Parameters:
  • url – The URL to the artifact.
  • destdir – The optional destination directory. Defaults to None (curent working directory).
  • filename – Optional file name. Defaults to the name of the artifact file.
_request(verb, endpoint, data=None)

Request a url.

Parameters:
  • endpoint – The api endpoint we want to call.
  • verb – POST, GET, or DELETE.
  • params (dict) – Optional build parameters.
Raises:

requests.exceptions.HTTPError – When response code is not successful.

Returns:

A JSON object with the response from the API.

add_envvar(username, project, name, value, vcs_type='github')

Adds an environment variable to a project

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • name – Name of the environment variable.
  • value – Value of the environment variable.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/envvar
add_heroku_key(apikey)

Adds your Heroku API key to CircleCI

Parameters:apikey – Heroku API key.
Endpoint:
POST: /user/heroku-key
add_ssh_key(username, project, ssh_key, vcs_type='github', hostname=None)

Create an ssh key

Used to access external systems that require SSH key-based authentication.

Note

The ssh_key must be unencrypted.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • branch – Defaults to master.
  • ssh_key – Private RSA key.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
  • hostname – Optional hostname. If set, the key will only work for this hostname.
Endpoint:
POST: /project/:vcs-type/:username/:project/ssh-key
add_ssh_user(username, project, build_num, vcs_type='github')

Adds a user to the build’s SSH permissions.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/:build_num/ssh-users
cancel_build(username, project, build_num, vcs_type='github')

Cancels the build.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/:build_num/cancel
clear_cache(username, project, vcs_type='github')

Clear cache for a project

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
DELETE: /project/:vcs-type/:username/:project/build-cache
create_checkout_key(username, project, key_type, vcs_type='github')

Create a new checkout keys for a project

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • key_type – The type of key to create. Valid values are ‘deploy-key’ or ‘github-user-key’
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Raises:

InvalidKeyError – When key_type is not a valid key type.

Endpoint:
POST: /project/:vcs-type/:username/:project/checkout-key
delete_checkout_key(username, project, fingerprint, vcs_type='github')

Delete a checkout key.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • fingerprint – The fingerprint of the checkout key.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
DELETE: /project/:vcs-type/:username/:project/checkout-key/:fingerprint
delete_envvar(username, project, name, vcs_type='github')

Delete an environment variable

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • name – Name of the environment variable.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
DELETE /project/:vcs-type/:username/:project/envvar/:name
download_artifact(url, destdir=None, filename=None)

Download an artifact from a url

Parameters:
  • url – The URL to the artifact.
  • destdir – The optional destination directory. Defaults to None (curent working directory).
  • filename – Optional file name. Defaults to the name of the artifact file.
follow_project(username, project, vcs_type='github')

Follow a new project on CircleCI.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/follow
get_artifacts(username, project, build_num, vcs_type='github')

List the artifacts produced by a given build.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: /project/:vcs-type/:username/:project/:build_num/artifacts
get_build_info(username, project, build_num, vcs_type='github')

Full details for a single build.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: /project/:vcs-type/:username/:project/:build_num
get_checkout_key(username, project, fingerprint, vcs_type='github')

Get a checkout key.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • fingerprint – The fingerprint of the checkout key.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: /project/:vcs-type/:username/:project/checkout-key/:fingerprint
get_envvar(username, project, name, vcs_type='github')

Gets the hidden value of an environment variable

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • name – Name of the environment variable.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET /project/:vcs-type/:username/:project/envvar/:name
get_latest_artifact(username, project, branch=None, status_filter='completed', vcs_type='github')

List the artifacts produced by the latest build on a given branch.

Note

This endpoint is a little bit flakey. If the “latest” build does not have any artifacts, rathern than returning an empty set, the API will 404.

Parameters:
  • username – org or user name
  • project – case sensitive repo name
  • branch – The branch you would like to look in for the latest build. Returns artifacts for latest build in entire project if omitted.
  • filter – Restricts which builds are returned. defaults to ‘completed’ valid filters: “completed”, “successful”, “failed”
  • vcs_type – defaults to github on circleci.com you can also pass in bitbucket
Raises:

InvalidFilterError – when filter is not a valid filter.

Endpoint:
GET: /project/:vcs-type/:username/:project/latest/artifacts
get_project_build_summary(username, project, limit=30, offset=0, status_filter=None, branch=None, vcs_type='github')

Build summary for each of the last 30 builds for a single git repo.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • limit (int) – The number of builds to return. Maximum 100, defaults to 30.
  • offset (int) – The API returns builds starting from this offset, defaults to 0.
  • status_filter – Restricts which builds are returned. Set to “completed”, “successful”, “running” or “failed”. Defaults to no filter.
  • branch – Narrow returned builds to a single branch.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Raises:

InvalidFilterError – when filter is not a valid filter.

Endpoint:
GET: /project/:vcs-type/:username/:project
get_projects()

List of all the projects you’re following on CircleCI.

Endpoint:
GET: /projects
get_recent_builds(limit=30, offset=0)

Build summary for each of the last 30 recent builds, ordered by build_num.

Parameters:
  • limit (int) – The number of builds to return. Maximum 100, defaults to 30.
  • offset (int) – The API returns builds starting from this offset, defaults to 0.
Endpoint:
GET: /recent-builds
get_test_metadata(username, project, build_num, vcs_type='github')

Provides test metadata for a build

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: /project/:vcs-type/:username/:project/:build_num/tests
get_user_info()

Provides information about the signed in user.

Endpoint:
GET: /me
list_checkout_keys(username, project, vcs_type='github')

List checkout keys for a project

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: project/:vcs-type/:username/:project/checkout-key
list_envvars(username, project, vcs_type='github')

Provides list of environment variables for a project

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
GET: /project/:vcs-type/:username/:project/envvar
retry_build(username, project, build_num, ssh=False, vcs_type='github')

Retries the build.

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num – Build number.
  • ssh (bool) – Retry a build with SSH enabled. Defaults to False.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/:build_num/retry
trigger_build(username, project, branch='master', revision=None, tag=None, parallel=None, params=None, vcs_type='github')

Triggers a new build.

Note

  • tag and revision are mutually exclusive.
  • parallel is ignored for builds running on CircleCI 2.0
Parameters:
  • username – Organization or user name.
  • project – Case sensitive repo name.
  • branch – The branch to build. Defaults to master.
  • revision – The specific git revision to build. Default is null and the head of the branch is used. Can not be used with the tag parameter.
  • tag – The git tag to build. Default is null. Cannot be used with the tag parameter.
  • parallel (int) – The number of containers to use to run the build. Default is null and the project default is used.
  • params (dict) – Optional build parameters.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: project/:vcs-type/:username/:project/tree/:branch

Experimental API Object

CircleCI Experimental API Module

Warning

All methods here work against undocumented and unsupported aspects of the CircleCI API. Subject to change at any moment. Use at your own risk.

copyright:
  1. 2017 by Lev Lazinskiy
license:

MIT, see LICENSE for more details.

class circleci.experimental.Experimental(token, url='https://circleci.com/api/v1.1')

Experimantal CircleCI API

Instantiate a new circleci.Api object.

Parameters:
retry_no_cache(username, project, build_num, vcs_type='github')

Retries a build without cache

Parameters:
  • username – Org or user name.
  • project – Case sensitive repo name.
  • build_num (int) – Build number.
  • vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.
Endpoint:
POST: /project/:vcs-type/:username/:project/:build_num/retry

Errors

CircleCI API Error Module

copyright:
  1. 2017 by Lev Lazinskiy
license:

MIT, see LICENSE for more details

class circleci.error.CircleCIException(argument)

Base class for CircleCI exceptions

Parameters:argument – The argument that was passed into the function.
class circleci.error.BadVerbError(argument)

Exception raises for bad HTTP verb

Parameters:argument – The argument that was passed into the function.
message = "verb must be one of 'GET', 'POST', or 'DELETE'"
class circleci.error.BadKeyError(argument)

Exception raises for bad Key Type

Parameters:argument – The argument that was passed into the function.
message = "key must be one of 'deploy-key' or 'github-user-key'"
class circleci.error.InvalidFilterError(argument, filter_type)

Exception raises for an invalid filter

Parameters:
  • argument – The argument that was passed into the function.
  • filter_type – Filter for status or artifacts.
filter_message = "status_filter must be one of 'completed''successful', 'failed', or 'running'"
artifacts_message = "must be one of 'completed', 'successful', or 'failed'"