How to trigger a single job with version 2.1 config

Using CircleCI config 2.1, it's not possible to trigger a single job via API v1.1. One way to do it for now is to use a conditional workflow with the new API v2.

Instructions

Let's see the example below so that we're going to trigger only the deploy_to_dev job using the API.

# config.yml

version: 2.1
executors:
  node-executor:
    docker:
      - image: cimg/node:25.9.0

# Set parameter here
parameters:
  deploy_to_dev:
    type: boolean
    default: false

jobs:
  build:
    executor: node-executor
    steps:
      - checkout
      - unless:
          condition: << pipeline.parameters.deploy_to_dev >> # by default this is triggered
          steps:
            - run: # build
  deploy_to_dev:
    executor: node-executor
    steps:
      - checkout
      - when:
         condition: << pipeline.parameters.deploy_to_dev >> # this would be triggered when you pass the parameter value via API
         steps:
           - run: # deploy steps
                  # do deploy to dev

workflows:
  build-deploy:
    jobs:
      - build
      - deploy_to_dev

In this case, by default pipeline.parameters.deploy_to_dev is false since we set the parameter to false by default. So when you trigger the pipeline,  deploy_to_dev won't be triggered. However, triggering it with API 2 makes a magic.

curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
 "parameters": {
   "deploy_to_dev": true
 }
}' https://circleci.com/api/v2/project/${project_slug}/pipeline

Outcome

With the parameter set on body, CircleCI knows that it's time to trigger deploy_to_dev and that would be the only job triggered.

Additional Resources

• https://circleci.com/docs/reference/configuration-reference/#example-1
• https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/conditional-workflows.md
• https://circleci.com/docs/api/v2/#trigger-a-new-pipeline