Depot API

Depot CI API reference

RPC-first reference for the Depot CI Connect API. Every method is generated from the OpenAPI artifact and grouped by CI resource. The Depot CI API exposes a four-level resource hierarchy.

  • Run: Top-level execution unit triggered by an event or workflow dispatch. Contains one or more workflows.
  • Workflow: Corresponds to a single workflow YAML file. Contains one or more jobs.
  • Job: Corresponds to one entry in the workflow YAML. Has one or more attempts.
  • Attempt: One dispatch of a job. Retries create new attempts.

Logs, metrics, artifacts, and failure diagnoses are scoped to attempts but reachable from the parent run, workflow, or job.

Secret and variable management methods use the depot.ci.v3beta2 package. This API surface is in beta and may change.

RPC basics
Base URL
https://api.depot.dev
Protocol
Connect RPC over HTTP
Encoding
JSON or Connect JSON
OpenAPI spec
SourceView JSON
API version
v1
OAS
3.1.0

Method index

The Depot CI API provides the following methods, grouped by resource.

RunCIService.Run

Triggers a CI run. Runs can contain one or more workflows.

Parameters

repostringrequired

Repository to run workflows from. GitHub, Origin, and Entire repositories use owner/name format. For example, "depot/cli". For Entire, use the owner/name in the repository's clone URL. Depot Code repositories use the repository name. For example, "widgets".

shastring | null

Commit SHA to run against. Use a specific commit to run a particular version of your workflow files (and have that SHA appear in github.sha), or omit to run the latest commit on the default branch. Must be a full 40-character hex SHA. Default: HEAD of the default branch.

workflowstring | null

Path of the workflow file to run, relative to the repo root. For example, ".depot/workflows/ci.yml". Mutually exclusive with workflowContent; if neither is provided, runs all workflows in the repo.

workflowContentstring[]

An array of workflow YAMLs to run. Depot reads the YAML from the request instead of the repo. Each entry must be the complete content of a workflow (as found in .depot/workflows/). Useful for testing workflow YAML changes without committing them. Mutually exclusive with workflow; if neither is provided, runs all workflows in the repo.

jobstring | null

Job key of a single job to run from within a workflow. For example, "build" or "test". When specified, the run skips all other jobs in the workflow. Valid only when a single workflow is specified, either through workflow or a workflowContent entry containing one workflow.

forgeForge

Source-code host containing the repository. Depot Code is supported only for repositories that do not mirror a GitHub repository. Entire requires the Depot plugin installed on the repository's project. Default: FORGE_GITHUB.

Possible enum values
FORGE_UNSPECIFIEDFORGE_GITHUBFORGE_ORIGINFORGE_DEPOT_CODEFORGE_ENTIRE
refstring | null

Branch or tag the sha was checked out from, used to attribute test results. For example, "refs/heads/feature". An unqualified name like "feature" is treated as a branch. To use a tag, pass the fully-qualified ref "refs/tags/v1.0". It does not change what is checked out. Only valid when sha is set.

Returns

orgIdstring

Depot organization that owns this run.

runIdstring

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.

POST/depot.ci.v1.CIService/Run
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/Run \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "repo": "repo_example",8  "sha": "b2f5ff47436671b6e533d8dc3614845d",9  "workflow": "workflow_example",10  "workflowContent": [11    "workflowContent_example"12  ],13  "job": "job_example",14  "forge": "FORGE_UNSPECIFIED",15  "ref": "ref_example"16}17JSON
Response
{  "orgId": "org_123",  "runId": "run_123"}

ListRunsCIService.ListRuns

Returns CI runs for the authenticated organization, newest first. Filter by status, repository, commit SHA, trigger, or pull request number. Use pageSize and pageToken to page through additional results.

Parameters

statusstring[]

Statuses of runs to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: ["running", "queued"].

pageSizeinteger<int32>

Number of runs to return per page. Maximum: 100. Default: 50.

pageTokenstring

Token to fetch the next page of runs. Use the nextPageToken value from a prior response. Leave empty to fetch the first page.

repostring

Repository to return runs from, in owner/name format. For example, "depot/cli". Required if pr is set.

shastring

Commit SHA prefix to return runs for. Matched against the run's sha or headSha. 1-40 hex characters.

triggerstring

Trigger event to return runs for. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

prstring

Pull request number to return runs for. Requires repo.

Returns

runsListRunsResponseRun[]

Recent runs matching the request, newest first.

+Show child parameters
runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format. For example, "depot/cli".

triggerstring

Event that triggered the run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

shastring

Commit SHA the run executes against. Empty for open pull_request runs.

statusstring

Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Run creation time, in RFC 3339 format.

refstring

Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.

headShastring

Source commit SHA for pull_request and merge_group triggers. Empty for triggers that don't carry a head SHA.

nextPageTokenstring

Token to retrieve the next page of results. Empty when no more pages are available.

POST/depot.ci.v1.CIService/ListRuns
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListRuns \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "status": [8    "status_example"9  ],10  "pageSize": 1,11  "pageToken": "pageToken_example",12  "repo": "repo_example",13  "sha": "b2f5ff47436671b6e533d8dc3614845d",14  "trigger": "trigger_example",15  "pr": "pr_example"16}17JSON
Response
{  "runs": [    {      "runId": "run_123",      "repo": "repo_example",      "trigger": "trigger_example",      "sha": "b2f5ff47436671b6e533d8dc3614845d",      "status": "status_example",      "createdAt": "createdAt_example"    }  ],  "nextPageToken": "nextPageToken_example"}

GetRunCIService.GetRun

Returns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use GetRunStatus.

Parameters

runIdstringrequired

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

orgIdstring

Depot organization that owns this run.

runIdstring

Unique identifier for the CI run.

repostring

GitHub repository in owner/name format. For example, "depot/cli".

refstring

Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref.

shastring

Commit SHA the run executes against. Empty for open pull_request runs; populated with the merge commit SHA once the PR is closed and merged.

headShastring

Source commit SHA for pull_request and merge_group triggers; matches the PR or merge group head. Empty for triggers that don't carry a head SHA.

triggerstring

Event that triggered the run. For example, "push", "pull_request", "pull_request_target", "issue_comment", "merge_group", "schedule", "workflow_run", or "workflow_dispatch".

statusstring

Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".

createdAtstring

Creation time, in RFC 3339 format.

startedAtstring

Start time, in RFC 3339 format. Empty until the run starts.

finishedAtstring

Finish time, in RFC 3339 format. Empty until the run finishes.

POST/depot.ci.v1.CIService/GetRun
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRun \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON
Response
{  "orgId": "org_123",  "runId": "run_123",  "repo": "repo_example",  "ref": "ref_example",  "sha": "b2f5ff47436671b6e533d8dc3614845d",  "headSha": "b2f5ff47436671b6e533d8dc3614845d",  "trigger": "trigger_example",  "status": "status_example"}

GetRunStatusCIService.GetRunStatus

Returns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use GetRun.

Parameters

runIdstringrequired

Unique identifier for the CI run. Returned by Run, DispatchWorkflow, and ListRuns.

Returns

orgIdstring

Depot organization that owns this run.

runIdstring

Unique identifier for the CI run.

statusstring

Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled".

workflowsWorkflowStatus[]

Workflows in the run with their nested jobs and attempts.

+Show child parameters
workflowIdstring

Unique identifier for the workflow.

statusstring

Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled".

workflowPathstring

Workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via workflowContent in the Run request.

jobsJobStatus[]

Jobs that make up the workflow.

+Show child parameters
jobIdstring

Unique identifier for the job.

jobKeystring

Job key from the workflow. For example, "build" or "test".

statusstring

Current state of the job. Can be "queued", "waiting", "running", "finished", "failed", "cancelled", or "skipped". "waiting" means the job is blocked behind another run that holds the same concurrency: group slot.

attemptsAttemptStatus[]

All attempts for this job, including the original and any retries. Each contains the attempt's identifier, number, current status, and sandbox/session IDs (when active). Order is not guaranteed.

jobDisplayNamestring

Resolved job name for display. Falls back to the leaf job name, then jobKey, when unavailable. Use jobId or jobKey to identify the job.

namestring

Workflow name from the YAML name: key. Empty when not set.

errorMessagestring

Workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy.

POST/depot.ci.v1.CIService/GetRunStatus
1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunStatus \2  -H "Authorization: Bearer $DEPOT_TOKEN" \3  -H "Content-Type: application/json" \4  -H "Connect-Protocol-Version: 1" \5  --json @- <<'JSON'6{7  "runId": "run_123"8}9JSON
Response
{  "orgId": "org_123",  "runId": "run_123",  "status": "status_example",  "workflows": [    {      "workflowId": "workflow_123",      "status": "status_example",      "workflowPath": "workflowPath_example",      "jobs": [        {          "jobId": "job_123",          "jobKey": "jobKey_example",          "status": "status_example",          "attempts": [