Trigger CircleCI Pipelines Programmatically via the API (2026)

You can trigger CircleCI pipelines programmatically via the API by sending a POST request to the appropriate endpoint with the necessary authentication and payload.

Let’s see it in action. Imagine you’ve got a Git repository on GitHub and you want to trigger a CircleCI build for a specific branch whenever a certain event happens in another system – maybe a new deployment to a staging environment or a user action in your internal dashboard.

Here’s a curl command that simulates this. We’ll assume you have your CircleCI API token ready.

curl --request POST \
  --url https://circleci.com/api/v2/project/github/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME/pipeline \
  --header "Circle-Token: YOUR_CIRCLECI_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "branch": "main",
    "parameters": {
      "deploy_env": "staging",
      "tag_version": "v1.2.3"
    }
  }'

In this example:

• YOUR_GITHUB_USERNAME and YOUR_REPO_NAME identify your project.
• YOUR_CIRCLECI_API_TOKEN is your secret key to authenticate with CircleCI. You can generate this in your CircleCI user settings.
• branch: "main" specifies which branch’s configuration to use for the pipeline.
• parameters is a JSON object where you can pass custom key-value pairs to your pipeline. These parameters can then be accessed within your .circleci/config.yml file.

The core problem this solves is enabling event-driven automation for your CI/CD workflows. Instead of relying solely on Git commits to kick off builds, you can integrate CircleCI into a broader ecosystem of tools and services. This allows for more sophisticated workflows, like triggering builds based on external events, manual approvals, or even data from other systems.

Internally, when CircleCI receives this API request, it performs a few key actions:

1. Authentication: It validates your Circle-Token.
2. Project Lookup: It finds the specified project based on your GitHub username and repository name.
3. Pipeline Creation: It initiates a new pipeline run.
4. Configuration Loading: It determines which CircleCI configuration (.circleci/config.yml) to use, typically based on the specified branch.
5. Parameter Injection: If parameters are provided, it makes these available to the jobs within the pipeline.

The exact levers you control are primarily the branch and the parameters. The branch dictates which version of your .circleci/config.yml is loaded, and the parameters allow you to dynamically influence the execution of your jobs without needing to commit new code. For instance, you could have a single deploy job that accepts a deploy_env parameter and deploys to different environments accordingly.

Here’s how you might use those parameters in your .circleci/config.yml:

version: 2.1

parameters:
  deploy_env:
    type: string
    default: "staging"
  tag_version:
    type: string
    default: "latest"

jobs:
  build_and_deploy:
    docker:
      - image: cimg/node:16.14.0
    steps:
      - checkout
      - run: echo "Deploying version << parameters.tag_version >> to << parameters.deploy_env >> environment."
      # ... deployment steps ...

When the pipeline is triggered with the parameters shown in the curl example, the run step would output: Deploying version v1.2.3 to staging environment.

The most surprising thing about triggering pipelines programmatically is how granularly you can control the execution context. Beyond just specifying a branch, the parameters object acts as a dynamic input for your entire pipeline. This means you can effectively create parameterized builds that adapt their behavior based on external triggers without modifying your codebase or CI configuration files themselves. It’s like having a function call for your CI/CD process where you can pass arguments.

The next concept you’ll likely run into is how to handle the response from the API call, specifically looking at the pipeline.id and pipeline.number to track the status of your triggered build.