v1-reference.md

layout	title	categories	description	regenerate	sitemap
classic-docs	CircleCI API v1.1 Reference	reference	Using the CircleCI API	true	false

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.

• TOC {:toc}

Endpoint Summary

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

{% assign apis = site.data.api | sort: url %} {%- for endpoint in apis %} {%- unless endpoint[1].url contains "/project/:vcs-type/:username/:project" %} {%- endunless -%} {% endfor %} {%- for endpoint in apis %} {%- if endpoint[1].url contains "/project/:vcs-type/:username/:project" -%} {%- endif -%} {% endfor %}

Endpoint	Method	Description
{{ endpoint[1].url | remove: "/api/v1.1" }}	{{- endpoint[1].method -}}	{{- endpoint[1].description -}}
Endpoint	Method	Description
Project endpoints below should be prefixed with /api/v1.1/project/:vcs-type/:username/:project
{{ endpoint[1].url | remove: "/api/v1.1/project/:vcs-type/:username/:project" }}	{{- endpoint[1].method -}}	{{- endpoint[1].description -}}

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 -H "Circle-Token: " https://circleci.com/api/v1.1/me

3.  You should see a response like the following:

    ```
{
  "user_key_fingerprint" : null,
  "days_left_in_trial" : -238,
  "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 be authenticated by the API server, use this as the value of the Circle-Token header:

curl -H "Circle-Token: <circle-token>" "https://circleci.com/api/..."

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.)

DEPRECATED (this option will be removed in the future): The API token can be added to the circle-token query param:

curl https://circleci.com/api/v1.1/me

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 -H "Accept: application/json" -H "Circle-Token: <circle-token>" https://circleci.com/api/v1.1/me

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 }}/configuration-reference/#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 with an API-token authenticated HTTP request.

curl -L -H "Circle-Token: <circle-token>" https://132-55688803-gh.circle-artifacts.com/0//tmp/circle-artifacts.7wgAaIU/file.txt

Notes:

• Make sure your HTTP client is configured to follow follow redirects as the artifact URLs can respond with an HTTP 3xx status code (the -L switch in curl will achieve this).
• :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

For more information about build parameters, refer to the [Running tests in Parallel]( {{ site.baseurl }}/parallelism-faster-jobs/) and [Optional build parameters]({{ site.baseurl }}/inject-environment-variables-with-api/#api-v1) pages. The response for "failed" should be a boolean true or null. {: class="alert alert-info" }

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

Trigger a new Build by Project (preview)

Prerequisite: 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 builds to collect test metadata]( {{ site.baseurl }}/collect-test-data/)

SSH Keys

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

Heroku Keys

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