---
title: "DispatchWorkflow"
method: POST
path: "/depot.ci.v1.CIService/DispatchWorkflow"
tags: ["CIService"]
---

# DispatchWorkflow

`POST /depot.ci.v1.CIService/DispatchWorkflow`

## Request

- Base URL: `https://api.depot.dev`
- URL: `https://api.depot.dev/depot.ci.v1.CIService/DispatchWorkflow`
- Auth: HTTP bearer

Triggers a single workflow configured with an `on.workflow_dispatch` trigger and validates inputs against its input schema.

## Headers

- `Connect-Protocol-Version` 1, required: Define the version of the Connect protocol
- `Connect-Timeout-Ms` number: Define the timeout, in ms

## Request body

- DepotCiV1DispatchWorkflowRequest
  - `repo` string, required: GitHub repository to run workflows from, in `owner/name` format. For example, "depot/cli". Must be connected to your Depot organization through the Depot GitHub app.
  - `workflow` string, required: Path of the workflow file to run, relative to the repo root. For example, ".depot/workflows/deploy.yml". The workflow must be configured with an `on.workflow_dispatch` trigger. Required.
  - `ref` string: Branch or tag to run the workflow on. An unqualified name like "main" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0". Leave empty to use the repository's default branch. Default: HEAD of the default branch.
  - `inputs` object: Inputs to pass to the workflow, as key-value pairs. All values are strings. The server validates each value against the workflow's `workflow_dispatch` input schema. Boolean inputs must be the string "true" or "false", number inputs must be numeric, and choice inputs must match one of the defined options. Unknown inputs are rejected. A required input must be supplied only if it has no default; one that has a default may be omitted.

## Response `200`

Success

- DepotCiV1DispatchWorkflowResponse
  - `orgId` string: Depot organization that owns this run.
  - `runId` string: Unique identifier for the created CI run. Use it for methods like `GetRun`, `GetRunStatus`, `CancelRun`, and `ListArtifacts` to track, cancel, or fetch results from the run.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/depot/apis/depot-ci-api.md) - [All operations](https://skmtc.dev/depot/apis/depot-ci-api/llms.txt) - [OpenAPI document](https://skmtc.dev/depot/apis/depot-ci-api/revisions/6cf759b535b4?raw)