Triggering CircleCI Builds on New Branches via API

Overview

When using CircleCI with restricted trigger settings (such as "PR opened or pushed to, default branch pushes, tag pushes"), you may encounter difficulties triggering builds via the API on newly created branches that haven't been associated with a Pull Request.

Users typically receive an error message stating that the branch was not found, even though the branch exists in the VCS (like GitHub).

Root Cause

This issue occurs because CircleCI needs to be aware of the branch before you can trigger a pipeline run against it via API. With restricted trigger settings, CircleCI doesn't automatically detect newly created branches until they are associated with a Pull Request or meet other trigger criteria.

Solution

There are two ways to resolve this issue:

Option 1: Use the Pipeline Run API Endpoint (Recommended)

Instead of using the standard Pipeline Trigger API endpoint, use the Pipeline Run API endpoint:

curl --request POST \
  --url https://circleci.com/api/v2/project/github/{org}/{repo}/pipeline/run \
  --header 'Circle-Token: YOUR_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"definition_id":"YOUR_DEFINITION_ID","config":{"branch":"YOUR_BRANCH"},"checkout":{"branch":"YOUR_BRANCH"}}''

The Pipeline Run endpoint can initiate builds on branches that CircleCI hasn't yet processed through webhooks, making it ideal for automation workflows that create branches programmatically.

Option 2: Adjust Your Trigger Settings

If Option 1 doesn't work for your workflow, you can modify your project's trigger settings to include one of the following:

• Enable "All branch pushes" (may increase build costs)
• Create a Pull Request for the branch (may complicate automation workflows)

Important Notes: 

• The Pipeline Run API is specifically designed for scenarios where you need to trigger builds on branches that CircleCI hasn't yet processed through webhooks.
• Using the standard Pipeline Trigger API (/pipeline) will continue to fail for branches that CircleCI hasn't recorded yet.
• This solution is particularly useful for CI/CD automation tools like Argo that programmatically create branches and need to trigger builds.

Related Documentation

• Trigger a Pipeline (Standard API)
• Trigger a Pipeline Run (Recommended for new branches)
• CircleCI Project Trigger Settings