Skip to main content
Mapagam

Using CircleCI API

1. Authenticating with API

Method Description Authentication Required Notes
Personal API Token Generate a token in CircleCI UI under User Settings Yes Used for API v2
CircleCI Token Used for API v2, can be generated via CircleCI UI or CLI Yes Can be scoped to specific projects or permissions
OAuth 2.0 For third-party integrations and applications Yes Requires OAuth flow setup in CircleCI

Example: Using Personal API Token

curl -H "Circle-Token: <your-token>" \\\n  https://circleci.com/api/v2/project/github/owner/repo
Note: Personal API tokens are tied to your user account and can be used for any project you have access to. For better security, consider using project-specific tokens or OAuth 2.0.

2. Triggering Pipelines

Field Description Example
pipeline The pipeline to trigger 123456
branch Branch to run the pipeline on main
tag Tag to run the pipeline on v1.0.0
parameters Parameters to pass to the pipeline {"env": "prod"}

Example: Triggering a Pipeline

curl -X POST https://circleci.com/api/v2/project/<VCS>/<ORG>/<PROJECT>/pipeline \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Circle-Token: <API_TOKEN>' \
  -d '{"branch":"main","parameters":{"env":"prod"}}'
Note: The Circle-Token must have appropriate permissions to trigger pipelines.

3. Getting Pipeline Status

Field Description Example
status Pipeline execution status success, running, failed
created_at Timestamp when pipeline was created 2023-10-01T12:00:00Z
updated_at Timestamp when pipeline was last updated 2023-10-01T12:05:00Z
branch Branch name that triggered the pipeline main
vcs_url URL to the VCS repository https://github.com/example/repo

Example: Fetch Pipeline Status

curl -H "Circle-Token: <TOKEN>" \
  https://circleci.com/api/v2/pipeline/123456789
Note: Replace <TOKEN> with your CircleCI API token.

4. Listing Workflows

Property Description Example
project_slug Unique identifier for the project in CircleCI github/myorg/myproject
branch Branch name to filter workflows main
status Filter workflows by status (success, failed, running) success
limit Maximum number of workflows to return (default: 30) 5

Example: Fetching Workflows

curl -H "Circle-Token: <token>" \
  "https://circleci.com/api/v2/project/github/myorg/myproject/workflow?branch=main&limit=5"
Note: The Circle-Token must be a valid API token with appropriate permissions to access project workflows.

5. Getting Job Details

Field Description Example
job_number Unique identifier for the job 12345
status Current status of the job (running, success, failed) success
start_time Start time of the job in ISO 8601 format 2025-04-05T10:00:00Z
end_time End time of the job in ISO 8601 format 2025-04-05T10:05:00Z
duration Duration of the job in seconds 300
workflow_id UUID of the workflow this job belongs to a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example: Fetch Job Details

curl -H "Circle-Token: <your-token>" \
  https://circleci.com/api/v2/project/github/owner/repo/job/12345
Note: You must have appropriate permissions to access job details.

6. Canceling Workflows

Property Description Value
workflow_id Unique identifier for the workflow to cancel string
project_slug Slug of the project (e.g., github/owner/repo) string
branch Branch name (optional, used for filtering) string

Example: Cancel a Workflow via API

curl -X POST \
  "https://circleci.com/api/v2/workflow/<workflow_id>/cancel" \
  -H "Circle-Token: <api_token>"
Note: The workflow_id must be obtained from a previous API call or job output.
Warning: Canceling a workflow does not stop running jobs immediately; it prevents new jobs from starting.

7. Rerunning Workflows

Property Description Value
workflow_id Unique identifier for the workflow to rerun string
project_slug Slug of the project (e.g., github/owner/repo) string
branch Branch name to rerun workflow on (optional) string

Example: Rerun a Workflow via API

curl -X POST \
  "https://circleci.com/api/v2/workflow/<workflow_id>/rerun" \
  -H "Circle-Token: <token>" \
  -H "Content-Type: application/json"
Note: The workflow_id can be obtained from the CircleCI UI or via the API using /project/<project_slug>/workflow.

8. Downloading Artifacts

Property Description Example
artifact path Path to the artifact on the executor ./build/dist/app.js
artifact destination Destination path for downloaded artifact /tmp/app.js

Example: Downloading Artifacts via API

curl -H "Circle-Token: <TOKEN>" \
     -X GET \
     "https://circleci.com/api/v2/project/github/ORG/REPO/artifacts/<BUILD_NUMBER>" \
     -o artifact.zip
Note: Artifacts must be uploaded during the build process using save_artifacts or similar configuration in your CircleCI config.
Warning: Ensure that the Circle-Token has appropriate permissions to access artifacts.

9. Managing Environment Variables

Property Value Description
CIRCLECI_API_TOKEN string API token for authenticating with CircleCI API
CIRCLECI_PROJECT_SLUG string Project identifier in the format owner/project

Example: Setting Environment Variables via API

curl -X POST https://circleci.com/api/v2/project/<PROJECT_SLUG>/envvar \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Circle-Token: <API_TOKEN>" \
  -d '{"name":"MY_VAR","value":"my_value"}'

Example: Listing Environment Variables

curl -X GET https://circleci.com/api/v2/project/<PROJECT_SLUG>/envvar \
  -H 'Accept: application/json' \
  -H "Circle-Token: <API_TOKEN>"

Example: Deleting an Environment Variable

curl -X DELETE https://circleci.com/api/v2/project/<PROJECT_SLUG>/envvar/MY_VAR \
  -H 'Accept: application/json' \
  -H "Circle-Token: <API_TOKEN>"

10. Using API v2

Endpoint Method Description Example
/api/v2/project/{project-slug}/pipeline POST Trigger a new pipeline 
{
  "branch": "main",
  "parameters": {
    "deploy": true
  }
}
/api/v2/pipeline/{pipeline-id}/config GET Get pipeline configuration 
{
  "name": "build",
  "steps": [
    "checkout",
    "run"
  ]
}
/api/v2/pipeline/{pipeline-id}/workflow GET List workflows in a pipeline 
[
  {
    "id": "wf-12345",
    "name": "build"
  }
]

Example: Triggering a Pipeline

curl -X POST "https://circleci.com/api/v2/project/github/owner/repo/pipeline" \
  -H "Accept: application/json" \
  -H "Circle-Token: <token>" \
  -d "{\"branch\":\"main\",\"parameters\":{\"deploy\":true}}"
Note: Replace <token> with your personal API token from CircleCI settings.
Warning: Ensure the project slug matches the repository structure exactly (e.g., github/owner/repo).

11. Handling Rate Limits

Rate Limit Type Limit Reset Time Notes
API Requests 1000 requests/hour Hourly Applies per user and organization
Concurrent Builds 50 concurrent builds Instant Applies per project and organization
Note: Exceeding rate limits results in 429 Too Many Requests responses.

Example: Retry Logic with Exponential Backoff

const retryRequest = async (requestFn, maxRetries = 3) => {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      const response = await requestFn();
      return response;
    } catch (error) {
      if (error.status === 429 && i < maxRetries) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Was this article helpful?

Related Cheat Sheets