@bmcgair I hear you - this is area we are prioritizing.
tldr: we have a 1.1 endpoint that triggers the workflow(s) in your config, though it has limitations some find onerous. We are also about to announce stability of our initial set of API v2 endpoints (currently in public preview), which include the ability to trigger pipelines with optional parameters you can use to drive specific workflows. The v2 API has preview docs up here: https://github.com/CircleCI-Public/api-preview-docs.
For those who want a more thorough explanation of the situation, strap in…:
In Sept 2018 we previewed the concept of “build processing” when we started to roll out orbs and the 2.1 config features. At that time we added an endpoint to the 1.1 API to trigger a build on a project:
In code it would look something like:
curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/build?circle-token=:token
That endpoint has been in production and documented since late 2018, and when you trigger work using it your workflow(s) will run. This is why we have said tbhat you can trigger workflows with the API. Admittedly, I see ways we could improve the description on that endpoint, and I’ll look into getting that done. However, in the next few weeks we’ll be encouraging people to move over to the new pipeline triggering endpoint in v2, so I strongly encourage anyone reading this in August 2019 to go try that first.
If you look through the preview docs to the v2 API you’ll see us referring increasingly to pipelines alongside workflows jobs. The v2 API will be the first major feature to reflect the new pipeline entity within the system. For those who have been playing close attention, you’ll notice we started talking about pipelines in March 2019 because use of the word “build” had become overloaded to mean both each job run inside your workflows and also used to describe the entire triggered run and its configuration. We found ourselves talking about builds inside of workflows inside of builds, so we formalized that you trigger pipelines that can contain one or more workflows that each orchestrate one or more jobs to be run on executors.
The new pipeline triggering mechanism in the v2 API is designed to address the two major shortcomings we’ve heard loud and clear from our developer community about the 1.1 endpoint for triggering jobs:
In the 1.1 build triggering endpoint the return result is useless – that endpoint is a “fire and forget” way to trigger work on CircleCI. It does not return any identifier with which to get back the resulting workflows or jobs. In v2, the pipeline triggering endpoint returns a pipeline ID you can use to get information about it, including access to its workflows.
In the 1.1 build triggering endpoint you can’t pass parameters – in our 1.1 API we have a way to POST to a project to trigger a job (aka a “build”), and that endpoint takes parameters that get injected into the job. In v2, we introduce pipeline parameters that are declared and used inside the configuration (note this is a change from how “build parameters” work in the 1.1 API). For more on how this work in v2 see https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/pipeline-parameters.md
For more on running conditional workflows using pipeline parameters see: https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/conditional-workflows.md.
For those who might wonder why the new pipeline triggering mechanism has more moving parts than the old job triggering endpoint, it’s because the old job triggering endpoint works only for individual jobs and cannot support any features of workflows or pipelines. An increasing number of projects are using those features, so we have been focusing on providing a reasonable API experience end-to-end. As of August 2019 we have well over half of all projects using pipelines, and that percent is climbing steadily). One of the underlying causes of some of the complexity in the v2 API is that the processing of pipelines happens in stages that are sometimes asynchronous. For instance, when you trigger a pipeline we immediately give you a pipeline ID, but the actual configuration processing happens after your trigger is received. And after the configuration processing your workflows are queued for execution. Once the workflows run the jobs are then created and dispatched to our execution systems. We run things with that kind of asynchrony to achieve reliability at the scale we’re now running. We’ll be eagerly listening to feedback on ways API v2 can be more expressive as we roll it out in the coming weeks.