API

Note

Unless otherwise noted all arguments are of the str type.

API Object

circleci.api

This module provides a class which abstracts the CircleCI REST API.

Changed in version 2.0.0: Removed legacy 1.0 endpoints. See CHANGELOG 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:

• url – The URL to the CircleCI instance. Defaults to https://circleci.com/api/v1.1. If you are running CircleCI server, the API is available at the same endpoint of your own installation url. i.e (https://circleci.yourcompany.com/api/v1.1).
• token – Your CircleCI API token.

_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_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

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

Errors

circleci.error

This module provides some classes that subclass Exception to provide some useful exceptions for the API wrapper.

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'"