API¶
Note
Unless otherwise noted all arguments are of the str
type.
API Object¶
CircleCI API Module
copyright: |
|
---|---|
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: - 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_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
andrevision
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: |
|
---|---|
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: - 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.
-
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: |
|
---|---|
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'"¶