# Create a workflow dispatch event

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`

You can use this endpoint to manually trigger a GitHub Actions workflow run. You can replace `workflow_id` with the workflow file name. For example, you could use `main.yaml`.

You must configure your GitHub Actions workflow to run when the [`workflow_dispatch` webhook](/developers/webhooks-and-events/webhook-events-and-payloads#workflow_dispatch) event occurs. The `inputs` are configured in the workflow file. For more information about how to configure the `workflow_dispatch` event in the workflow file, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#workflow_dispatch)."

You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint. For more information, see "[Creating a personal access token for the command line](https://docs.github.com/articles/creating-a-personal-access-token-for-the-command-line)."

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `workflow_id`

- Location: path
- Required: true
The ID of the workflow. You can also pass the workflow file name as a string.

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "inputs": {
    "home": "San Francisco, CA",
    "name": "Mona the Octocat"
  },
  "ref": "topic-branch"
}
```

```json
{"properties":{"inputs":{"additionalProperties":{"type":"string"},"description":"Input keys and values configured in the workflow file. The maximum number of properties is 10. Any default properties configured in the workflow file will be used when `inputs` are omitted.","maxProperties":10,"type":"object"},"ref":{"description":"The git reference for the workflow. The reference can be a branch or tag name.","type":"string"}},"required":["ref"],"type":"object"}
```

## Responses

### `204`

Response

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches \
  --header 'content-type: application/json' \
  --data '{
  "inputs": {
    "home": "San Francisco, CA",
    "name": "Mona the Octocat"
  },
  "ref": "topic-branch"
}'
```