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
  • Da Boss commented
    February 03, 2018 22:16

    Aye was goid

  • Florin Iacob commented
    April 17, 2018 12:51

    Triggering a complete workflow from the API is becoming imperaive for us, and we see ourselves forced to look into other CI solutions.

    Can you please share a schedule to when is this planned ?


  • Nathan Dintenfass commented
    May 01, 2018 03:02

    This is very much on our radar. I can’t give firm estimates yet, but this is on the list of important things before our August deadline when we sunset our 1.0 service. 

  • Martin Smith commented
    May 04, 2018 20:07

    It would be useful to be able to do these things while preventing users from doing it in the UI too, which might work around code review processes we're implementing as CircleCI workflows.

  • Carey Hoffman commented
    May 11, 2018 16:56

    Just hit this as well.  Seems a little crazy that this doesn't work.

  • Hans Sprecher commented
    June 04, 2018 21:45

    +1. Use this for complex projects in Circle CI 1.0. We're actively migrating to Circle CI 2.0. Thought we were late to the show, but this is a blocker for us.

  • Sergei Ryabkov commented
    June 07, 2018 13:15

    At the moment, even if it is not possible to trigger the entire workflow, it is possible to trigger a particular job that is referenced in the workflow. It is possible to re-implement the workflow (or implement a completely different one) by making the job call other jobs using the API. The mechanics are described in the documentation ( 

    However, when a job is triggered using the API, context environment variables are not available to the job, even if the job references the context in the workflow definition (which sounds like a bug, if not an implementation one than definitely a requirements/design/user experience one). As a workaround, it is possible to define environment variables on the project level, but that defeats the whole point of context environment variables. I'd like to flag this issue here to make sure that it gets addressed as part of the effort to enable triggering workflows using the API. 

  • Nathan Dintenfass commented
    June 07, 2018 16:14

    @Sergei Yes, this will be part of what gets addressed - you will be able to trigger the entire run of your config on a branch, including all workflows present. Contexts are resolved inside the workflow, and the job definition stands alone, so the old method isn't aware of the workflow. In the new triggering endpoint you will effectively be requesting to execute the entirety of the configuration on a given branch. 

  • Ken-ichi Tanabe commented
    June 20, 2018 10:19

    After I finished the migration from pipelines made by API calls to CircleCI 2.0 with lovely workflows and I found I cannot trigger a workflows via API. I'm feeling bad as I have to decide whether go back to v1 or reimplement a workflow with job API calls.

    It's very important and a major blocker now.

  • 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.

  • 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:

  • Nathan Dintenfass commented
    August 17, 2018 00:40

    This is now live:

  • 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 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 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 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.

  • 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
    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 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.

  • 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.

  • Ed Salter commented
    May 08, 2019 08:15

    Any updates on this? Thanks

  • 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.

  • 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:

  • 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.

  • 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.

  • 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:

  • 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? 

  • 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?

  • 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.