Skip to main content

Python wrapper for the CircleCI API

Project description

Python Wrapper around the CircleCI API

Installation requires Python 3. Python 2 will be EOL soon, it’s time to make the switch.

pip install circleci


Basic Usage

Make a new API token in the CircleCI application.

Import the CircleCI API and start using methods:

from circleci.api import Api

circleci = Api("$YOUR_TOKEN")


Usage with CircleCI server

Make a new API token at https://<$YOUR_CIRCLECI_DOMAIN>/account/api.

Import the CircleCI API and start using methods:

from circleci.api import Api

circleci = Api("$YOUR_TOKEN", "$YOUR_CIRCLECI_DOMAIN/api/v1.1")


See the tests for more examples.


  1. Supports the latest v1.1 of the CircleCI API.
  2. Supports both and CircleCI server (aka “Enterprise”).

Experimental Features

WARNING: All methods here work against the UNDOCUMENTED and UNSUPPORTED CircleCI API. Subject to change at any moment. Use at your own risk.

  • Retry a build without cache
from circleci.experimental import Experimental

circleci = Experimental("$YOUR_TOKEN")
circleci.retry_no_cache('$USERNAME', '$PROJECT', '$BUILD_NUMBER')

Sample Output (truncated for readability)

'author_date': '2017-10-24T12:00:27-07:00',
'author_email': '',
'author_name': 'Lev Lazinskiy',
'body': '',
'branch': 'master',
'build_num': 21,
'fail_reason': None,
'failed': None,
'infrastructure_fail': False,
'is_first_green_build': False,
'job_name': None,
'lifecycle': 'scheduled',
'messages': [],


'no_dependency_cache': True,



Your life will be a lot better if you use a virtualenv when working with python.

  1. Fork and Clone this repo
  2. Install python-pip and virtualenv if you do not already have it.
  3. Create a new virtualenv with virtualenv -p python3 env.
  4. Actiavte the new virtualenv with source env/bin/activate.
  5. Run make dev
  6. Hack away!

Running Tests

Tests are stored in the tests/ directory. You can run tests with make test. In order to run the integration tests you must have a valid CIRCLE_TOKEN set as an environment variable.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for circleci, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size circleci-1.1.0-py3-none-any.whl (11.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size circleci-1.1.0.tar.gz (5.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page