Search Results for ""

Using the API to Trigger Jobs

This document describes how to trigger jobs using the CircleCI API.

Note: You cannot currently trigger jobs that use 2.1 config from the API.


Use the CircleCI API to trigger jobs that you have defined in .circleci/config.yml.

The following example shows how to trigger the deploy_docker job by using curl.

     -d build_parameters[CIRCLE_JOB]=deploy_docker \<vcs-type>/<org>/<repo>/tree/<branch>

Some notes on the variables used in this example:

  • CIRCLE_API_USER_TOKEN is a personal API token.
  • <vcs-type> is a placeholder variable and refers to your chosen VCS (either github or bitbucket).
  • <org> is a placeholder variable and refers to the name of your CircleCI organization.
  • <repo> is a placeholder variable and refers to the name of your repository.
  • <branch> is a placeholder variable and refers to the name of your branch.

For a complete reference of the API, see the CircleCI API Documentation.

Important Considerations When Triggering A Job Via The API

  • Jobs triggered with the API may contain a workflows section
  • Your workflow does not have to reference the job you triggered with the API
  • Jobs that are triggered via the API do not have access to environment variables created for a CircleCI Context
  • If you wish to use environment variables they have to be defined at the Project level
  • It is currently not possible to trigger a single job if you are using CircleCI 2.1 and Workflows
  • It is possible to trigger workflows with the CircleCI API, using the Trigger a Build by Project endpoint

Conditionally Running Jobs With the API

The next example demonstrates a configuration for building docker images with setup_remote_docker only for builds that should be deployed.

version: 2
      - image: ruby:2.4.0-jessie
          LANG: C.UTF-8
    working_directory: /my-project
    parallelism: 2
      - checkout

      - run: echo "run some tests"

      - deploy:
          name: conditionally run a deploy job
          command: |
            # replace this with your build/deploy check (i.e. current branch is "release")
            if [[ true ]]; then
              curl --user ${CIRCLE_API_USER_TOKEN}: \
                --data build_parameters[CIRCLE_JOB]=deploy_docker \
                --data revision=$CIRCLE_SHA1 \

      - image: ruby:2.4.0-jessie
    working_directory: /
      - setup_remote_docker
      - run: echo "deploy section running"

Notes on the above example:

  • Using the deploy step in the build job is important to prevent triggering N builds, where N is your parallelism value - deploy is a special step that will only run on one container, even when the job parallelism is set greater that one.
  • We use an API call with build_parameters[CIRCLE_JOB]=deploy_docker so that only the deploy_docker job will be run.

See Also