Generate a CircleCI personal API token or project API token from the CircleCI UI under User Settings or Project Settings
POST to 'https://circleci.com/api/v2/project/{project-slug}/pipeline' with header 'Circle-Token: YOUR_TOKEN' and Content-Type 'application/json'
Include a JSON body with 'branch' or 'tag' to specify the ref, and 'parameters' as an object of key-value pairs matching pipeline parameters declared in your '.circleci/config.yml'
Declare pipeline parameters at the top of config.yml under 'parameters:' with type and default; jobs conditionally run using 'when:' expressions referencing these parameters
The response contains a 'id' for the pipeline; poll GET '/api/v2/pipeline/{pipeline-id}/workflow' to retrieve workflow IDs and then GET '/api/v2/workflow/{workflow-id}' for status
Known gotchas
Pipeline parameters must be declared in config.yml before they can be passed via API; passing undeclared parameters causes the pipeline to fail with a configuration error
Parameter types are strictly enforced: passing a string where an integer is declared, or vice versa, causes a 400 error
The v2 API uses a 'project-slug' format of 'gh/owner/repo' or 'bb/owner/repo' depending on VCS; using the wrong prefix results in a 404
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp