CircleCI API v1.1 Reference

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

Endpoint Summary
Getting Started
Authentication
Version Control System (:vcs-type)
- Project Username (:username)
F/OSS
List Ordering
Accept header
User
Projects
Test Metadata
SSH Keys
Heroku Keys

Endpoint Summary

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

Endpoint	Method	Description
/user/heroku-key	POST	Adds your Heroku API key to CircleCI
/me	GET	Provides information about the signed in user.
/projects	GET	List of all the projects you're following on CircleCI, with build information organized by branch.
/recent-builds	GET	Build summary for each of the last 30 recent builds, ordered by build_num.
/user/ssh-key	POST	Adds a CircleCI key to your GitHub User account.
Endpoint	Method	Description
Project endpoints below should be prefixed with `/api/v1.1/project/:vcs-type/:username/:project`
/envvar	POST	Creates a new environment variable
/:build_num/ssh-users	POST	Only available when using a user API token. If the current user has permission to build the project, this API adds the current user's SSH public key to the authorized keys on each container running a build. This allows them to SSH to the build containers.
/:build_num/artifacts	GET	List the artifacts produced by a given build.
/latest/artifacts	GET	List the artifacts produced by the latest build on a given branch.
/:build_num	GET	Full details for a single job. The response includes all of the fields from the job summary.
/:build_num/cancel	POST	Cancels the build, returns a summary of the build.
/checkout-key/:fingerprint	DELETE	Deletes the checkout key
/envvar/:name	DELETE	Deletes the environment variable named ':name'
/ssh-key	DELETE	Delete an ssh key that will be used to access the external system identified by fingerprint. Hostname is optional.
/follow	POST	Follow a new project. CircleCI will then monitor the project for automatic building of commits.
/checkout-key/:fingerprint	GET	Gets the checkout key
/envvar/:name	GET	Gets the hidden value of environment variable :name
/checkout-key	GET	Lists the checkout keys for :project
/envvar	GET	Returns four 'x' characters plus the last four ASCII characters of the value, consistent with the display of environment variable values in the CircleCI website.
/checkout-key	POST	Creates a new checkout key. Only usable with a user API token.
	GET	Build summary for each of the last 30 builds for a single git repo, ordered by build_num.
/tree/:branch	POST	Triggers a new build, returns a summary of the build.
/build	POST	Trigger a build of the specified project, by branch, revision, or tag. Workflows will be run or scheduled in the same way as when a webhook from source control is received.
/build-cache	DELETE	Clears the cache for a project
	POST	Triggers a new build, returns a summary of the build.
/:build_num/retry	POST	Retries the build, returns a summary of the new build.
/ssh-key	POST	Creates an ssh key that will be used to access the external system identified by the hostname parameter for SSH key-based authentication.
/:build_num/tests	GET	Provides test metadata for a build

Getting Started

Add an API token from your account dashboard.

To test it, View it in your browser or call the API using curl:

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

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:

Recent Builds Across All Projects
Recent Builds For a Project

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

Provides information about the signed in user.

Method

GET

Example call

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

Example response

{
  "basic_email_prefs" : "smart", // can be "smart", "none" or "all"
  "login" : "pbiggar" // your github username
}

Try it in your browser

Projects

List of all the projects you're following on CircleCI, with build information organized by branch.

Method

GET

Example call

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

Example response

[ {
  "vcs_url": "https://github.com/circleci/mongofinil",
  "followed": true, // true if you follow this project in CircleCI
  "username": "circleci",
  "reponame": "mongofinil",
  "branches" : {
    "master" : {
      "pusher_logins" : [ "pbiggar", "arohner" ], // users who have pushed
      "last_non_success" : { // last failed build on this branch
        "pushed_at" : "2013-02-12T21:33:14Z",
        "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
        "build_num" : 22,
        "outcome" : "failed",
        },
      "last_success" : { // last successful build on this branch
        "pushed_at" : "2012-08-09T03:59:53Z",
        "vcs_revision" : "384211bbe72b2a22997116a78788117b3922d570",
        "build_num" : 15,
        "outcome" : "success",
        },
      "recent_builds" : [ { // last 5 builds, ordered by pushed_at (decreasing)
        "pushed_at" : "2013-02-12T21:33:14Z",
        "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
        "build_num" : 22,
        "outcome" : "failed",
        }, {
        "pushed_at" : "2013-02-11T03:09:54Z",
        "vcs_revision" : "0553ba86b35a97e22ead78b0d568f6a7c79b838d",

        "build_num" : 21,
        "outcome" : "failed",
        }, ... ],
      "running_builds" : [ ] // currently running builds
    }
  }
}, ... ]

Try it in your browser

Follow a New Project on CircleCI

Follow a new project. CircleCI will then monitor the project for automatic building of commits.

Method

POST

Example call

curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/follow?circle-token=:token

Example response

{
  "followed" : true,
  "first_build" : {
    "compare" : null,
    "previous_successful_build" : null,
    "build_parameters" : null,
    "oss" : true,
    "committer_date" : null,
    "body" : null,
    "usage_queued_at" : "2016-09-07T13:48:10.825Z",
    "fail_reason" : null,
    "retry_of" : null,
    "reponame" : "testing-circleci",
    "ssh_users" : [ ],
    "build_url" : "https://circleci.com/gh/circleci/mongofinil/1",
    "parallel" : 1,
    "failed" : null,
    "branch" : "master",
    "username" : "circleci",
    "author_date" : null,
    "why" : "first-build",
    "user" : {
      "is_user" : true,
      "login" : "circleci",
      "avatar_url" : "https://avatars.githubusercontent.com/u/6017470?v=3",
      "name" : "CircleCI",
      "vcs_type" : "github",
      "id" : 10101010
    },
    "vcs_revision" : "b2b5def65bf54091dde02ebb39ef3c54de3ff049",
    "vcs_tag" : null,
    "build_num" : 1,
    "infrastructure_fail" : false,
    "committer_email" : null,
    "previous" : null,
    "status" : "not_running",
    "committer_name" : null,
    "retries" : null,
    "subject" : null,
    "vcs_type" : "github",
    "timedout" : false,
    "dont_build" : null,
    "lifecycle" : "not_running",
    "no_dependency_cache" : false,
    "stop_time" : null,
    "ssh_disabled" : false,
    "build_time_millis" : null,
    "circle_yml" : null,
    "messages" : [ ],
    "is_first_green_build" : false,
    "job_name" : null,
    "start_time" : null,
    "canceler" : null,
    "outcome" : null,
    "vcs_url" : "https://github.com/circleci/mongofinil",
    "author_name" : null,
    "node" : null,
    "canceled" : false,
    "author_email" : null
  }
}

Recent Builds Across All Projects

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

Method

GET

Parameter	Description
limit	The number of builds to return. Maximum 100, defaults to 30.
offset	The API returns builds starting from this offset, defaults to 0.

Example call

curl https://circleci.com/api/v1.1/recent-builds?circle-token=:token&limit=20&offset=5

Example response

[ {
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished
  "build_time_millis" : 23505,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "finished", // :queued, :scheduled, :not_run, :not_running, :running or :finished
  "outcome" : "failed", // :canceled, :infrastructure_fail, :timedout, :failed, :no_tests or :success
  "status" : "failed", // :retried, :canceled, :infrastructure_fail, :timedout, :not_run, :running, :failed, :queued, :scheduled, :not_running, :no_tests, :fixed, :success
  "retry_of" : null, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 21
  }, ... ]

Try it in your browser

Recent Builds For a Single Project

Build summary for each of the last 30 builds for a single git repo, ordered by build_num.

Method

GET

Parameter	Description
limit	The number of builds to return. Maximum 100, defaults to 30.
offset	The API returns builds starting from this offset, defaults to 0.
filter	Restricts which builds are returned. Set to "completed", "successful", "failed", "running", or defaults to no filter.

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project?circle-token=:token&limit=20&offset=5&filter=completed

Example response

[ {
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started running
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished running
  "build_time_millis" : 23505,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "finished", // :queued, :scheduled, :not_run, :not_running, :running or :finished
  "outcome" : "failed", // :canceled, :infrastructure_fail, :timedout, :failed, :no_tests or :success
  "status" : "failed", // :retried, :canceled, :infrastructure_fail, :timedout, :not_run, :running, :failed, :queued, :scheduled, :not_running, :no_tests, :fixed, :success
  "retry_of" : null, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 21
  }, ... ]

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, in which case this object is the value to a key named ‘payload’.

Full details for a single job. The response includes all of the fields from the job summary.

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num?circle-token=:token

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/22",
  "build_num" : 22,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "github", // short string explaining the reason the build ran
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-02-12T21:33:30Z" // time build was queued
  "start_time" : "2013-02-12T21:33:38Z", // time build started
  "stop_time" : "2013-02-12T21:34:01Z", // time build finished
  "build_time_millis" : 23505,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "finished", // :queued, :scheduled, :not_run, :not_running, :running or :finished
  "outcome" : "success", // :canceled, :infrastructure_fail, :timedout, :failed, :no_tests or :success
  "status" : "success", // :retried, :canceled, :infrastructure_fail, :timedout, :not_run, :running, :failed, :queued, :scheduled, :not_running, :no_tests, :fixed, :success
  "retry_of" : null, // build_num of the build this is a retry of
  "steps" : [ {
    "name" : "configure the build",
    "actions" : [ {
      "bash_command" : null,
      "run_time_millis" : 1646,
      "start_time" : "2013-02-12T21:33:38Z",
      "end_time" : "2013-02-12T21:33:39Z",
      "name" : "configure the build",
      "exit_code" : null,
      "type" : "infrastructure",
      "index" : 0,
      "status" : "success",
    } ] },

    "name" : "lein2 deps",
    "actions" : [ {
      "bash_command" : "lein2 deps",
      "run_time_millis" : 7555,
      "start_time" : "2013-02-12T21:33:47Z",
      "messages" : [ ],
      "step" : 1,
      "exit_code" : 0,
      "end_time" : "2013-02-12T21:33:54Z",
      "index" : 0,
      "status" : "success",
      "type" : "dependencies",
      "source" : "inference",
      "failed" : null
    } ] },
    "name" : "lein2 trampoline midje",
    "actions" : [ {
      "bash_command" : "lein2 trampoline midje",
      "run_time_millis" : 2310,
      "continue" : null,
      "parallel" : true,
      "start_time" : "2013-02-12T21:33:59Z",
      "name" : "lein2 trampoline midje",
      "messages" : [ ],
      "step" : 6,
      "exit_code" : 1,
      "end_time" : "2013-02-12T21:34:01Z",
      "index" : 0,
      "status" : "failed",
      "timedout" : null,
      "infrastructure_fail" : null,
      "type" : "test",
      "source" : "inference",
      "failed" : true
    } ]
  } ],
  ...
}

Artifacts of a Build

List the artifacts produced by a given build.

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/artifacts?circle-token=:token

Example response

[ {
  "path" : "raw-test-output/go-test-report.xml",
  "pretty_path" : "raw-test-output/go-test-report.xml",
  "node_index" : 0,
  "url" : "https://24-88881093-gh.circle-artifacts.com/0/raw-test-output/go-test-report.xml"
}, {
  "path" : "raw-test-output/go-test.out",
  "pretty_path" : "raw-test-output/go-test.out",
  "node_index" : 0,
  "url" : "https://24-88881093-gh.circle-artifacts.com/0/raw-test-output/go-test.out"
} ]

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

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

Method

GET

Parameter	Description
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. Set to "completed", "successful", "failed". Defaults to "completed".

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/latest/artifacts?circle-token=:token&branch=:branch&filter=:filter

Example response

[ {
  "path" : "raw-test-output/go-test-report.xml",
  "pretty_path" : "raw-test-output/go-test-report.xml",
  "node_index" : 0,
  "url" : "https://24-88881093-gh.circle-artifacts.com/0/raw-test-output/go-test-report.xml"
}, {
  "path" : "raw-test-output/go-test.out",
  "pretty_path" : "raw-test-output/go-test.out",
  "node_index" : 0,
  "url" : "https://24-88881093-gh.circle-artifacts.com/0/raw-test-output/go-test.out"
} ]

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

Retries the build, returns a summary of the new build.

Method

POST

Example call

curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/retry?circle-token=:token

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/23",
  "build_num" : 23,
  "branch" : "master",
  "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Don't explode when the system clock shifts backwards",
  "body" : "", // commit message body
  "why" : "retry", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-04-12T21:33:30Z" // time build was queued
  "start_time" : "2013-04-12T21:33:38Z", // time build started running
  "stop_time" : "2013-04-12T21:34:01Z", // time build finished running
  "build_time_millis" : 23505,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "queued",
  "outcome" : null,
  "status" : "queued",
  "retry_of" : 22, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "failed",
    "build_num" : 22
  }
}

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

Only available when using a user API token. If the current user has permission to build the project, this API adds the current user's SSH public key to the authorized keys on each container running a build. This allows them to SSH to the build containers.

Method

POST

Example call

curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/ssh-users?circle-token=:token

Example response

{... the build data ... }

Cancel a Build

Cancels the build, returns a summary of the build.

Method

POST

Example call

curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/cancel?circle-token=:token

Example response

{
  "vcs_url" : "https://github.com/circleci/mongofinil",
  "build_url" : "https://circleci.com/gh/circleci/mongofinil/26",
  "build_num" : 26,
  "branch" : "master",
  "vcs_revision" : "59c9c5ea3e289f2f3b0c94e128267cc0ce2d65c6",
  "committer_name" : "Allen Rohner",
  "committer_email" : "arohner@gmail.com",
  "subject" : "Merge pull request #6 from dlowe/master"
  "body" : "le bump", // commit message body
  "why" : "retry", // short string explaining the reason we built
  "dont_build" : null, // reason why we didn't build, if we didn't build
  "queued_at" : "2013-05-24T19:37:59.095Z" // time build was queued
  "start_time" : null, // time build started running
  "stop_time" : null, // time build finished running
  "build_time_millis" : null,
  "username" : "circleci",
  "reponame" : "mongofinil",
  "lifecycle" : "queued",
  "outcome" : "canceled",
  "status" : "canceled",
  "canceled" : true,
  "retry_of" : 25, // build_num of the build this is a retry of
  "previous" : { // previous build
    "status" : "success",
    "build_num" : 25
  }
}

Trigger a new Job

Triggers a new build, returns a summary of the build.

Method

POST

Parameter	Description
revision	The specific revision to build. Default is null and the head of the branch is used. Cannot be used with tag parameter.
tag	The tag to build. Default is null. Cannot be used with revision parameter.
parallel	The number of containers to use to run the build. Default is null and the project default is used. This parameter is ignored for builds running on our 2.0 infrastructure.
build_parameters	Additional environment variables to inject into the build environment. A map of names to values.

Example call

curl -X POST --header "Content-Type: application/json" -d '{
  "tag": "v0.1", // optional
  "parallel": 2, //optional, default null
  "build_parameters": { // optional
    "RUN_EXTRA_TESTS": "true"
  }
}
' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project?circle-token=:token

Example response

{
  "author_name": "Allen Rohner",
  "build_url": "https://circleci.com/gh/circleci/mongofinil/54",
  "reponame": "mongofinil",
  "failed": null,
  "infrastructure_fail": false,
  "canceled": false,
  "all_commit_details": [{
      "author_name": "Allen Rohner",
      "commit": "f1baeb913288519dd9a942499cef2873f5b1c2bf",
      "author_login": "arohner",
      "committer_login": "arohner",
      "committer_name": "Allen Rohner",
      "body": "Minor version bump",
      "author_date": "2014-04-17T08:41:40Z",
      "committer_date": "2014-04-17T08:41:40Z",
      "commit_url": "https://github.com/circleci/mongofinil/commit/f1baeb913288519dd9a942499cef2873f5b1c2bf",
      "committer_email": "arohner@gmail.com",
      "author_email": "arohner@gmail.com",
      "subject": "Merge pull request #15 from circleci/minor-version-bump"
    }],
  "previous": {
    "build_num": 53,
    "status": "success",
    "build_time_millis": 55413
  },
  "ssh_enabled": null,
  "author_email": "arohner@gmail.com",
  "why": "edit",
  "build_time_millis": null,
  "committer_email": "arohner@gmail.com",
  "parallel": 2,
  "retries": null,
  "compare": null,
  "dont_build": null,
  "committer_name": "Allen Rohner",
  "usage_queued_at": "2014-04-29T12:56:55.338Z",
  "branch": "master",
  "body": "Minor version bump",
  "author_date": "2014-04-17T08:41:40Z",
  "node": null,
  "committer_date": "2014-04-17T08:41:40Z",
  "start_time": null,
  "stop_time": null,
  "lifecycle": "not_running",
  "user": {
    "email": "arohner@gmail.com",
    "name": "Allen Rohner",
    "login": "arohner",
    "is_user": true
  },
  "subject": "Merge pull request #15 from circleci/minor-version-bump",
  "messages": [],
  "job_name": null,
  "retry_of": null,
  "previous_successful_build": {
    "build_num": 53,
    "status": "success",
    "build_time_millis": 55413
  },
  "outcome": null,
  "status": "not_running",
  "vcs_revision": "f1baeb913288519dd9a942499cef2873f5b1c2bf",
  "vcs_tag": "v0.1",
  "build_num": 54,
  "username": "circleci",
  "vcs_url": "https://github.com/circleci/mongofinil",
  "timedout": false
}

Trigger a new Build with a Branch

Note: For more about build parameters, read about using 1.0 parameterized builds and optional 2.0 build parameters. The response for “failed” should be a boolean true or null.

Triggers a new build, returns a summary of the build.

Method

POST

Parameter	Description
parallel	The number of containers to use to run the build. Default is null and the project default is used.
revision	The specific revision to build. Default is null and the head of the branch is used
build_parameters	Additional environment variables to inject into the build environment. A map of names to values.

Example call

curl -X POST --header "Content-Type: application/json" -d '{
  "parallel": 2, //optional, default null
  "revision": "f1baeb913288519dd9a942499cef2873f5b1c2bf" // optional
  "build_parameters": { // optional
    "RUN_EXTRA_TESTS": "true"
  }
}
' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/tree/:branch?circle-token=:token

Example response

{
  "author_name": "Allen Rohner",
  "build_url": "https://circleci.com/gh/circleci/mongofinil/54",
  "reponame": "mongofinil",
  "failed": null,
  "infrastructure_fail": false,
  "canceled": false,
  "all_commit_details": [
    {
      "author_name": "Allen Rohner",
      "commit": "f1baeb913288519dd9a942499cef2873f5b1c2bf",
      "author_login": "arohner",
      "committer_login": "arohner",
      "committer_name": "Allen Rohner",
      "body": "Minor version bump",
      "author_date": "2014-04-17T08:41:40Z",
      "committer_date": "2014-04-17T08:41:40Z",
      "commit_url": "https://github.com/circleci/mongofinil/commit/f1baeb913288519dd9a942499cef2873f5b1c2bf",
      "committer_email": "arohner@gmail.com",
      "author_email": "arohner@gmail.com",
      "subject": "Merge pull request #15 from circleci/minor-version-bump"
    }
  ],
  "previous": {
    "build_num": 53,
    "status": "success",
    "build_time_millis": 55413
  },
  "ssh_enabled": null,
  "author_email": "arohner@gmail.com",
  "why": "edit",
  "build_time_millis": null,
  "committer_email": "arohner@gmail.com",
  "parallel": 2,
  "retries": null,
  "compare": null,
  "dont_build": null,
  "committer_name": "Allen Rohner",
  "usage_queued_at": "2014-04-29T12:56:55.338Z",
  "branch": "master",
  "body": "Minor version bump",
  "author_date": "2014-04-17T08:41:40Z",
  "node": null,
  "committer_date": "2014-04-17T08:41:40Z",
  "start_time": null,
  "stop_time": null,
  "lifecycle": "not_running", // :queued, :scheduled, :not_run, :not_running, :running or :finished
  "user": {
    "email": "arohner@gmail.com",
    "name": "Allen Rohner",
    "login": "arohner",
    "is_user": true
  },
  "subject": "Merge pull request #15 from circleci/minor-version-bump",
  "messages": [],
  "job_name": null,
  "retry_of": null,
  "previous_successful_build": {
    "build_num": 53,
    "status": "success",
    "build_time_millis": 55413
  },
  "outcome": null,
  "status": "not_running",
  "vcs_revision": "f1baeb913288519dd9a942499cef2873f5b1c2bf",
  "build_num": 54,
  "username": "circleci",
  "vcs_url": "https://github.com/circleci/mongofinil",
  "timedout": false
}

Trigger a new Build by Project (preview)

Prerequisite: You must go to your Project Settings in the CircleCI app to Enable Build Processing (preview). This endpoint does not yet support the build_parameters options that the job-triggering endpoint supports.

Trigger a build of the specified project, by branch, revision, or tag. Workflows will be run or scheduled in the same way as when a webhook from source control is received.

Method

POST

Parameter	Description
branch	The branch to build. Cannot be used with tag parameter.
revision	The specific revision to build. If not specified, the HEAD of the branch is used. Cannot be used with tag parameter.
tag	The git tag to build. Cannot be used with branch and revision parameters.

Example call

curl -X POST --header "Content-Type: application/json" -d '{"branch":"staging"}' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/build?circle-token=:token

Example response

{
  "status": 200,
  "body": "Build created"
  }

Clear Cache

Clears the cache for a project

Method

DELETE

Example call

curl -X DELETE https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/build-cache?circle-token=:token

Example response

{
  "status" : "build caches deleted"
}

List Environment Variables

Returns four 'x' characters plus the last four ASCII characters of the value, consistent with the display of environment variable values in the CircleCI website.

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar?circle-token=:token

Example response

[{"name":"foo","value":"xxxx1234"}]

Add Environment Variables

Creates a new environment variable

Method

POST

Example call

curl -X POST --header "Content-Type: application/json" -d '{"name":"foo", "value":"bar"}' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar?circle-token=:token

Example response

{"name":"foo","value":"xxxx"}

Get Single Environment Variable

Gets the hidden value of environment variable :name

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar/:name?circle-token=:token

Example response

{"name":"foo","value":"xxxx"}

Delete Environment Variables

Deletes the environment variable named ':name'

Method

DELETE

Example call

curl -X DELETE https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar/:name?circle-token=:token

Example response

{"message":"ok"}

List Checkout Keys

Lists the checkout keys for :project

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key?circle-token=:token

Example response

[{"public_key": "ssh-rsa...",
  "type": "deploy-key", // can be "deploy-key" or "github-user-key"
  "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  "preferred": true,
  "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
  }]

New Checkout Key

Creates a new checkout key. Only usable with a user API token.

Method

POST

Parameter	Description
type	The type of key to create. Can be 'deploy-key' or 'github-user-key'.

Example call

curl -X POST --header "Content-Type: application/json" -d '{"type":"github-user-key"}' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key?circle-token=:token

Example response

{"public_key": "ssh-rsa...",
  "type": "deploy-key", // can be "deploy-key" or "user-key"
  "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  "preferred": true,
  "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
  }

Get Checkout Key

Gets the checkout key

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key/:fingerprint?circle-token=:token

Example response

{"public_key": "ssh-rsa...",
  "type": "deploy-key", // can be "deploy-key" or "user-key"
  "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  "preferred": true,
  "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
  }

Delete Checkout Key

Deletes the checkout key

Method

DELETE

Example call

curl -X DELETE https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key/:fingerprint?circle-token=:token

Example response

{"message":"ok"}

Test Metadata

Provides test metadata for a build

Method

GET

Example call

curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/tests?circle-token=:token

Example response

{
  "tests" : [ {
    "message" : "",
    "file" : "features/desktop/invitations.feature",
    "source" : "cucumber",
    "run_time" : 2.957513661,
    "result" : "success",
    "name" : "Accepting an invitation",
    "classname" : "Invitations"
  }, {
    "message" : null,
    "file" : "spec/lib/webfinger_spec.rb",
    "source" : "rspec",
    "run_time" : 0.011366,
    "result" : "success",
    "name" : "Webfinger#intialize sets account ",
    "classname" : "spec.lib.webfinger_spec"
  } ]
}

Note: Learn how to set up your 1.0 builds to collect test metadata and set up your 2.0 builds to collect test metadata

SSH Keys

Creates an ssh key that will be used to access the external system identified by the hostname parameter for SSH key-based authentication.

Method

POST

Example call

curl -X POST --header "Content-Type: application/json" -d '{"hostname":"hostname","private_key":"RSA private key"}' https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/ssh-key?circle-token=:token

Example response

[no response expected]

Heroku Keys

Adds your Heroku API key to CircleCI

Method

POST

Example call

curl -X POST --header "Content-Type: application/json" -d '{"apikey":"Heroku key"}' https://circleci.com/user/heroku-key?circle-token=:token

Example response

[no response expected]

Search Results for ""

CircleCI API v1.1 Reference

Endpoint Summary

Getting Started

Making calls

Authentication

Version Control System (:vcs-type)

Project Username (:username)

F/OSS

List Ordering

Accept header

User

Method

Example call

Example response

Projects

Method

Example call

Example response

Follow a New Project on CircleCI

Method

Example call

Example response

Recent Builds Across All Projects

Method

Example call

Example response

Recent Builds For a Single Project

Method

Example call

Example response

Recent Builds For a Project Branch

Single Job

Method

Example call

Example response

Artifacts of a Build

Method

Example call

Example response

Download an artifact file

Artifacts of the latest Build

Method

Example call

Example response

Retry a Build

Method

Example call

Example response

Add User to Build

Method

Example call

Example response

Cancel a Build

Method

Example call

Example response

Trigger a new Job

Method

Example call

Example response

Trigger a new Build with a Branch

Method

Example call

Example response

Trigger a new Build by Project (preview)

Method

Example call

Example response

Clear Cache

Method

Example call

Example response

List Environment Variables

Method

Example call

Example response

Add Environment Variables

Method

Example call