Search Results for ""

Using the API to Trigger Jobs

This document describes how to trigger jobs using the CircleCI 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