Permalink
Fetching contributors…
Cannot retrieve contributors at this time
357 lines (255 sloc) 10.8 KB
layout title categories description
classic-docs
CircleCI API v1.1 Reference
reference
Using the CircleCI API

The CircleCI API is a fully-featured JSON API that allows you to access all information and trigger all actions in CircleCI. Note: Access to billing functions is only available from the CircleCI application.

CircleCI 1.0 and 2.0 are supported by API version 1.1 as documented in the following sections:

  • TOC {:toc}

Summary

All CircleCI API endpoints begin with "https://circleci.com/api/v1.1/".

GET: /me
Provides information about the signed in user.
GET: /projects
List of all the projects you're following on CircleCI, with build information organized by branch.
POST: /project/:vcs-type/:username/:project/follow
Follow a new project on CircleCI.
GET: /project/:vcs-type/:username/:project
Build summary for each of the last 30 builds for a single git repo.
GET: /recent-builds
Build summary for each of the last 30 recent builds, ordered by build_num.
GET: /project/:vcs-type/:username/:project/:build_num
Full details for a single build. The response includes all of the fields from the build summary. This is also the payload for the [notification webhooks]( {{ site.baseurl }}/1.0/configuration/#notify), in which case this object is the value to a key named 'payload'.
GET: /project/:vcs-type/:username/:project/:build_num/artifacts
List the artifacts produced by a given build.
POST: /project/:vcs-type/:username/:project/:build_num/retry
Retries the build, returns a summary of the new build.
POST: /project/:vcs-type/:username/:project/:build_num/cancel
Cancels the build, returns a summary of the build.
POST: /project/:vcs-type/:username/:project/:build_num/ssh-users
Adds a user to the build's SSH permissions.
POST: /project/:vcs-type/:username/:project/tree/:branch
Triggers a new build, returns a summary of the build. [Optional 1.0 build parameters can be set as well]( {{ site.baseurl }}/1.0/parameterized-builds/) and [Optional 2.0 build parameters]({{ site.baseurl }}/2.0/env-vars/#injecting-environment-variables-with-the-api).
POST: /project/:vcs-type/:username/:project/ssh-key
Create an ssh key used to access external systems that require SSH key-based authentication
GET: /project/:vcs-type/:username/:project/checkout-key
Lists checkout keys.
POST: /project/:vcs-type/:username/:project/checkout-key
Create a new checkout key.
GET: /project/:vcs-type/:username/:project/checkout-key/:fingerprint
Get a checkout key.
DELETE: /project/:vcs-type/:username/:project/checkout-key/:fingerprint
Delete a checkout key.
DELETE: /project/:vcs-type/:username/:project/build-cache
Clears the cache for a project.
POST: /user/heroku-key
Adds your Heroku API key to CircleCI, takes apikey as form param name.

Getting Started

  1. Add an API token from your account dashboard{:rel="nofollow"}.

  2. To test it, View it in your browser{:rel="nofollow"} or call the API using curl:

$ curl https://circleci.com/api/v1.1/me?circle-token=:token


3.  You should see a response like the following:

    ```
{
  "user_key_fingerprint" : null,
  "days_left_in_trial" : -238,
  "plan" : "p16",
  "trial_end" : "2011-12-28T22:02:15Z",
  "basic_email_prefs" : "smart",
  "admin" : true,
  "login" : "pbiggar"
}

Making calls

All API calls are made in the same way, by making standard HTTP calls, using JSON, a content-type, and your API token. All CircleCI API endpoints begin with "https://circleci.com/api/v1.1/".

Authentication

To authenticate, add an API token using your account dashboard. To use the API token, add it to the circle-token query param, like so:

curl https://circleci.com/api/v1.1/me?circle-token=:token

Alternatively, you can use the API token as the username for HTTP Basic Authentication, by passing the -u flag to the curl command, like so:

curl -u <circle-token>: https://circleci.com/api/...

(Note the colon :, which tells curl that there's no password.)

Version Control System (:vcs-type)

New with v1.1 of the api, for endpoints under /project you will now need to tell CircleCI what version control system type your project uses. Current choices are 'github' or 'bitbucket'. The command for recent builds for a project would be formatted like so:

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/tree/:branch

Project Username (:username)

This is the GitHub or Bitbucket project account username for the target project (not your personal GitHub or Bitbucket username).

F/OSS

If you have a Free / Open Source Software (F/OSS) project, and have the setting turned on in Advanced Settings in your project dashboard, some read-only /project endpoints will return the requested data without the need for a token. People will also be able to view the build results dashboard for the project as well.

List Ordering

There are two API endpoints where the list order is significant:

In both cases, builds are returned in the order that they were created. For all other endpoints, the order has no special significance.

Accept header

If you specify no accept header, we'll return human-readable JSON with comments. If you prefer to receive compact JSON with no whitespace or comments, add the "application/json" Accept header. Using curl:

curl https://circleci.com/api/v1.1/me?circle-token=:token -H "Accept: application/json"

User

{{ site.data.api.me | api_endpoint }}

Projects

{{ site.data.api.projects | api_endpoint }}

Follow a New Project on CircleCI

{{ site.data.api.follow | api_endpoint }}

Recent Builds Across All Projects

{{ site.data.api.recent_builds | api_endpoint }}

Recent Builds For a Single Project

{{ site.data.api.project | api_endpoint }}

Recent Builds For a Project Branch

You can narrow the builds to a single branch by appending /tree/:branch to the url: https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/tree/:branch

The branch name should be url-encoded.

Single Job

Note: This is also the payload for the [notification webhooks]( {{ site.baseurl }}/1.0/configuration/#notify), in which case this object is the value to a key named 'payload'.

{{ site.data.api.build | api_endpoint }}

Artifacts of a Build

{{ site.data.api.artifacts | api_endpoint }}

Notes:

  • the value of path is relative to the project root (the working_directory)
  • pretty_path returns the same value as path. It is included in the response for backwards compatibility

Download an artifact file

You can download an individual artifact file via the API by appending a query string to its URL:

https://132-55688803-gh.circle-artifacts.com/0//tmp/circle-artifacts.7wgAaIU/file.txt?circle-token=:token

':token' is an API token with 'view-builds' scope.

Artifacts of the latest Build

{{ site.data.api.artifacts_latest | api_endpoint }}

Notes:

  • the value of path is relative to the project root (the working_directory)
  • pretty_path returns the same value as path. It is included in the response for backwards compatibility

Retry a Build

{{ site.data.api.retry_build | api_endpoint }}

You can retry a build with ssh by swapping "retry" with "ssh": https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/ssh

Add User to Build

{{ site.data.api.add_user_ssh | api_endpoint }}

Cancel a Build

{{ site.data.api.cancel_build | api_endpoint }}

Trigger a new Job

{{ site.data.api.project_post | api_endpoint }}

Trigger a new Build with a Branch

Note: For more about build parameters, read about [using 1.0 parameterized builds]( {{ site.baseurl }}/1.0/parameterized-builds/) and [optional 2.0 build parameters]({{ site.baseurl }}/2.0/env-vars/#injecting-environment-variables-with-the-api). The response for "failed" should be a boolean true or null.

{{ site.data.api.project_branch | api_endpoint }}

Trigger a new Build by Project (preview)

Prerequisite: You must go to your Project Settings in the CircleCI app to [Enable Build Processing (preview)]( {{ site.baseurl }}/2.0/build-processing/). This endpoint does not yet support the build_parameters options that the job-triggering endpoint supports.

{{ site.data.api.project_build | api_endpoint }}

Clear Cache

{{ site.data.api.project_build_cache | api_endpoint}}

List Environment Variables

{{ site.data.api.list_environment_variables | api_endpoint}}

Add Environment Variables

{{ site.data.api.add_environment_variable | api_endpoint}}

Get Single Environment Variable

{{ site.data.api.get_environment_variable | api_endpoint}}

Delete Environment Variables

{{ site.data.api.delete_environment_variable | api_endpoint}}

List Checkout Keys

{{ site.data.api.list_checkout_keys | api_endpoint}}

New Checkout Key

{{ site.data.api.new_checkout_key | api_endpoint}}

Get Checkout Key

{{ site.data.api.get_checkout_key | api_endpoint}}

Delete Checkout Key

{{ site.data.api.delete_checkout_key | api_endpoint}}

Test Metadata

{{ site.data.api.test_metadata | api_endpoint }}

Note: [Learn how to set up your 1.0 builds to collect test metadata]( {{ site.baseurl }}/1.0/test-metadata/) and [set up your 2.0 builds to collect test metadata]( {{ site.baseurl }}/2.0/collect-test-data/)

SSH Keys

{{ site.data.api.ssh_key | api_endpoint }}

Heroku Keys

{{ site.data.api.heroku_key | api_endpoint }}