Run a workflow

Run a workflow that has on: workflow_dispatch, on a branch or tag (the default branch if none), with its inputs.

POST/repos/{owner}/{name}/actions/workflows/{workflow}/dispatches

Needs the Write role or higher.

Authentication: Required. Send an access token as Authorization: Bearer.
MCP tool: workflow with action dispatch, and the same inputs
Scope: An access token needs workflows:write.

Path parameters

Name	Type	Required	Description
`owner`	string	Yes	The workspace that owns the repository.
`name`	string	Yes	The repository’s name.
`workflow`	string	Yes	The workflow’s id or file name.

Body parameters

Send a JSON object. Names are snake_case, as in responses; the camelCase spelling is accepted too.

Name	Type	Required	Description
`ref`	string	No	A branch or tag. The default branch if not given.
`inputs`	object	No	The workflow_dispatch inputs, by name.

Example request

curl -X POST https://api.g1t.sh/repos/flagon-io/hello/actions/workflows/ci.yml/dispatches \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "inputs": {
      "debug": true
    }
  }'

Example response

A successful request answers 200 with:

{
  "id": "run_01kpx8d4e7f0g3h6j9k2m5n8pq",
  "workflow_id": "wfl_01kpw2c5d8e1f4g7h0j3k6m9np",
  "path": ".g1t/workflows/ci.yml",
  "name": "CI",
  "title": "CI run by syntaqx",
  "number": 13,
  "attempt": 1,
  "event": "workflow_dispatch",
  "ref": "refs/heads/main",
  "sha": "9f2c4e1a7b3d5f60812a4c6e8b0d2f4a6c8e0b13",
  "pull": null,
  "status": "queued",
  "conclusion": null,
  "error": null,
  "actor": "syntaqx",
  "created_at": "2026-10-04T16:30:00.512Z",
  "started_at": null,
  "finished_at": null
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	`unauthenticated`	A token is required, or the one sent is not valid.
403	`forbidden`	The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository.
404	`not_found`	It does not exist, or you cannot see it.
409	`conflict`	The request conflicts with the current state.
422	`invalid`	The input is not valid. `message` says which field and why.