- 
- 
- CircleCI V1 API Overview
-The CircleCI API is a full-featured RESTful API that allows you to access all information and trigger all actions in CircleCI. RESTful APIs enable you to call individual API endpoints to perform the following actions:
- --
-
- GET - retrieve specific information, which may include arrays and sets of data and information. -
- POST - create/add a new API element. -
- PUT - update an existing API element in the API server. -
- DELETE - remove/delete an API element in the API server. -
Authentication
-The CircleCI API utilizes token-based authentication to manage access to the API server and validate that a user has permission to make API requests. Before you can make an API request, you must first add an API token and then verify that you are authenticated by the API server to make requests. The process to add an API token and have the API server authenticate you is described in the sections below.
- -Note You may use the API token as the username for HTTP Basic Authentication, by passing the -u flag to the curl command.
Add an API Token
$ curl -H "Circle-Token: <circle-token>" https://circleci.com/api/v1.1/me
-{
- "user_key_fingerprint" : null,
- "days_left_in_trial" : -238,
- "trial_end" : "2011-12-28T22:02:15Z",
- "basic_email_prefs" : "smart",
- "admin" : true,
- "login" : "pbiggar"
- }
-To add an API token, perform the steps listed below.
- --
-
- Add an API token from your account dashboard. -
- To test it, View it in your browser or call the API using -
- You should see a response similar to the example shown in the right pane. -
Get Authenticated
curl -H "Circle-Token: <circle-token>" "https://circleci.com/api/..."
-curl -u <circle-token>: "https://circleci.com/api/..."
-curl "https://circleci.com/api/v1.1/me?circle-token=<circle-token>"
-You can add the API token using your account dashboard. We recommend using personal API tokens at this time because project API tokens are not supported for API v2. Project API tokens are supported for most API v1 endpoints. Notes are included below to indicate when a personal API token is required.
- -To be authenticated by the API server, use this as the value of the Circle-Token header:
- -Or you can use the API token as the username for HTTP Basic Authentication, by passing the -u flag to the curl command:
DEPRECATED (this option will be removed in the future): The API token can be added to the circle-token query param:
Summary of API Endpoints
-All CircleCI API endpoints begin with https://circleci.com/api/v1.1/
GET Requests
-| API | -Description | -
|---|---|
| /me | -Provides information about the signed in user. | -
| /projects | -Lists all projects you are following on CircleCI, with job information organized by branch. | -
| /project/:vcs-type/:username/:project | -Returns a summary for each of the last 30 job runs for a single project. | -
| /recent-builds | -Returns a summary for each of the last 30 recent job runs, ordered by build_num. | -
| /project/:vcs-type/:username/:project/:build_num | -Returns full details for a single job run. The response includes all of the fields from the job summary. This is also the payload for the notification webhooks, in which case this object is the value to a key named ‘payload’. | -
| /project/:vcs-type/:username/:project/:build_num/artifacts | -Lists the artifacts produced by a given job run. | -
| /project/:vcs-type/:username/:project/checkout-key/:fingerprint | -Retrieves a checkout key. | -
POST Requests
-| API | -Description | -
|---|---|
| /project/:vcs-type/:username/:project/follow | -Follow a new project on CircleCI. | -
| /project/:vcs-type/:org_name/:project/:build_num/retry | -Retries the job, returns a summary of the new job run. | -
| /project/:vcs-type/:username/:project/:build_num/cancel | -Cancels the job, returns a summary of the job run. | -
| /project/:vcs-type/:username/:project/:build_num/ssh-users | -Adds a user to the job's SSH permissions. | -
| /project/:vcs-type/:username/:project/tree/:branch | -Triggers a new job, returns a summary of the job run. Optional build parameters can be set. | -
| /project/:vcs-type/:username/:project/ssh-key | -Creates an SSH key used to access external systems that require SSH key-based authentication. | -
| /project/:vcs-type/:username/:project/checkout-key | -Creates a new checkout key. | -
DELETE Requests
-| API | -Description | -
|---|---|
| /project/:vcs-type/:username/:project/checkout-key/:fingerprint | -Deletes a checkout key. | -
| /project/:vcs-type/:username/:project/ssh-key | -Delete the SSH key from a project. | -
Getting Started
API Syntax
-When making an API request, make sure you follow standard REST API syntax and formatting. Adhering to proper REST API syntax ensures that the API server can properly process your request and return a JSON response. To make a request to the CircleCI API, use the format shown in the pane to the right:
-"https://circleci.com/api/v1.1"
-Where:
- --
-
- https://circleci.com - the resource URL for the API being called. -
- api - the class being called. -
- v1.1 - the API version. -
Version Control Systems
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/tree/:branch
-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. You may currently select either ‘github’ or ‘bitbucket’. The command for recent builds for a project would be formatted like the example shown in the right pane.
Rate Limiting
-The CircleCI API is protected by a number of rate limiting measures to ensure the stability of the system. We reserve the right to throttle the requests made by an individual user, or the requests made to individual resources in order to ensure a fair level of service to all of our users.
- -As the author of an API integration with CircleCI, your integration should expect to be throttled, and should be able to gracefully handle failure. -There are different protections and limits in place for different parts of the API. In particular, we protect our API against sudden large bursts of traffic, and we protect against sustained high volumes of requests, for example, frequent polling.
- -For HTTP APIs, when a request is throttled, you will receive HTTP status code 429. If your integration requires that a throttled request is completed, then you should retry these requests after a delay, using an exponential backoff. -In most cases, the HTTP 429 response code will be accompanied by the Retry-After HTTP header. When this header is present, your integration should wait for the period of time specified by the header value before retrying a request.
-List Ordering
-There are two API endpoints where the list order is significant:
- - - -In both cases, jobs are returned in the order that they were created. For all other endpoints, the order has no special significance.
-Accept Header
curl https://circleci.com/api/v1.1/me -H "Accept: application/json" -H "Circle-Token: <circle-token>"
-If no accept header is specified (or it is empty), CircleCI will return the data in a Clojure EDN format. To receive the data as nicely formatted JSON, include any value for the Accept header (e.g text/plain). If you prefer to receive compact JSON with no whitespace or comments, use application/json as the Accept header.
Cache-Control Header
-Some CircleCI APIs may emit a Cache-Control header to indicate that the response may be cached for a period of time. This feature can be used to avoid unnecessary re-fetching of data that will not change. If you plan to make a large volume of API requests you are strongly encouraged to make use of this header in order to improve your performance and lower your risk of being rate limited.
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 job results dashboard for the project as well.
User
curl https://circleci.com/api/v1.1/me -H "Circle-Token: <circle-token>"
-{
- "basic_email_prefs" : "smart", // can be "smart", "none" or "all"
- "login" : "pbiggar" // your github username
-}
-GET Request: Provides information about the user that is currently signed in. The use of this endpoint requires a personal API token.
Projects
-If you would like to retrieve detailed information about projects, CircleCI provides several different endpoints that you may call to return this information, including the ability to return detailed information for all projects. To ensure you do not encounter any performance-related lags or issues when making an API request, you may wish to limit your search for a single project instead of an array of projects.
- -The sections below describe the endpoints you may call to return Project information.
-Get All Followed Projects
curl https://circleci.com/api/v1.1/projects -H "Circle-Token: <circle-token>"
-[ {
- "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 job on this branch
- "pushed_at" : "2013-02-12T21:33:14Z",
- "vcs_revision" : "1d231626ba1d2838e599c5c598d28e2306ad4e48",
- "build_num" : 22,
- "outcome" : "failed",
- },
- "last_success" : { // last successful job on this branch
- "pushed_at" : "2012-08-09T03:59:53Z",
- "vcs_revision" : "384211bbe72b2a22997116a78788117b3922d570",
- "build_num" : 15,
- "outcome" : "success",
- },
- "recent_builds" : [ { // last 5 jobs, 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 jobs
- }
- }
-}, ... ]
-GET request.
Returns an array of all projects you are currently following on CircleCI, with job information organized by branch.
-Follow a New Project on CircleCI
curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/follow -H "Circle-Token: <circle-token>"
-{
- "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
- }
-}
-Request Type: POST
Follows a new project. CircleCI will then monitor the project for automatic building of commits.
-Recent Jobs Across All Projects
curl https://circleci.com/api/v1.1/recent-builds?limit=1&shallow=true
-[ {
- "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 the job was queued
- "start_time" : "2013-02-12T21:33:38Z", // time the job started
- "stop_time" : "2013-02-12T21:34:01Z", // time the job finished
- "build_time_millis" : 23505,
- "username" : "circleci",
- "reponame" : "mongofinil",
- "lifecycle" : "finished", // :queued, :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, :not_running, :no_tests, :fixed, :success
- "retry_of" : null, // build_num of the job that this is a retry of
- "previous" : { // previous job
- "status" : "failed",
- "build_num" : 21
- }, ... ]
-Request Type: GET
Returns a job summary for each of the last 30 recent job runs, ordered by build_num.
| Parameter | -Description | -
|---|---|
| limit | -The number of job runs to return. Maximum 100, defaults to 30. | -
| offset | -The API returns job runs starting from this offset, defaults to 0. | -
| shallow | -An optional boolean parameter that may be sent to improve performance if set to 'true'. | -
Note: When making an API request for Project information, you may experience performance lag and a decrease in overall performance while the request is being processed by the server. To improve performance, CircleCI recommends you pass the shallow parameter in your request.
Recent Jobs For A Single Project
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project?limit=20&offset=5&filter=completed -H "Circle-Token: <circle-token>"
-[{
- "committer_date": "2019-04-12T10:44:51-07:00",
- "body": "",
- "usage_queued_at": "2019-04-12T17:46:11.229Z",
- "reponame": "circleci.com",
- "build_url": "https://circleci.com/gh/circleci/circleci.com/16315",
- "parallel": 1,
- "branch": "ja-homepage",
- "username": "circleci",
- "author_date": "2019-04-12T10:44:51-07:00",
- "why": "github",
- "user": {
- "is_user": true,
- "login": "trevor-circleci",
- "avatar_url": "https://avatars1.githubusercontent.com/u/22457684?v=4",
- "name": null,
- "vcs_type": "github",
- "id": 22457684
- },
- "vcs_revision": "8139060f4d1f6ff617ac49f8afb2273c4fee2343",
- "workflows": {
- "job_name": "build-preview",
- "job_id": "981f2bfa-3c50-4505-865d-5266670217eb",
- "workflow_id": "a063aeae-5b89-458b-8aa1-cca4c565b07d",
- "workspace_id": "a063aeae-5b89-458b-8aa1-cca4c565b07d",
- "upstream_job_ids": ["7e92fbf5-8111-430b-8e2a-54b169ba745d"],
- "upstream_concurrency_map": {},
- "workflow_name": "build-website"
- },
- "vcs_tag": null,
- "pull_requests": [{
- "head_sha": "8139060f4d1f6ff617ac49f8afb2273c4fee2343",
- "url": "https://github.com/circleci/circleci.com/pull/2347"
- }],
- "build_num": 16315,
- "committer_email": "trevor@circleci.com",
- "status": "success",
- "committer_name": "Trevor Sorel",
- "subject": "adding japanese translations for main nav",
- "dont_build": null,
- "lifecycle": "finished",
- "fleet": "picard",
- "stop_time": "2019-04-12T17:47:42.298Z",
- "build_time_millis": 89366,
- "start_time": "2019-04-12T17:46:12.932Z",
- "platform": "2.0",
- "outcome": "success",
- "vcs_url": "https://github.com/circleci/circleci.com",
- "author_name": "Trevor Sorel",
- "queued_at": "2019-04-12T17:46:11.289Z",
- "author_email": "trevor@circleci.com"
-}]
-GET Request: Returns a job summary for each of the last 30 job runs for a single project, ordered by build_num.
| Parameter | -Description | -
|---|---|
| limit | -The number of jobs to return. Maximum 100, defaults to 30. | -
| offset | -The API returns jobs starting from this offset, defaults to 0. | -
| filter | -Restricts which jobs are returned. Set to "completed", "successful", "failed", "running", or defaults to no filter. | -
| shallow | -An optional boolean value that may be sent to improve overall performance if set to 'true.' | -
Note: You can narrow the jobs to a single branch by appending /tree/:branch to the url. Note that the branch name should be url-encoded.
-Improving Performance In Recent Job Requests Using the Shallow Parameter
-When making API requests for information about recent job runs, you may experience performance lag and a decrease in overall performance while the request is being processed by the server. To improve performance, CircleCI recommends you pass the shallow parameter in your request.
curl https://circleci.com/api/v1.1/recent-builds?limit=1&shallow=true
-[ {
- "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 the job was queued
- "start_time" : "2013-02-12T21:33:38Z", // time the job started running
- "stop_time" : "2013-02-12T21:34:01Z", // time the job finished running
- "build_time_millis" : 23505,
- "username" : "circleci",
- "reponame" : "mongofinil",
- "lifecycle" : "finished", // :queued, :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, :not_running, :no_tests, :fixed, :success
- "retry_of" : null, // build_num of the job that this is a retry of
- "previous" : { // previous job
- "status" : "failed",
- "build_num" : 21
- }, ... ]
-Sample Request Using the Shallow Parameter
-The example to the right shows a user request for recent job information. Notice that when the user passes the shallow parameter, a limited set of information is returned, thereby improving response time and minimizing performance lag.
Jobs
Single Job
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num -H "Circle-Token: <circle-token>"
-{
- "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 job ran
- "dont_build" : null, // reason why we didn't build, if we didn't build
- "queued_at" : "2013-02-12T21:33:30Z", // time the job was queued
- "start_time" : "2013-02-12T21:33:38Z", // time the job started
- "stop_time" : "2013-02-12T21:34:01Z", // time the job finished
- "build_time_millis" : 23505,
- "username" : "circleci",
- "reponame" : "mongofinil",
- "lifecycle" : "finished", // :queued, :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, :not_running, :no_tests, :fixed, :success
- "retry_of" : null, // build_num of the job that 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
- } ]
- } ],
- ...
-}
-GET Request: Returns the full details for a single job. The response includes all of the fields from the job summary.
Retry a Job
curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:org_name/:project/:build_num/retry -H "Circle-Token: <circle-token>"
-
---You can retry a job with SSH by swapping “retry” with “ssh”.
-
{
- "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 the job was queued
- "start_time" : "2013-04-12T21:33:38Z", // time the job started running
- "stop_time" : "2013-04-12T21:34:01Z", // time the job finished running
- "build_time_millis" : 23505,
- "username" : "circleci",
- "reponame" : "mongofinil",
- "lifecycle" : "queued",
- "outcome" : null,
- "status" : "queued",
- "retry_of" : 22, // build_num of the job that this is a retry of
- "previous" : { // previous job
- "status" : "failed",
- "build_num" : 22
- }
-}
-POST Request: Retries the job and then returns a summary of the new job run.
Cancel a Job
curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/cancel -H "Circle-Token: <circle-token>"
-{
- "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 the job was queued
- "start_time" : null, // time the job started running
- "stop_time" : null, // time the job 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 job that this is a retry of
- "previous" : { // previous job
- "status" : "success",
- "build_num" : 25
- }
-}
-POST Request: Cancels the job and then returns a summary of the job run.
Trigger a new Job
curl -X POST --header "Content-Type: application/json" -H "Circle-Token: <circle-token>" -d '{
- "job": "deploy-preview"
- "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
-{
- "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": "my-new-job",
- "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
-}
-POST Request: Triggers a new job and then returns a summary of the job run.
| Parameter | -Description | -
|---|---|
| job | -Name of job. If not provided, defaults to a job named "build". | -
| 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. | -
| build_parameters | -Additional environment variables to inject into the job environment. A map of names to values. | -
Trigger a new Job with a Branch
curl -X POST --header "Content-Type: application/json" -H "Circle-Token: <circle-token>" -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
-{
- "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, :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
-}
-POST Request: Triggers a new job and then returns a summary of the job run.
| 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. | -
| build_parameters | -Additional environment variables to inject into the job environment. A map of names to values. | -
Note Triggering a new job with a branch is not currently supported with configurations that specify version: 2.1.
Trigger a new Pipeline by Project
- -curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/build -H "Circle-Token: <circle-token>"
-{
- "status": 200,
- "body": "Build created"
- }
-POST Request: Triggers a pipeline 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. The use of this endpoint requires a personal API token.
| Parameter | -Description | -
|---|---|
| revision | -The specific revision to build. If not specified, the HEAD of the branch is used. Cannot be used with tag parameter | -
| branch | -The branch to build. Cannot be used with tag parameter. | -
| tag | -The git tag to build. Cannot be used with branch and revision parameters. | -
Get Test Metadata
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/tests -H "Circle-Token: <circle-token>"
-{
- "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"
- } ]
-}
-GET Request Provides test metadata for a job.
Keys
List Checkout Keys
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key?digest=sha256 -H "Circle-Token: <circle-token>"
-[{"public_key": "ssh-rsa...",
- "type": "deploy-key", // can be "deploy-key" or "github-user-key"
- "fingerprint": "AddwN379YO1pnTyrOqALUZmo6XU4zJ2RLuOZslrl7c4",
- "preferred": true,
- "time" : "2015-09-21T17:29:21.042Z" // when the key was issued
- }]
-GET Request: Returns an array of checkout keys for :project.
| Parameter | -Description | -
|---|---|
| digest | -Fingerprint digest. Optional; 'md5' by default. Pass 'sha256' to return SHA-256 key fingerprint. | -
New Checkout Key
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 -H "Circle-Token: <circle-token>"
-{"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
- }
-POST Request: Creates a new checkout key. This API request is only usable with a user API token. Organizations using GitHub OAuth with SAML SSO may require an additional authorization step to use the key.
| Parameter | -Description | -
|---|---|
| type | -The type of key to create. Can be 'deploy-key' or 'github-user-key'. | -
Get Checkout Key
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key/:fingerprint -H "Circle-Token: <circle-token>"
-{"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 Request: Returns an individual checkout key. Supply fingerprint as a path parameter. Fingerprint can be of type md5 or sha256. sha256 fingerprints should be URL-encoded.
Delete Checkout Key
-DELETE Request: Deletes a checkout key by fingerprint. Supply fingerprint as a path parameter. Fingerprint can be of type md5 or sha256. sha256 fingerprints should be URL-encoded.
curl -X DELETE https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/checkout-key/:fingerprint -H "Circle-Token: <circle-token>"
-{"message":"ok"}
-Create SSH Keys
-POST Request: Creates an SSH key that will be used to access the external system identified by the hostname parameter for SSH key-based authentication.
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 -H "Circle-Token: <circle-token>"
-# no response expected
-Delete SSH Key
curl -X DELETE --header "Content-Type: application/json" -d {"fingerprint":"Fingerprint", "hostname":"Hostname"} https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/ssh-key -H "Circle-Token: <circle-token>"
-# no response expected
-DELETE Request: Deletes an SSH key from the system by fingerprint. Supply fingerprint in request body. Fingerprint can be of type md5 or sha256.
Heroku Keys
-POST Request: Adds your Heroku API key to CircleCI and then takes apikey as form param name.
curl -X POST --header "Content-Type: application/json" -d '{"apikey":"Heroku key"}' https://circleci.com/user/heroku-key -H "Circle-Token: <circle-token>"
-# no response expected
-Artifacts
Artifacts Of A Job
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/:build_num/artifacts -H "Circle-Token: <circle-token>"
-[ {
- "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"
-} ]
-Returns an array of artifacts produced by a given job.
-Request Type: GET
Notes
--
-
- The value of
pathis relative to the project root (the working directory).
- pretty_pathreturns the same value aspath. 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 https://132-55688803-gh.circle-artifacts.com/0//tmp/circle-artifacts.7wgAaIU/file.txt -H "Circle-Token: <circle-token>"
-Notes
--
-
- Make sure your HTTP client is configured to follow redirects as the artifact URLs can respond with
-an HTTP
3xxstatus code (the-Lswitch incurlwill achieve this).
- :tokenis an API token with 'view-builds' scope.
-
Artifacts of the latest Job run
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/latest/artifacts?branch=:branch&filter=:filter -H "Circle-Token: <circle-token>"
-[ {
- "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"
-} ]
-Returns an array of artifacts produced by the latest job run on a given branch.
- -Request Type: GET
| Parameter | -Description | -
|---|---|
| branch | -The branch you would like to look in for the latest job run. Returns artifacts for latest job run in entire project if omitted. | -
| filter | -Restricts which jobs are returned. Set to "completed", "successful", "failed", "running", or defaults to no filter. | -
Notes
--
-
- The value of
pathis relative to the project root (the working directory).
- pretty_pathreturns the same value aspath. It is included in the response for backwards compatibility.
-
Environment Variables
List Environment Variables
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar -H "Circle-Token: <circle-token>"
-[{"name":"foo","value":"xxxx1234"}]
-GET Request: 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.
Add Environment Variables
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 -H "Circle-Token: <circle-token>"
-{"name":"foo","value":"xxxx"}
-POST Request Creates a new environment variable.
Get Single Environment Variable
curl https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar/:name -H "Circle-Token: <circle-token>"
-{"name":"foo","value":"xxxx"}
-GET Request: Returns the hidden value of environment variable :name.
Delete Environment Variables
curl -X DELETE https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/envvar/:name -H "Circle-Token: <circle-token>"
-{"message":"ok"}
-DELETE Request Deletes the environment variable named :name.