Ensure the target workflow file declares 'on: workflow_dispatch:' and optionally defines 'inputs:' with names, types, and defaults
Send POST to 'https://api.github.com/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches' with header 'Authorization: Bearer YOUR_TOKEN' and 'Accept: application/vnd.github+json'
Include a JSON body with 'ref' (branch or tag to run on) and an optional 'inputs' object matching the declared input names
The API returns HTTP 204 on success with no body; poll GET '/repos/{owner}/{repo}/actions/runs' filtering by 'event=workflow_dispatch' and 'branch' to find the created run
Use the run's 'id' to stream logs or wait for completion via GET '/repos/{owner}/{repo}/actions/runs/{run_id}' polling 'status' and 'conclusion'
Known gotchas
workflow_dispatch requires the workflow file to exist on the specified 'ref' branch at the time of the call; dispatching to a ref that lacks the workflow returns a 422 error
Input values are always strings regardless of the declared type; the workflow must coerce booleans or numbers if needed
Rate limits on Actions API endpoints apply; frequent polling of run status should include exponential backoff to avoid secondary rate limit errors
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