Trigger workflows via CircleCI REST API

Currently REST API can only invoke the build step and does not properly support triggering steps within a workflow, or kicking off a full workflow. We would like the ability to use the REST API to:

1. kick off a step within a workflow

2. kick off an entire workflow

  • Nan Liu
  • Jan 31 2018
  • Shipped
  • Oct 3, 2018

    Admin response

    This has been shipped. The documentation for triggering a workflow via the API is available here:

  • Attach files
  • Nathan Dintenfass commented
    November 07, 2019 19:26

    For reasons of backwards compatibility all workflows in a config run by default, so you will need to explicitly include/exclude those you want to run if you want to run only specific ones. This is known to be sub-optimal for cases where people want to configure many workflows and pick and choose which to run. If we see a lot of this kind of behavior we may add a way to switch the default behavior of running them all by default.

  • Jan Martin Langeland commented
    November 07, 2019 13:50

    I experienced a similar thing. When using the V2 pipeline API to trigger a workflow it kicked off all the workflows for that branch unless I specified  `when: << pipelines.parameters.condition >>` in the workflow I wanted to kick off and `unless: << pipelines.parameters.condition >>` in the workflows I don't want to start. Bug or expected behavior?

  • Makarand Patwradhan commented
    October 01, 2019 21:01
    Hey Nathan, I am trying to use this v2 api to kick off my workflow. I have a question - how do I specify a branch when using this API? 

    I tried to to POST to

    "branch": "my_branch"
    "parameters": {
    "run_release_steps": true,
    "run_stable_only": true

    But saw that it kicked off the build against master. Where do I specify the branch in this new API? 

  • Nathan Dintenfass commented
    September 03, 2019 19:34

    We are in preview for our v2 API that provides parameters when triggering pipelines. Rather than passing workflow name directly we have the ability to run workflows based on a boolean parameter (with more expressive conditionality coming later). To run a particular workflow you can thus set up a boolean parameter and pass that. Preview documentation for doing that can be found here:

  • Ilya commented
    September 03, 2019 14:20 has nothing about triggering WORKFLOWS and simply returns 404 on 


     More than that from its description it does not trigger arbitrary workflow, neither it can accept any parameters. So what's new? Can you please provide the doc that explains how to trigger ARBITRARY workflow by it's name with parameter. This was announced as implemented more than a year ago, still we are at the same place where we can't trigger any workflows with API.

  • Kenny Williams commented
    August 09, 2019 19:59

    Nathan, are there docs for the v2 conditional workflow endpoint? The regular API docs don't have any info on this new endpoint.

  • Nathan Dintenfass commented
    July 23, 2019 14:07

    We are currently previewing our v2 API that has a new feature to allow conditionally running particular workflows based on parameters passed when triggering your pipeline. See this preview doc for more information:

  • Gustavo Ambrozio commented
    July 22, 2019 18:58

    Seems like the link to the doc changes:


    Also, I don't see how to "kick off a step within a workflow" like it was suggested. This would be the most important thing for us.

  • Ed Salter commented
    May 08, 2019 08:15

    Any updates on this? Thanks

  • Joseph Becher commented
    February 15, 2019 16:11

    Wanted to provide an update here, since it feels like there is little movement. This is very close to the top of our priority list and we hope to have it soon. It turned out to involve more work than expected, but we understand the need and are making it a goal to get this to you folks as soon as we can.

  • Guest commented
    October 05, 2018 21:17

    Thanks for the link. Though "shipped" is misleading as this is a part of preview which has limitations and so is not something that can be considered as released. Using label "in preview" would be more correct.

  • Nathan Dintenfass commented
    October 03, 2018 18:04

    This got lost in the thread, but the documentation for triggering a build with workflows is here:

  • Guest commented
    October 03, 2018 09:33

    This is marked as "shipped" though I can't find any announcements or documentation on that. So is it now available or not?

  • Nathan Dintenfass commented
    August 20, 2018 00:36

    @Jóhann - make sure to vote on this Idea: -- we are looking at ways to allow you to filter based on files changed.

  • Jóhann Bergþórsson commented
    August 19, 2018 08:35


    We're operating in a monorepo and are looking into ways to run a subset of the total workflow based on what code got changed. Our code structure is slightly complex so we'll have a script that determines what jobs need to run.

    One idea would be to have a checked in config.yml that only looks at the code changes, then generates a new config.yml file and kicks of a workflow using that config.yml using the API.

    Another one would be to have a checked in config.yml that only looks at the code changes and then kicks off a workflow using the API with build_parameters which would allow us skip jobs that we don't want to run (using the 2.1 config). I think this is probably the way to go if I understand the docs (

    Any other approaches that you'd recommend? (maybe going off topic here, happy to move into email/DMs)

    I've yet to try the new API but does it work nicely with Github green/red lights? I.e. if I trigger a workflow from the API, will it post status updates to Github?

  • Nathan Dintenfass commented
    August 18, 2018 08:46

    We are looking into letting you pass config as part of the build trigger, though there are security implications we want to work out first. We will be adding some answer to build parameters in the coming weeks. Curious to hear more specifics about your needs on both fronts if you care to share.

  • Jóhann Bergþórsson commented
    August 18, 2018 07:16

    This sounds great.

    I remember having seen somewhere that you'd be able to kick of an workflow with a custom config file but now I can't find any documentation on that. Is that a deprecated feature? Will the workflow always run from the config.yml from the revision?

    Also: what's the ETA for supporting build_parameters?

  • Nathan Dintenfass commented
    August 17, 2018 00:40

    This is now live:

  • Nathan Dintenfass commented
    August 07, 2018 22:46

    We are now testing this capability in the wild -- it requires turning on build processing under the Advanced settings on your project's Settings page. It will be in docs soon, but given how eager folks are I put together a little gist to explain how it works:

  • Kelsey Steinbeck commented
    July 11, 2018 16:11

    Do we have a status on this? I've been waiting on this feature for about a yr now. I keep pushing back automation needs until this gets addressed. It would be nice to know when you think this will be available.

  • Load older comments