NAV Navbar
cURL Ruby Python JavaScript Go

CircleCI API v2

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This describes the resources that make up the CircleCI API v2. API v2 is currently in Preview. Additional documentation for this API can be found in the API Preview Docs. Breaking changes to the API will be announced in the Breaking Changes log.

Base URLs:

License: MIT

Authentication

Insights

Get summary metrics for a project's workflows

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/insights/{project-slug}/workflows \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/insights/{project-slug}/workflows',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/insights/{project-slug}/workflows', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/insights/{project-slug}/workflows',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/insights/{project-slug}/workflows", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /insights/{project-slug}/workflows

Get summary metrics for a project's workflows. Workflow runs going back at most 90 days are included in the aggregation window. Metrics are refreshed daily, and thus may not include executions from the last 24 hours.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
page-token query string false A token to retrieve the next page of results.
branch query string false The name of a vcs branch.

Example responses

200 Response

{
  "items": [
    {
      "name": "build-and-test",
      "window_start": "2020-06-03T08:00:40Z",
      "window_end": "2020-06-03T08:00:40Z",
      "metrics": {
        "success_rate": 0,
        "total_runs": 0,
        "failed_runs": 0,
        "successful_runs": 0,
        "throughput": 0,
        "mttr": 0,
        "total_credits_used": 0,
        "duration_metrics": {
          "min": 0,
          "mean": 0,
          "median": 0,
          "p95": 0,
          "max": 0,
          "standard_deviation": 0
        }
      }
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of summary metrics by workflow Inline

Response Schema

Status Code 200

Paginated workflow summary metrics.

Name Type Required Restrictions Description
» items [object] true none Workflow summary metrics.
»» name string true none The name of the workflow.
»» window_start string(date-time) true none The start of the aggregation window for workflow metrics.
»» window_end string(date-time) true none The end of the aggregation window for workflow metrics.
»» metrics object true none Metrics relating to a workflow's runs.
»»» success_rate number(float) true none The ratio of successful runs / total runs.
»»» total_runs integer(int64) true none The total number of runs.
»»» failed_runs integer(int64) true none The number of failed runs.
»»» successful_runs integer(int64) true none The number of successful runs.
»»» throughput number(float) true none The average number of workflow runs per day.
»»» mttr integer(int64) true none The mean time to recovery (mean time between failures and their next success) in seconds.
»»» total_credits_used integer(int64) true none The total credits consumed by the workflow in the aggregation window.
»»» duration_metrics object true none Metrics relating to the duration of runs for a workflow.
»»»» min integer(int64) true none The minimum duration, in seconds, among a group of runs.
»»»» mean integer(int64) true none The mean duration, in seconds, among a group of runs.
»»»» median integer(int64) true none The median duration, in seconds, among a group of runs.
»»»» p95 integer(int64) true none The 95th percentile duration, in seconds, among a group of runs.
»»»» max integer(int64) true none The max duration, in seconds, among a group of runs.
»»»» standard_deviation number(float) true none The standard deviation, in seconds, among a group of runs.
»»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Get recent runs of a workflow

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /insights/{project-slug}/workflows/{workflow-name}

Get recent runs of a workflow. Runs going back at most 90 days are returned.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
workflow-name path string true The name of the workflow.
branch query string false The name of a vcs branch.
page-token query string false A token to retrieve the next page of results.
start-date path string(date-time) false Include only executions that started at or after this date. This must be specified if an end-date is provided.
end-date path string(date-time) false Include only executions that started before this date. This date can be at most 90 days after the start-date.

Example responses

200 Response

{
  "items": [
    {
      "id": "string",
      "duration": 0,
      "created_at": "2020-06-03T08:00:40Z",
      "stopped_at": "2020-06-03T08:00:40Z",
      "credits_used": 0,
      "status": "success"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of recent workflow runs Inline

Response Schema

Status Code 200

Paginated recent workflow runs.

Name Type Required Restrictions Description
» items [object] true none Recent workflow runs.
»» id string(uuid) true none The unique ID of the workflow.
»» duration integer(int64) true none The duration in seconds of a run.
»» created_at string(date-time) true none The date and time the workflow was created.
»» stopped_at string(date-time) true none The date and time the workflow stopped.
»» credits_used integer(int64) true none The number of credits used during execution
»» status string true none Workflow status.
» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
status success
status failed
status error
status canceled
status unauthorized

Get summary metrics for a project workflow's jobs.

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /insights/{project-slug}/workflows/{workflow-name}/jobs

Get summary metrics for a project workflow's jobs. Job runs going back at most 90 days are included in the aggregation window. Metrics are refreshed daily, and thus may not include executions from the last 24 hours.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
workflow-name path string true The name of the workflow.
page-token query string false A token to retrieve the next page of results.
branch query string false The name of a vcs branch.

Example responses

200 Response

{
  "items": [
    {
      "name": "string",
      "window_start": "2020-06-03T08:00:40Z",
      "window_end": "2020-06-03T08:00:40Z",
      "metrics": {
        "success_rate": 0,
        "total_runs": 0,
        "failed_runs": 0,
        "successful_runs": 0,
        "throughput": 0,
        "total_credits_used": 0,
        "duration_metrics": {
          "min": 0,
          "mean": 0,
          "median": 0,
          "p95": 0,
          "max": 0,
          "standard_deviation": 0
        }
      }
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of summary metrics by workflow job. Inline

Response Schema

Status Code 200

Paginated workflow job summary metrics.

Name Type Required Restrictions Description
» items [object] true none Job summary metrics.
»» name string true none The name of the job.
»» window_start string(date-time) true none The start of the aggregation window for job metrics.
»» window_end string(date-time) true none The end of the aggregation window for job metrics.
»» metrics object true none Metrics relating to a workflow job's runs.
»»» success_rate number(float) true none The ratio of successful runs / total runs.
»»» total_runs integer(int64) true none The total number of runs.
»»» failed_runs integer(int64) true none The number of failed runs.
»»» successful_runs integer(int64) true none The number of successful runs.
»»» throughput number(float) true none The average number of job runs per day.
»»» total_credits_used integer(int64) true none The total credits consumed by the job in the aggregation window.
»»» duration_metrics object true none Metrics relating to the duration of runs for a workflow job.
»»»» min integer(int64) true none The minimum duration, in seconds, among a group of runs.
»»»» mean integer(int64) true none The mean duration, in seconds, among a group of runs.
»»»» median integer(int64) true none The median duration, in seconds, among a group of runs.
»»»» p95 integer(int64) true none The 95th percentile duration, in seconds, among a group of runs.
»»»» max integer(int64) true none The max duration, in seconds, among a group of runs.
»»»» standard_deviation number(float) true none The standard deviation, in seconds, among a group of runs.
»»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Get recent runs of a workflow job

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}

Get recent runs of a job within a workflow. Runs going back at most 90 days are returned.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
workflow-name path string true The name of the workflow.
job-name path string true The name of the job.
branch query string false The name of a vcs branch.
page-token query string false A token to retrieve the next page of results.
start-date path string(date-time) false Include only executions that started at or after this date. This must be specified if an end-date is provided.
end-date path string(date-time) false Include only executions that started before this date. This date can be at most 90 days after the start-date.

Example responses

200 Response

{
  "items": [
    {
      "id": "string",
      "started_at": "2020-06-03T08:00:40Z",
      "stopped_at": "2020-06-03T08:00:40Z",
      "status": "success",
      "credits_used": 0
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of recent job runs Inline

Response Schema

Status Code 200

Paginated recent job runs.

Name Type Required Restrictions Description
» items [object] true none Recent job runs.
»» id string(uuid) true none The unique ID of the job.
»» started_at string(date-time) true none The date and time the job started.
»» stopped_at string(date-time) true none The time when the job stopped.
»» status string true none Job status.
»» credits_used integer(int64) true none The number of credits used during execution
» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
status success
status not_run
status failed
status canceled
status unauthorized

User (Preview)

User Information

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/user/{id} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/user/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/user/{id}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/user/{id}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/user/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /user/{id}

Provides information about the user with the given ID.

Parameters

Name In Type Required Description
id path string(uuid) true The unique ID of the user.

Example responses

200 Response

{
  "id": "string",
  "login": "string",
  "name": "string"
}

Responses

Status Meaning Description Schema
200 OK User login information. Inline

Response Schema

Status Code 200

User

Name Type Required Restrictions Description
» id string(uuid) true none The unique ID of the user.
» login string true none The login information for the user on the VCS.
» name string true none The name of the user.

Collaborations

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/me/collaborations \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/me/collaborations',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/me/collaborations', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/me/collaborations',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/me/collaborations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /me/collaborations

Provides the set of organizations of which a user is a member or a collaborator.

The set of organizations that a user can collaborate on is composed of:

Example responses

200 Response

[
  {
    "vcs-type": "string",
    "name": "string",
    "avatar_url": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK Collaborations Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» Collaboration object false none none
»» vcs-type string true none The VCS provider
»» name string true none The name of the organization
»» avatar_url string true none URL to the user's avatar on the VCS

Pipeline

Get a pipeline

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/pipeline/{pipeline-number} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/pipeline/{pipeline-number}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/pipeline/{pipeline-number}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/pipeline/{pipeline-number}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/pipeline/{pipeline-number}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/pipeline/{pipeline-number}

Returns a pipeline by number.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
pipeline-number path any true The number of the pipeline.

Example responses

200 Response

{
  "id": "string",
  "errors": [
    {
      "type": "config",
      "message": "string"
    }
  ],
  "project_slug": "gh/CircleCI-Public/api-preview-docs",
  "updated_at": "2020-06-03T08:00:40Z",
  "number": 0,
  "state": "created",
  "created_at": "2020-06-03T08:00:40Z",
  "trigger": {
    "type": "explicit",
    "received_at": "2020-06-03T08:00:40Z",
    "actor": {
      "login": "string",
      "avatar_url": "string"
    }
  },
  "vcs": {
    "provider_name": "GitHub",
    "origin_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
    "target_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
    "revision": "f454a02b5d10fcccfd7d9dd7608a76d6493a98b4",
    "branch": "feature/design-new-api",
    "tag": "v3.1.4159",
    "commit": {
      "subject": "string",
      "body": "string"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK A pipeline object. Inline

Response Schema

Status Code 200

Pipeline

Name Type Required Restrictions Description
» id string(uuid) true none The unique ID of the pipeline.
» errors [object] true none A sequence of errors that have occurred within the pipeline.
»» type string true none The type of error.
»» message string true none A human-readable error message.
» project_slug string true none The project-slug for the pipeline.
» updated_at string(date-time) false none The date and time the pipeline was last updated.
» number integer(int64) true none The number of the pipeline.
» state string true none The current state of the pipeline.
» created_at string(date-time) true none The date and time the pipeline was created.
» trigger object true none A summary of the trigger.
»» type string true none The type of trigger.
»» received_at string(date-time) true none The date and time the trigger was received.
»» actor object true none The user who triggered the Pipeline.
»»» login string true none The login information for the user on the VCS.
»»» avatar_url string true none URL to the user's avatar on the VCS
»» vcs object false none VCS information for the pipeline.
»»» provider_name string true none Name of the VCS provider (e.g. GitHub, Bitbucket).
»»» origin_repository_url string true none URL for the repository where the trigger originated. For fork-PR pipelines, this is the URL to the fork. For other pipelines the origin_ and target_repository_urls will be the same.
»»» target_repository_url string true none URL for the repository the trigger targets (i.e. the repository where the PR will be merged). For fork-PR pipelines, this is the URL to the parent repo. For other pipelines, the origin_ and target_repository_urls will be the same.
»»» revision string true none The code revision the pipeline ran.
»»» branch string false none The branch where the pipeline ran. The HEAD commit on this branch was used for the pipeline. Note that branch and tag are mutually exclusive.
»»» tag string false none The tag used by the pipeline. The commit that this tag points to was used for the pipeline. Note that branch and tag are mutually exclusive.
»»» commit object false none The latest commit in the pipeline.
»»»» subject string true none The subject of the commit message.
»»»» body string true none The body of the commit message.

Enumerated Values

Property Value
type config
type plan
state created
state errored
state pending
type explicit
type api
type webhook

ProjectFromPipeline => getProjectBySlug

Parameter Expression
project_slug $response.body#/project_slug

Get a pipeline's configuration

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/pipeline/{pipeline-id}/config \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/pipeline/{pipeline-id}/config',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/pipeline/{pipeline-id}/config', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/pipeline/{pipeline-id}/config',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/pipeline/{pipeline-id}/config", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /pipeline/{pipeline-id}/config

Returns a pipeline's configuration by ID.

Parameters

Name In Type Required Description
pipeline-id path string(uuid) true The unique ID of the pipeline.

Example responses

200 Response

{
  "source": "string",
  "compiled": "string"
}

Responses

Status Meaning Description Schema
200 OK The configuration strings for the pipeline. Inline

Response Schema

Status Code 200

PipelineConfig

Name Type Required Restrictions Description
» source string true none The source configuration for the pipeline, before any config compilation has been performed. If there is no config, then this field will be empty.
» compiled string true none The compiled configuration for the pipeline, after all orb expansion has been performed. If there were errors processing the pipeline's configuration, then this field may be empty.

Get a pipeline's workflows

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/pipeline/{pipeline-id}/workflow \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/pipeline/{pipeline-id}/workflow',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/pipeline/{pipeline-id}/workflow', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/pipeline/{pipeline-id}/workflow',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/pipeline/{pipeline-id}/workflow", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /pipeline/{pipeline-id}/workflow

Returns a paginated list of workflows by pipeline ID.

Parameters

Name In Type Required Description
pipeline-id path string(uuid) true The unique ID of the pipeline.
page-token query string false A token to retrieve the next page of results.

Example responses

200 Response

{
  "items": [
    {
      "pipeline_id": "string",
      "canceled_by": "string",
      "id": "string",
      "name": "build-and-test",
      "project_slug": "gh/CircleCI-Public/api-preview-docs",
      "errored_by": "string",
      "status": "success",
      "started_by": "string",
      "pipeline_number": 0,
      "created_at": "2020-06-03T08:00:40Z",
      "stopped_at": "2020-06-03T08:00:40Z"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of workflow objects. Inline

Response Schema

Status Code 200

WorkflowListResponse

Name Type Required Restrictions Description
» items [object] true none A list of workflows.
»» Workflow object false none A workflow
»»» pipeline_id string(uuid) true none The ID of the pipeline this workflow belongs to.
»»» canceled_by string(uuid) false none none
»»» id string(uuid) true none The unique ID of the workflow.
»»» name string true none The name of the workflow.
»»» project_slug string true none The project-slug for the pipeline this workflow belongs to.
»»» errored_by string(uuid) false none none
»»» status string true none The current status of the workflow.
»»» started_by string(uuid) true none none
»»» pipeline_number integer(int64) true none The number of the pipeline this workflow belongs to.
»»» created_at string(date-time) true none The date and time the workflow was created.
»»» stopped_at string(date-time) true none The date and time the workflow stopped.
»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
status success
status running
status not_run
status failed
status error
status failing
status on_hold
status canceled
status unauthorized

NextPipelineWorkflowsPage => listWorkflowsByPipelineId

Parameter Expression
pipeline-id $request.path.pipeline-id

Trigger a new pipeline

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/project/{project-slug}/pipeline \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-attribution-login: string' \
  -H 'x-attribution-actor-id: string'

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-attribution-login' => 'string',
  'x-attribution-actor-id' => 'string'
}

result = RestClient.post 'https://circleci.com/api/v2/project/{project-slug}/pipeline',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-attribution-login': 'string',
  'x-attribution-actor-id': 'string'
}

r = requests.post('https://circleci.com/api/v2/project/{project-slug}/pipeline', params={

}, headers = headers)

print r.json()

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-attribution-login':'string',
  'x-attribution-actor-id':'string'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/pipeline',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-attribution-login": []string{"string"},
        "x-attribution-actor-id": []string{"string"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/project/{project-slug}/pipeline", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /project/{project-slug}/pipeline

Triggers a new pipeline on the project.

Body parameter

{
  "branch": "feature/design-new-api",
  "tag": "v3.1.4159",
  "parameters": {
    "deploy_prod": true
  }
}

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
x-attribution-login header string false The login or user-readable identifier for the pipeline's triggerer. Internal use only.
x-attribution-actor-id header string false The id the integration uses to identify the pipeline's triggerer. Internal use only.
body body object false none
» branch body string false The branch where the pipeline ran. The HEAD commit on this branch was used for the pipeline. Note that branch and tag are mutually exclusive.
» tag body string false The tag used by the pipeline. The commit that this tag points to was used for the pipeline. Note that branch and tag are mutually exclusive.
» parameters body object false An object containing pipeline parameters and their values.
»» additionalProperties body any false none
»»» anonymous body integer false none
»»» anonymous body string false none
»»» anonymous body boolean false none

Example responses

201 Response

{
  "id": "string",
  "state": "created",
  "number": 0,
  "created_at": "2020-06-03T08:00:40Z"
}

Responses

Status Meaning Description Schema
201 Created The created pipeline. Inline

Response Schema

Status Code 201

PipelineLight

Name Type Required Restrictions Description
» id string(uuid) true none The unique ID of the pipeline.
» state string true none The current state of the pipeline.
» number integer(int64) true none The number of the pipeline.
» created_at string(date-time) true none The date and time the pipeline was created.

Enumerated Values

Property Value
state created
state errored
state pending

Get all pipelines

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/pipeline \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/pipeline',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/pipeline', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/pipeline',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/pipeline", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/pipeline

Returns all pipelines for this project.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
branch query string false The name of a vcs branch.
page-token query string false A token to retrieve the next page of results.

Example responses

200 Response

{
  "items": [
    {
      "id": "string",
      "errors": [
        {
          "type": "config",
          "message": "string"
        }
      ],
      "project_slug": "gh/CircleCI-Public/api-preview-docs",
      "updated_at": "2020-06-03T08:00:40Z",
      "number": 0,
      "state": "created",
      "created_at": "2020-06-03T08:00:40Z",
      "trigger": {
        "type": "explicit",
        "received_at": "2020-06-03T08:00:40Z",
        "actor": {
          "login": "string",
          "avatar_url": "string"
        }
      },
      "vcs": {
        "provider_name": "GitHub",
        "origin_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
        "target_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
        "revision": "f454a02b5d10fcccfd7d9dd7608a76d6493a98b4",
        "branch": "feature/design-new-api",
        "tag": "v3.1.4159",
        "commit": {
          "subject": "string",
          "body": "string"
        }
      }
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A sequence of pipelines. Inline

Response Schema

Status Code 200

PipelineListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» Pipeline object false none NOTE: The definition of pipeline is subject to change.
»»» id string(uuid) true none The unique ID of the pipeline.
»»» errors [object] true none A sequence of errors that have occurred within the pipeline.
»»»» type string true none The type of error.
»»»» message string true none A human-readable error message.
»»» project_slug string true none The project-slug for the pipeline.
»»» updated_at string(date-time) false none The date and time the pipeline was last updated.
»»» number integer(int64) true none The number of the pipeline.
»»» state string true none The current state of the pipeline.
»»» created_at string(date-time) true none The date and time the pipeline was created.
»»» trigger object true none A summary of the trigger.
»»»» type string true none The type of trigger.
»»»» received_at string(date-time) true none The date and time the trigger was received.
»»»» actor object true none The user who triggered the Pipeline.
»»»»» login string true none The login information for the user on the VCS.
»»»»» avatar_url string true none URL to the user's avatar on the VCS
»»»» vcs object false none VCS information for the pipeline.
»»»»» provider_name string true none Name of the VCS provider (e.g. GitHub, Bitbucket).
»»»»» origin_repository_url string true none URL for the repository where the trigger originated. For fork-PR pipelines, this is the URL to the fork. For other pipelines the origin_ and target_repository_urls will be the same.
»»»»» target_repository_url string true none URL for the repository the trigger targets (i.e. the repository where the PR will be merged). For fork-PR pipelines, this is the URL to the parent repo. For other pipelines, the origin_ and target_repository_urls will be the same.
»»»»» revision string true none The code revision the pipeline ran.
»»»»» branch string false none The branch where the pipeline ran. The HEAD commit on this branch was used for the pipeline. Note that branch and tag are mutually exclusive.
»»»»» tag string false none The tag used by the pipeline. The commit that this tag points to was used for the pipeline. Note that branch and tag are mutually exclusive.
»»»»» commit object false none The latest commit in the pipeline.
»»»»»» subject string true none The subject of the commit message.
»»»»»» body string true none The body of the commit message.
»»»»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
type config
type plan
state created
state errored
state pending
type explicit
type api
type webhook

NextPipelinePage => listPipelinesForProject

Parameter Expression
project-slug $request.path.project-slug

Get your pipelines

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/pipeline/mine \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/pipeline/mine',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/pipeline/mine', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/pipeline/mine',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/pipeline/mine", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/pipeline/mine

Returns a sequence of all pipelines for this project triggered by the user.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
page-token query string false A token to retrieve the next page of results.

Example responses

200 Response

{
  "items": [
    {
      "id": "string",
      "errors": [
        {
          "type": "config",
          "message": "string"
        }
      ],
      "project_slug": "gh/CircleCI-Public/api-preview-docs",
      "updated_at": "2020-06-03T08:00:40Z",
      "number": 0,
      "state": "created",
      "created_at": "2020-06-03T08:00:40Z",
      "trigger": {
        "type": "explicit",
        "received_at": "2020-06-03T08:00:40Z",
        "actor": {
          "login": "string",
          "avatar_url": "string"
        }
      },
      "vcs": {
        "provider_name": "GitHub",
        "origin_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
        "target_repository_url": "https://github.com/CircleCI-Public/api-preview-docs",
        "revision": "f454a02b5d10fcccfd7d9dd7608a76d6493a98b4",
        "branch": "feature/design-new-api",
        "tag": "v3.1.4159",
        "commit": {
          "subject": "string",
          "body": "string"
        }
      }
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A sequence of pipelines. Inline

Response Schema

Status Code 200

PipelineListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» Pipeline object false none NOTE: The definition of pipeline is subject to change.
»»» id string(uuid) true none The unique ID of the pipeline.
»»» errors [object] true none A sequence of errors that have occurred within the pipeline.
»»»» type string true none The type of error.
»»»» message string true none A human-readable error message.
»»» project_slug string true none The project-slug for the pipeline.
»»» updated_at string(date-time) false none The date and time the pipeline was last updated.
»»» number integer(int64) true none The number of the pipeline.
»»» state string true none The current state of the pipeline.
»»» created_at string(date-time) true none The date and time the pipeline was created.
»»» trigger object true none A summary of the trigger.
»»»» type string true none The type of trigger.
»»»» received_at string(date-time) true none The date and time the trigger was received.
»»»» actor object true none The user who triggered the Pipeline.
»»»»» login string true none The login information for the user on the VCS.
»»»»» avatar_url string true none URL to the user's avatar on the VCS
»»»» vcs object false none VCS information for the pipeline.
»»»»» provider_name string true none Name of the VCS provider (e.g. GitHub, Bitbucket).
»»»»» origin_repository_url string true none URL for the repository where the trigger originated. For fork-PR pipelines, this is the URL to the fork. For other pipelines the origin_ and target_repository_urls will be the same.
»»»»» target_repository_url string true none URL for the repository the trigger targets (i.e. the repository where the PR will be merged). For fork-PR pipelines, this is the URL to the parent repo. For other pipelines, the origin_ and target_repository_urls will be the same.
»»»»» revision string true none The code revision the pipeline ran.
»»»»» branch string false none The branch where the pipeline ran. The HEAD commit on this branch was used for the pipeline. Note that branch and tag are mutually exclusive.
»»»»» tag string false none The tag used by the pipeline. The commit that this tag points to was used for the pipeline. Note that branch and tag are mutually exclusive.
»»»»» commit object false none The latest commit in the pipeline.
»»»»»» subject string true none The subject of the commit message.
»»»»»» body string true none The body of the commit message.
»»»»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
type config
type plan
state created
state errored
state pending
type explicit
type api
type webhook

NextPipelinePage => listMyPipelines

Parameter Expression
project-slug $request.path.project-slug

Project (Preview)

Get a project

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}

Retrieves a project by project slug.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "slug": "gh/CircleCI-Public/api-preview-docs",
  "name": "api-preview-docs",
  "organization_name": "CircleCI-Public",
  "vcs_info": {
    "vcs_url": "https://github.com/CircleCI-Public/api-preview-docs",
    "provider": "Bitbucket",
    "default_branch": "master"
  }
}

Responses

Status Meaning Description Schema
200 OK A project object Inline

Response Schema

Status Code 200

Project

Name Type Required Restrictions Description
» slug string true none Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
» name string true none The name of the project
» organization_name string true none The name of the organization the project belongs to
» vcs_info object true none Information about the VCS that hosts the project source code.
»» vcs_url string true none URL to the repository hosting the project's code
»» provider string true none The VCS provider
»» default_branch string true none none

Enumerated Values

Property Value
provider Bitbucket
provider GitHub

Get all checkout keys

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/checkout-key \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/checkout-key',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/checkout-key', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/checkout-key',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/checkout-key", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/checkout-key

Returns a sequence of checkout keys for :project.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "items": [
    {
      "public-key": "ssh-rsa ...",
      "type": "deploy-key",
      "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
      "preferred": true,
      "created-at": "2015-09-21T17:29:21.042Z"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A sequence of checkout keys. Inline

Response Schema

Status Code 200

CheckoutKeyListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» CheckoutKey object false none none
»»» public-key string true none A public SSH key.
»»» type string true none The type of checkout key. This may be either deploy-key or github-user-key.
»»» fingerprint string true none An SSH key fingerprint.
»»» preferred boolean true none A boolean value that indicates if this key is preferred.
»»» created-at string(date-time) true none The date and time the checkout key was created.
»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
type deploy-key
type github-user-key

Create a new checkout key

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/project/{project-slug}/checkout-key \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/project/{project-slug}/checkout-key',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/project/{project-slug}/checkout-key', params={

}, headers = headers)

print r.json()

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/checkout-key',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/project/{project-slug}/checkout-key", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /project/{project-slug}/checkout-key

Creates a new checkout key. This API request is only usable with a user API token.

Body parameter

{
  "type": "deploy-key"
}

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
body body object false none
» type body string true The type of checkout key to create. This may be either deploy-key or user-key.

Enumerated Values

Parameter Value
» type user-key
» type deploy-key

Example responses

201 Response

{
  "public-key": "ssh-rsa ...",
  "type": "deploy-key",
  "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  "preferred": true,
  "created-at": "2015-09-21T17:29:21.042Z"
}

Responses

Status Meaning Description Schema
201 Created The checkout key. Inline

Response Schema

Status Code 201

CheckoutKey

Name Type Required Restrictions Description
» public-key string true none A public SSH key.
» type string true none The type of checkout key. This may be either deploy-key or github-user-key.
» fingerprint string true none An SSH key fingerprint.
» preferred boolean true none A boolean value that indicates if this key is preferred.
» created-at string(date-time) true none The date and time the checkout key was created.

Enumerated Values

Property Value
type deploy-key
type github-user-key

Delete a checkout key

Code samples

# You can also use wget
curl -X DELETE https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}',
  method: 'delete',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /project/{project-slug}/checkout-key/{fingerprint}

Deletes the checkout key.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
fingerprint path string true An SSH key fingerprint.

Example responses

200 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK A confirmation message. Inline

Response Schema

Status Code 200

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message

Get a checkout key

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/checkout-key/{fingerprint}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/checkout-key/{fingerprint}

Returns an individual checkout key.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
fingerprint path string true An SSH key fingerprint.

Example responses

200 Response

{
  "public-key": "ssh-rsa ...",
  "type": "deploy-key",
  "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  "preferred": true,
  "created-at": "2015-09-21T17:29:21.042Z"
}

Responses

Status Meaning Description Schema
200 OK The checkout key. Inline

Response Schema

Status Code 200

CheckoutKey

Name Type Required Restrictions Description
» public-key string true none A public SSH key.
» type string true none The type of checkout key. This may be either deploy-key or github-user-key.
» fingerprint string true none An SSH key fingerprint.
» preferred boolean true none A boolean value that indicates if this key is preferred.
» created-at string(date-time) true none The date and time the checkout key was created.

Enumerated Values

Property Value
type deploy-key
type github-user-key

List all environment variables

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/envvar \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/envvar',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/envvar', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/envvar',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/envvar", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/envvar

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

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "items": [
    {
      "name": "foo",
      "value": "xxxx1234"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A sequence of environment variables. Inline

Response Schema

Status Code 200

EnvironmentVariableListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» EnvironmentVariablePair object false none none
»»» name string true none The name of the environment variable.
»»» value string true none The value of the environment variable.
»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Create an environment variable

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/project/{project-slug}/envvar \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/project/{project-slug}/envvar',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/project/{project-slug}/envvar', params={

}, headers = headers)

print r.json()

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/envvar',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/project/{project-slug}/envvar", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /project/{project-slug}/envvar

Creates a new environment variable.

Body parameter

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

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
body body object false none
» name body string true The name of the environment variable.
» value body string true The value of the environment variable.

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created The environment variable. Inline

Response Schema

Status Code 201

EnvironmentVariablePair

Name Type Required Restrictions Description
» name string true none The name of the environment variable.
» value string true none The value of the environment variable.

Delete an environment variable

Code samples

# You can also use wget
curl -X DELETE https://circleci.com/api/v2/project/{project-slug}/envvar/{name} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://circleci.com/api/v2/project/{project-slug}/envvar/{name}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('https://circleci.com/api/v2/project/{project-slug}/envvar/{name}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/envvar/{name}',
  method: 'delete',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://circleci.com/api/v2/project/{project-slug}/envvar/{name}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /project/{project-slug}/envvar/{name}

Deletes the environment variable named :name.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
name path string true The name of the environment variable.

Example responses

200 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
200 OK A confirmation message. Inline

Response Schema

Status Code 200

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message

Get a masked environment variable

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/envvar/{name} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/envvar/{name}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/envvar/{name}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/envvar/{name}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/envvar/{name}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/envvar/{name}

Returns the masked value of environment variable :name.

Parameters

Name In Type Required Description
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
name path string true The name of the environment variable.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK The environment variable. Inline

Response Schema

Status Code 200

EnvironmentVariablePair

Name Type Required Restrictions Description
» name string true none The name of the environment variable.
» value string true none The value of the environment variable.

Job (Preview)

Get job details

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/job/{job-number} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/job/{job-number}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/job/{job-number}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/job/{job-number}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/job/{job-number}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/job/{job-number}

Returns job details.

Parameters

Name In Type Required Description
job-number path any true The number of the job.
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "web_url": "string",
  "project": {
    "slug": "gh/CircleCI-Public/api-preview-docs",
    "name": "api-preview-docs",
    "external_url": "https://github.com/CircleCI-Public/api-preview-docs"
  },
  "parallel_runs": [
    {
      "index": 0,
      "status": "string"
    }
  ],
  "started_at": "2020-06-03T08:00:40Z",
  "latest_workflow": {
    "id": "string",
    "name": "build-and-test"
  },
  "name": "string",
  "executor": {
    "type": "string",
    "resource_class": "string"
  },
  "parallelism": 0,
  "status": null,
  "number": 0,
  "pipeline": {
    "id": "string"
  },
  "duration": 0,
  "created_at": "2020-06-03T08:00:40Z",
  "messages": [
    {
      "type": "string",
      "message": "string",
      "reason": "string"
    }
  ],
  "contexts": [
    {
      "name": "string"
    }
  ],
  "organization": {
    "name": "string"
  },
  "queued_at": "2020-06-03T08:00:40Z",
  "stopped_at": "2020-06-03T08:00:40Z"
}

Responses

Status Meaning Description Schema
200 OK Job details. Inline

Response Schema

Status Code 200

Job Details

Name Type Required Restrictions Description
» web_url string true none URL of the job in CircleCI Web UI.
» project object true none Information about a project.
»» slug string true none Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.
»» name string true none The name of the project
»» external_url string true none URL to the repository hosting the project's code
» parallel_runs [object] true none Info about parallels runs and their status.
»» index integer(int64) true none Index of the parallel run.
»» status string true none Status of the parallel run.
» started_at string(date-time) true none The date and time the job started.
» latest_workflow object true none Info about the latest workflow the job was a part of.
»» id string(uuid) true none The unique ID of the workflow.
»» name string true none The name of the workflow.
» name string true none The name of the job.
» executor object true none Information about executor used for a job.
»» type string true none Executor type.
»» resource_class string true none Resource class name.
» parallelism integer(int64) true none A number of parallel runs the job has.
» status any true none The current status of the job.
» number integer(int64) true none The number of the job.
» pipeline object true none Info about a pipeline the job is a part of.
»» id string(uuid) true none The unique ID of the pipeline.
» duration integer(int64) true none Duration of a job in milliseconds.
» created_at string(date-time) true none The time when the job was created.
» messages [object] true none Messages from CircleCI execution platform.
»» type string true none Message type.
»» message string true none Information describing message.
»» reason string false none Value describing the reason for message to be added to the job.
» contexts [object] true none List of contexts used by the job.
»» name string true none The name of the context.
» organization object true none Information about an organization.
»» name string true none The name of the organization.
» queued_at string(date-time) true none The time when the job was placed in a queue.
» stopped_at string(date-time) false none The time when the job stopped.

Cancel job

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/project/{project-slug}/job/{job-number}/cancel \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/project/{project-slug}/job/{job-number}/cancel',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/project/{project-slug}/job/{job-number}/cancel', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/job/{job-number}/cancel',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/project/{project-slug}/job/{job-number}/cancel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /project/{project-slug}/job/{job-number}/cancel

Cancel job with a given job number.

Parameters

Name In Type Required Description
job-number path any true The number of the job.
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

202 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
202 Accepted none Inline

Response Schema

Status Code 202

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message

Get a job's artifacts

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/{job-number}/artifacts \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/{job-number}/artifacts',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/{job-number}/artifacts', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/{job-number}/artifacts',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/{job-number}/artifacts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/{job-number}/artifacts

Returns a job's artifacts.

Parameters

Name In Type Required Description
job-number path any true The number of the job.
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "items": [
    {
      "path": "string",
      "node_index": 0,
      "url": "string"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of the job's artifacts. Inline

Response Schema

Status Code 200

ArtifactListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» Artifact object false none An artifact
»»» path string true none The artifact path.
»»» node_index integer(int64) true none The index of the node that stored the artifact.
»»» url string true none The URL to download the artifact contents.
»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Get test metadata

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/project/{project-slug}/{job-number}/tests", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /project/{project-slug}/{job-number}/tests

Get test metadata for a build.

Parameters

Name In Type Required Description
job-number path any true The number of the job.
project-slug path string true Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped.

Example responses

200 Response

{
  "items": [
    {
      "message": "",
      "file": "",
      "result": "",
      "name": "",
      "classname": ""
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated list of test results. Inline

Response Schema

Status Code 200

TestsResponse

Name Type Required Restrictions Description
» items [object] true none none
»» message string true none The failure message associated with the test.
»» file string true none The file in which the test is defined.
»» result string true none Indication of whether the test succeeded.
»» name string true none The name of the test.
»» classname string true none The programmatic location of the test.
» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Workflow

Get a workflow

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/workflow/{id} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/workflow/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/workflow/{id}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/workflow/{id}',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/workflow/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /workflow/{id}

Returns summary fields of a workflow by ID.

Parameters

Name In Type Required Description
id path string(uuid) true The unique ID of the workflow.

Example responses

200 Response

{
  "pipeline_id": "string",
  "canceled_by": "string",
  "id": "string",
  "name": "build-and-test",
  "project_slug": "gh/CircleCI-Public/api-preview-docs",
  "errored_by": "string",
  "status": "success",
  "started_by": "string",
  "pipeline_number": 0,
  "created_at": "2020-06-03T08:00:40Z",
  "stopped_at": "2020-06-03T08:00:40Z"
}

Responses

Status Meaning Description Schema
200 OK A workflow object. Inline

Response Schema

Status Code 200

Workflow

Name Type Required Restrictions Description
» pipeline_id string(uuid) true none The ID of the pipeline this workflow belongs to.
» canceled_by string(uuid) false none none
» id string(uuid) true none The unique ID of the workflow.
» name string true none The name of the workflow.
» project_slug string true none The project-slug for the pipeline this workflow belongs to.
» errored_by string(uuid) false none none
» status string true none The current status of the workflow.
» started_by string(uuid) true none none
» pipeline_number integer(int64) true none The number of the pipeline this workflow belongs to.
» created_at string(date-time) true none The date and time the workflow was created.
» stopped_at string(date-time) true none The date and time the workflow stopped.

Enumerated Values

Property Value
status success
status running
status not_run
status failed
status error
status failing
status on_hold
status canceled
status unauthorized

ProjectFromGetWorkflow => getProjectBySlug

Parameter Expression
project_slug $response.body#/project_slug

WorkflowJobs => listWorkflowJobs

Parameter Expression
id $response.body#/id

CancelWorkflow => cancelWorkflow

Parameter Expression
id $response.body#/id

Approve a job

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/workflow/{id}/approve/{approval_request_id} \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/workflow/{id}/approve/{approval_request_id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/workflow/{id}/approve/{approval_request_id}', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/workflow/{id}/approve/{approval_request_id}',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/workflow/{id}/approve/{approval_request_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /workflow/{id}/approve/{approval_request_id}

Approves a pending approval job in a workflow.

Parameters

Name In Type Required Description
approval_request_id path string(uuid) true The ID of the job being approved.
id path string(uuid) true The unique ID of the workflow.

Example responses

202 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
202 Accepted A confirmation message. Inline

Response Schema

Status Code 202

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message

Cancel a workflow

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/workflow/{id}/cancel \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/workflow/{id}/cancel',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/workflow/{id}/cancel', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/workflow/{id}/cancel',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/workflow/{id}/cancel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /workflow/{id}/cancel

Cancels a running workflow.

Parameters

Name In Type Required Description
id path string(uuid) true The unique ID of the workflow.

Example responses

202 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
202 Accepted A confirmation message. Inline

Response Schema

Status Code 202

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message

Get a workflow's jobs

Code samples

# You can also use wget
curl -X GET https://circleci.com/api/v2/workflow/{id}/job \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://circleci.com/api/v2/workflow/{id}/job',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://circleci.com/api/v2/workflow/{id}/job', params={

}, headers = headers)

print r.json()

var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/workflow/{id}/job',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://circleci.com/api/v2/workflow/{id}/job", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /workflow/{id}/job

Returns a sequence of jobs for a workflow.

Parameters

Name In Type Required Description
id path string(uuid) true The unique ID of the workflow.

Example responses

200 Response

{
  "items": [
    {
      "canceled_by": "string",
      "dependencies": [
        "string"
      ],
      "job_number": 0,
      "id": "string",
      "started_at": "2020-06-03T08:00:40Z",
      "name": "string",
      "approved_by": "string",
      "project_slug": "gh/CircleCI-Public/api-preview-docs",
      "status": null,
      "type": "build",
      "stopped_at": "2020-06-03T08:00:40Z",
      "approval_request_id": "string"
    }
  ],
  "next_page_token": "string"
}

Responses

Status Meaning Description Schema
200 OK A paginated sequence of jobs. Inline

Response Schema

Status Code 200

WorkflowJobListResponse

Name Type Required Restrictions Description
» items [object] true none none
»» Job object false none Job
»»» canceled_by string(uuid) false none The unique ID of the user.
»»» dependencies [string] true none A sequence of the unique job IDs for the jobs that this job depends upon in the workflow.
»»» job_number integer(int64) false none The number of the job.
»»» id string(uuid) true none The unique ID of the job.
»»» started_at string(date-time) true none The date and time the job started.
»»» name string true none The name of the job.
»»» approved_by string(uuid) false none The unique ID of the user.
»»» project_slug string true none The project-slug for the job.
»»» status any true none The current status of the job.
»»» type string true none The type of job.
»»» stopped_at string(date-time) false none The time when the job stopped.
»»» approval_request_id string(uuid) false none The unique ID of the job.
»» next_page_token string true none A token to pass as a page-token query parameter to return the next page of results.

Enumerated Values

Property Value
type build
type approval

NextWorkflowJobPage => listWorkflowJobs

Parameter Expression
id $request.path.id

Rerun a workflow

Code samples

# You can also use wget
curl -X POST https://circleci.com/api/v2/workflow/{id}/rerun \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://circleci.com/api/v2/workflow/{id}/rerun',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://circleci.com/api/v2/workflow/{id}/rerun', params={

}, headers = headers)

print r.json()

var headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

$.ajax({
  url: 'https://circleci.com/api/v2/workflow/{id}/rerun',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://circleci.com/api/v2/workflow/{id}/rerun", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /workflow/{id}/rerun

Reruns a workflow.

Body parameter

{
  "jobs": [
    "c65b68ef-e73b-4bf2-be9a-7a322a9df150",
    "5e957edd-5e8c-4985-9178-5d0d69561822"
  ],
  "from_failed": false
}

Parameters

Name In Type Required Description
id path string(uuid) true The unique ID of the workflow.
body body object false none
» jobs body [string] false A list of job IDs to rerun.
» from_failed body boolean false Whether to rerun the workflow from the failed job. Mutually exclusive with the jobs parameter.

Example responses

202 Response

{
  "message": "string"
}

Responses

Status Meaning Description Schema
202 Accepted A confirmation message. Inline

Response Schema

Status Code 202

MessageResponse

Name Type Required Restrictions Description
» message string true none A human-readable message