Cookies We use cookies to understand how people use Depot. [Learn more](/content/cookies/index.html) RejectAccept 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` Auth [Bearer token](/content/docs/api/authentication/index.html) Encoding `JSON or Connect JSON` Errors [Connect status codes](/content/docs/api/ci/reference#errors/index.html) OpenAPI spec [SourceView JSON](/content/openapi/depot-ci/v1.json) API version v1 OAS 3.1.0 ## Method index The Depot CI API provides the following methods, grouped by resource. [Runs6](/content/docs/api/ci/reference#runs/index.html) [RunTriggers a CI run. Runs can contain one or more workflows.](/content/docs/api/ci/reference#ci-service-run/index.html) [ListRunsReturns 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.](/content/docs/api/ci/reference#ci-service-list-runs/index.html) [GetRunReturns a CI run's identity, repo, trigger, status, and timestamps. For nested workflow, job, and attempt status, use \`GetRunStatus\`.](/content/docs/api/ci/reference#ci-service-get-run/index.html) [GetRunStatusReturns a CI run's status with its nested workflows, jobs, and attempts. For the run's identity, repo, trigger, and timestamps, use \`GetRun\`.](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) [GetRunMetricsReturns workflow, job, and attempt CPU and memory metric summaries for one run.](/content/docs/api/ci/reference#ci-service-get-run-metrics/index.html) [CancelRunCancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts.](/content/docs/api/ci/reference#ci-service-cancel-run/index.html) [Workflows5](/content/docs/api/ci/reference#workflows/index.html) [ListWorkflowsReturns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use \`pageSize\` to return up to 200 workflows.](/content/docs/api/ci/reference#ci-service-list-workflows/index.html) [GetWorkflowReturns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts.](/content/docs/api/ci/reference#ci-service-get-workflow/index.html) [DispatchWorkflowTriggers a single workflow configured with an \`on.workflow\_dispatch\` trigger and validates inputs against its input schema.](/content/docs/api/ci/reference#ci-service-dispatch-workflow/index.html) [RerunWorkflowResets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running.](/content/docs/api/ci/reference#ci-service-rerun-workflow/index.html) [CancelWorkflowCancels a queued or running workflow and all its child jobs.](/content/docs/api/ci/reference#ci-service-cancel-workflow/index.html) [Jobs7](/content/docs/api/ci/reference#jobs/index.html) [GetJobReturns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history.](/content/docs/api/ci/reference#ci-service-get-job/index.html) [SubmitJobInputSubmit an answer to a running input job.](/content/docs/api/ci/reference#ci-service-submit-job-input/index.html) [GetJobSummaryReturns authored step summary markdown for a job, a specific attempt, or both.](/content/docs/api/ci/reference#ci-service-get-job-summary/index.html) [GetJobMetricsReturns per-attempt CPU and memory metric summaries for one job.](/content/docs/api/ci/reference#ci-service-get-job-metrics/index.html) [RetryJobRetries a failed or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use \`RetryFailedJobs\` to retry related failures together.](/content/docs/api/ci/reference#ci-service-retry-job/index.html) [RetryFailedJobsRetries the failed and cancelled jobs in a workflow, along with every job that depends on them. A dependent that already succeeded or was skipped runs again too, because a job it consumed is running again. Queued dependents are left untouched, since they re-check their dependencies before starting. Fails without resetting anything when a waiting or running job depends on the retried set; wait for that job to finish, or cancel the workflow and use \`RerunWorkflow\`.](/content/docs/api/ci/reference#ci-service-retry-failed-jobs/index.html) [CancelJobCancels a queued, waiting, or running job and its active attempt.](/content/docs/api/ci/reference#ci-service-cancel-job/index.html) [Attempts2](/content/docs/api/ci/reference#attempts/index.html) [GetAttemptReturns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context.](/content/docs/api/ci/reference#ci-service-get-attempt/index.html) [GetJobAttemptMetricsReturns CPU and memory metrics for one job attempt.](/content/docs/api/ci/reference#ci-service-get-job-attempt-metrics/index.html) [Logs3](/content/docs/api/ci/reference#logs/index.html) [GetJobAttemptLogsReturns persisted log lines for a job attempt, oldest first. Identify the attempt by \`attemptId\`, or by \`jobId\` to use the job's latest attempt. Poll with \`pageToken\` to fetch lines persisted after a previous response.](/content/docs/api/ci/reference#ci-service-get-job-attempt-logs/index.html) [StreamJobAttemptLogsFollows a job attempt's persisted log lines, streaming new lines while the attempt runs.stream](/content/docs/api/ci/reference#ci-service-stream-job-attempt-logs/index.html) [ExportJobAttemptLogsExports a finite snapshot of persisted log lines.stream](/content/docs/api/ci/reference#ci-service-export-job-attempt-logs/index.html) [Artifacts2](/content/docs/api/ci/reference#artifacts/index.html) [ListArtifactsReturns CI artifact metadata for one run, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with \`GetArtifactDownloadURL\`.](/content/docs/api/ci/reference#ci-service-list-artifacts/index.html) [GetArtifactDownloadURLReturns a short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance.](/content/docs/api/ci/reference#ci-service-get-artifact-download-url/index.html) [Secrets10](/content/docs/api/ci/reference#secrets/index.html) [ListSecrets](/content/docs/api/ci/reference#secret-service-list-secrets/index.html) [ListSecretAttributes](/content/docs/api/ci/reference#secret-service-list-secret-attributes/index.html) [GetSecret](/content/docs/api/ci/reference#secret-service-get-secret/index.html) [GetSecretVariant](/content/docs/api/ci/reference#secret-service-get-secret-variant/index.html) [CreateSecretVariant](/content/docs/api/ci/reference#secret-service-create-secret-variant/index.html) [SetSecretVariant](/content/docs/api/ci/reference#secret-service-set-secret-variant/index.html) [UpdateSecretVariantMetadata](/content/docs/api/ci/reference#secret-service-update-secret-variant-metadata/index.html) [UpdateSecretVariantValue](/content/docs/api/ci/reference#secret-service-update-secret-variant-value/index.html) [DeleteSecretVariant](/content/docs/api/ci/reference#secret-service-delete-secret-variant/index.html) [DeleteSecret](/content/docs/api/ci/reference#secret-service-delete-secret/index.html) [Variables10](/content/docs/api/ci/reference#variables/index.html) [ListVariables](/content/docs/api/ci/reference#variable-service-list-variables/index.html) [ListVariableAttributes](/content/docs/api/ci/reference#variable-service-list-variable-attributes/index.html) [GetVariable](/content/docs/api/ci/reference#variable-service-get-variable/index.html) [GetVariableVariant](/content/docs/api/ci/reference#variable-service-get-variable-variant/index.html) [CreateVariableVariant](/content/docs/api/ci/reference#variable-service-create-variable-variant/index.html) [SetVariableVariant](/content/docs/api/ci/reference#variable-service-set-variable-variant/index.html) [UpdateVariableVariantMetadata](/content/docs/api/ci/reference#variable-service-update-variable-variant-metadata/index.html) [UpdateVariableVariantValue](/content/docs/api/ci/reference#variable-service-update-variable-variant-value/index.html) [DeleteVariableVariant](/content/docs/api/ci/reference#variable-service-delete-variable-variant/index.html) [DeleteVariable](/content/docs/api/ci/reference#variable-service-delete-variable/index.html) [Diagnostics1](/content/docs/api/ci/reference#diagnostics/index.html) [GetFailureDiagnosisReturns a failure diagnosis for a run, workflow, job, or attempt.](/content/docs/api/ci/reference#ci-service-get-failure-diagnosis/index.html) ## Runs Create, inspect, measure, and cancel CI runs. [RunPOST/depot.ci.v1.CIService/Run](/content/docs/api/ci/reference#ci-service-run/index.html) [ListRunsPOST/depot.ci.v1.CIService/ListRuns](/content/docs/api/ci/reference#ci-service-list-runs/index.html) [GetRunPOST/depot.ci.v1.CIService/GetRun](/content/docs/api/ci/reference#ci-service-get-run/index.html) [GetRunStatusPOST/depot.ci.v1.CIService/GetRunStatus](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) [GetRunMetricsPOST/depot.ci.v1.CIService/GetRunMetrics](/content/docs/api/ci/reference#ci-service-get-run-metrics/index.html) [CancelRunPOST/depot.ci.v1.CIService/CancelRun](/content/docs/api/ci/reference#ci-service-cancel-run/index.html) ### RunCIService.Run Triggers a CI run. Runs can contain one or more workflows. ### Parameters `repo`stringrequired 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". `sha`string \| 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. `workflow`string \| 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. `workflowContent`string\[\] 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. `job`string \| 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. `forge`Forge 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_UNSPECIFIED``FORGE_GITHUB``FORGE_ORIGIN``FORGE_DEPOT_CODE``FORGE_ENTIRE` `ref`string \| 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 `orgId`string Depot organization that owns this run. `runId`string Unique identifier for the created CI run. Use it for methods like [`GetRun`](/content/docs/api/ci/reference#ci-service-get-run/index.html), [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html), [`CancelRun`](/content/docs/api/ci/reference#ci-service-cancel-run/index.html), and [`ListArtifacts`](/content/docs/api/ci/reference#ci-service-list-artifacts/index.html) to track, cancel, or fetch results from the run. POST`/depot.ci.v1.CIService/Run` cURLNode.jsGo ``` 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 `status`string\[\] Statuses of runs to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. Default: \["running", "queued"\]. `pageSize`integer Number of runs to return per page. Maximum: 100. Default: 50. `pageToken`string Token to fetch the next page of runs. Use the `nextPageToken` value from a prior response. Leave empty to fetch the first page. `repo`string Repository to return runs from, in `owner/name` format. For example, "depot/cli". Required if `pr` is set. `sha`string Commit SHA prefix to return runs for. Matched against the run's `sha` or `headSha`. 1-40 hex characters. `trigger`string Trigger event to return runs for. For example, "push", "pull\_request", "pull\_request\_target", "issue\_comment", "merge\_group", "schedule", "workflow\_run", or "workflow\_dispatch". `pr`string Pull request number to return runs for. Requires `repo`. ### Returns `runs`ListRunsResponseRun\[\] Recent runs matching the request, newest first. +Show child parameters `runId`string Unique identifier for the CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `trigger`string Event that triggered the run. For example, "push", "pull\_request", "pull\_request\_target", "issue\_comment", "merge\_group", "schedule", "workflow\_run", or "workflow\_dispatch". `sha`string Commit SHA the run executes against. Empty for open pull\_request runs. `status`string Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Run creation time, in RFC 3339 format. `ref`string Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `nextPageToken`string Token to retrieve the next page of results. Empty when no more pages are available. POST`/depot.ci.v1.CIService/ListRuns` cURLNode.jsGo ``` 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`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html). ### Parameters `runId`stringrequired Unique identifier for the CI run. Returned by [`Run`](/content/docs/api/ci/reference#ci-service-run/index.html), [`DispatchWorkflow`](/content/docs/api/ci/reference#ci-service-dispatch-workflow/index.html), and [`ListRuns`](/content/docs/api/ci/reference#ci-service-list-runs/index.html). ### Returns `orgId`string Depot organization that owns this run. `runId`string Unique identifier for the CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the run was triggered against. For example, "refs/heads/main" or "refs/pull/42/merge". Empty when the trigger carries no ref. `sha`string 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. `headSha`string 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. `trigger`string `status`string Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Creation time, in RFC 3339 format. `startedAt`string Start time, in RFC 3339 format. Empty until the run starts. `finishedAt`string Finish time, in RFC 3339 format. Empty until the run finishes. POST`/depot.ci.v1.CIService/GetRun` cURLNode.jsGo ``` 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`](/content/docs/api/ci/reference#ci-service-get-run/index.html). ### Parameters `runId`stringrequired ### Returns `orgId`string Depot organization that owns this run. `runId`string Unique identifier for the CI run. `status`string Current state of the run. Can be "queued", "running", "finished", "failed", or "cancelled". `workflows`WorkflowStatus\[\] Workflows in the run with their nested jobs and attempts. +Show child parameters `workflowId`string Unique identifier for the workflow. `status`string Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled". `workflowPath`string Workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via `workflowContent` in the [`Run`](/content/docs/api/ci/reference#ci-service-run/index.html) request. `jobs`JobStatus\[\] Jobs that make up the workflow. +Show child parameters `jobId`string Unique identifier for the job. `jobKey`string Job key from the workflow. For example, "build" or "test". `status`string 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. `attempts`AttemptStatus\[\] 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. `jobDisplayName`string Resolved job name for display. Falls back to the leaf job name, then `jobKey`, when unavailable. Use `jobId` or `jobKey` to identify the job. `name`string Workflow name from the YAML `name:` key. Empty when not set. `errorMessage`string Workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy. POST`/depot.ci.v1.CIService/GetRunStatus` cURLNode.jsGo ``` 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": [ "attempts_example" ], "jobDisplayName": "jobDisplayName_example" } ], "name": "name_example", "errorMessage": "errorMessage_example" } ]} ``` ### GetRunMetricsCIService.GetRunMetrics Returns workflow, job, and attempt CPU and memory metric summaries for one run. ### Parameters `runId`stringrequired ### Returns `run`CIMetricsRunContext Run context: identifiers, trigger, status, and lifecycle timestamps. +Show child parameters `runId`string Unique identifier for the CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the run executes against. Empty for open pull\_request runs. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `status`string Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Run creation time, in RFC 3339 format. `startedAt`string Run start time, in RFC 3339 format. Empty until the run starts. `finishedAt`string Run finish time, in RFC 3339 format. Empty until the run finishes. `workflows`CIMetricsWorkflowMetrics\[\] Per-workflow rollups containing each workflow's jobs and per-attempt metric summaries. +Show child parameters `workflow`CIMetricsWorkflowContext Workflow context: identifiers, status, and lifecycle timestamps. +Show child parameters `workflowId`string Unique identifier for the workflow. `workflowPath`string Workflow file path, for example ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via `workflowContent` in the [`Run`](/content/docs/api/ci/reference#ci-service-run/index.html) request. `name`string Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `status`string Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Workflow creation time, in RFC 3339 format. `startedAt`string Workflow start time, in RFC 3339 format. Empty until the workflow starts. `finishedAt`string Workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `jobs`CIMetricsJobMetrics\[\] Jobs in the workflow and their per-attempt metric summaries. +Show child parameters `job`CIMetricsJobContext Job context: identifiers, status, conclusion, and lifecycle timestamps. `attempts`CIMetricsAttemptSummary\[\] Per-attempt metric summaries for this job, ordered by attempt number ascending. `snapshotAt`string Server time at which this metrics snapshot was captured, in RFC 3339 format. For attempts that haven't finished yet, CPU and memory data is collected up to this time, so a running attempt's metrics grow on successive calls. POST`/depot.ci.v1.CIService/GetRunMetrics` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetRunMetrics \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 ``` { "run": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "workflows": [ { "workflow": { "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "name": "name_example", "status": "status_example", "createdAt": "createdAt_example", "startedAt": "startedAt_example" }, "jobs": [ { "job": "job_example", "attempts": [ "attempts_example" ] } ] } ], "snapshotAt": "snapshotAt_example"} ``` ### CancelRunCIService.CancelRun Cancels a queued or running CI run and any of its unfinished workflows, jobs, and attempts. ### Parameters `runId`stringrequired ### Returns `runId`string Unique identifier for the CI run. Matches the request `runId`. `status`string Updated run status. Should be "cancelled". POST`/depot.ci.v1.CIService/CancelRun` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelRun \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 ``` { "runId": "run_123", "status": "status_example"} ``` ## Workflows List, inspect, dispatch, rerun, and cancel CI workflows. [ListWorkflowsPOST/depot.ci.v1.CIService/ListWorkflows](/content/docs/api/ci/reference#ci-service-list-workflows/index.html) [GetWorkflowPOST/depot.ci.v1.CIService/GetWorkflow](/content/docs/api/ci/reference#ci-service-get-workflow/index.html) [DispatchWorkflowPOST/depot.ci.v1.CIService/DispatchWorkflow](/content/docs/api/ci/reference#ci-service-dispatch-workflow/index.html) [RerunWorkflowPOST/depot.ci.v1.CIService/RerunWorkflow](/content/docs/api/ci/reference#ci-service-rerun-workflow/index.html) [CancelWorkflowPOST/depot.ci.v1.CIService/CancelWorkflow](/content/docs/api/ci/reference#ci-service-cancel-workflow/index.html) ### ListWorkflowsCIService.ListWorkflows Returns CI workflows for the authenticated organization, newest first. Filter by name, repository, status, trigger, commit SHA, or pull request number. Use `pageSize` to return up to 200 workflows. ### Parameters `pageSize`integer Number of workflows to return per page. Maximum: 200. Default: 50. `name`string Text to match against the workflow name or file path. Only workflows containing this text are returned. `repo`string Repository to return workflows from, in `owner/name` format. For example, "depot/cli". `status`string\[\] Statuses of workflows to return. Can be "queued", "running", "finished", "failed", or "cancelled". Multiple values are ORed. `trigger`string Trigger event to return workflows for. For example, "push", "pull\_request", "pull\_request\_target", "issue\_comment", "merge\_group", "schedule", "workflow\_run", or "workflow\_dispatch". `sha`string Commit SHA prefix to return workflows for, matched against the parent run's `headSha`. 1-40 hex characters. `pr`string Pull request number to return workflows for. ### Returns `workflows`ListWorkflowsResponseWorkflow\[\] Recent workflows matching the request, newest first. +Show child parameters `workflowId`string Unique identifier for the workflow. `name`string Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `status`string Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled". `trigger`string Event that triggered the parent run. For example, "push", "pull\_request", "pull\_request\_target", "issue\_comment", "merge\_group", "schedule", "workflow\_run", or "workflow\_dispatch". `runId`string Unique identifier for the parent CI run. `sha`string Commit SHA the parent run executes against. Empty for open pull\_request runs. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `createdAt`string Workflow creation time, in RFC 3339 format. `jobCounts`ListWorkflowsResponseJobCounts Counts of jobs in the workflow broken down by status. +Show child parameters `total`integer Total number of jobs in the workflow. `queued`integer Number of jobs currently queued. `waiting`integer Number of jobs waiting on dependencies. `running`integer Number of jobs currently running. `finished`integer Number of jobs that finished successfully. `failed`integer Number of jobs that failed. `cancelled`integer Number of jobs that were cancelled. `skipped`integer Number of jobs that were skipped. POST`/depot.ci.v1.CIService/ListWorkflows` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListWorkflows \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "pageSize": 1,8 "name": "name_example",9 "repo": "repo_example",10 "status": [11 "status_example"12 ],13 "trigger": "trigger_example",14 "sha": "b2f5ff47436671b6e533d8dc3614845d",15 "pr": "pr_example"16}17JSON ``` Response ``` { "workflows": [ { "workflowId": "workflow_123", "name": "name_example", "workflowPath": "workflowPath_example", "repo": "repo_example", "status": "status_example", "trigger": "trigger_example" } ]} ``` ### GetWorkflowCIService.GetWorkflow Returns a workflow's identity, status, timestamps, parent run context, execution history, and nested jobs and attempts. ### Parameters `workflowId`stringrequired Unique identifier for the workflow. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`ListWorkflows`](/content/docs/api/ci/reference#ci-service-list-workflows/index.html). ### Returns `orgId`string Depot organization that owns this workflow. `runId`string Unique identifier for the parent CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the parent run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the parent run executes against. For pull\_request triggers, the merge commit SHA. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `runStatus`string Current state of the parent run. Can be "queued", "running", "finished", "failed", or "cancelled". `runCreatedAt`string Parent run creation time, in RFC 3339 format. `runStartedAt`string Parent run start time, in RFC 3339 format. Empty until the run starts. `runFinishedAt`string Parent run finish time, in RFC 3339 format. Empty until the run finishes. `workflowId`string Unique identifier for the workflow. `workflowName`string Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string `workflowStatus`string Current state of the workflow. Can be "queued", "running", "finished", "failed", or "cancelled". `workflowErrorMessage`string Workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy. `workflowCreatedAt`string Workflow creation time, in RFC 3339 format. `workflowStartedAt`string Workflow start time, in RFC 3339 format. Empty until the workflow starts. `workflowFinishedAt`string Workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `executions`GetWorkflowExecution\[\] Workflow-level execution records; each re-run creates another execution. +Show child parameters `executionId`string Unique identifier for the workflow execution. `execution`integer Execution number, starting at 1 for the first execution. `status`string Current state of the execution. Can be "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Execution creation time, in RFC 3339 format. `startedAt`string Execution start time, in RFC 3339 format. Empty until the execution starts. `finishedAt`string Execution finish time, in RFC 3339 format. Empty until the execution finishes. `jobs`GetWorkflowJob\[\] Workflow jobs and their per-job attempts. +Show child parameters `jobId`string Unique identifier for the job. `jobKey`string Job key from the workflow. For example, "build" or "test". `status`string `startedAt`string Job start time, in RFC 3339 format. Empty until the job starts. `finishedAt`string Job finish time, in RFC 3339 format. Empty until the job finishes. `attempts`GetWorkflowJobAttempt\[\] Per-job attempts, not workflow execution records. +Show child parameters `attemptId`string Unique identifier for the job attempt. `attempt`integer Attempt number, starting at 1 for the first run. `status`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". `sandboxId`string Unique identifier for the sandbox currently running this attempt, when one exists. `sessionId`string Unique identifier for the interactive session attached to that sandbox, when one is available. `startedAt`string Attempt start time, in RFC 3339 format. Empty until the attempt starts. `finishedAt`string Attempt finish time, in RFC 3339 format. Empty until the attempt finishes. `jobDisplayName`string Resolved job name for display. Falls back to the leaf job name, then `jobKey`, when unavailable. Use `jobId` or `jobKey` to identify the job. `waitingReason`string Reason a queued job is waiting. "timer" means it will become eligible at `waitUntil`. Empty otherwise. `waitUntil`string Time the job's configured delay ends, in RFC 3339 format. Empty when the job is not waiting on a timer. POST`/depot.ci.v1.CIService/GetWorkflow` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON ``` Response ``` { "orgId": "org_123", "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example", "runStatus": "runStatus_example"} ``` ### DispatchWorkflowCIService.DispatchWorkflow Triggers a single workflow configured with an `on.workflow_dispatch` trigger and validates inputs against its input schema. ### Parameters `repo`stringrequired 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`stringrequired 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. ### Returns `orgId`string Depot organization that owns this run. `runId`string POST`/depot.ci.v1.CIService/DispatchWorkflow` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/DispatchWorkflow \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 "workflow": "workflow_example",9 "ref": "ref_example",10 "inputs": "inputs_example"11}12JSON ``` Response ``` { "orgId": "org_123", "runId": "run_123"} ``` ### RerunWorkflowCIService.RerunWorkflow Resets every job in a workflow that's in a terminal state (finished, failed, or cancelled) to queued and runs them all again. Cancel the workflow first if it's still running. ### Parameters `workflowId`stringrequired Unique identifier for the workflow to re-run. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`ListWorkflows`](/content/docs/api/ci/reference#ci-service-list-workflows/index.html). ### Returns `workflowId`string Unique identifier for the workflow. Matches the request `workflowId`. A re-run creates a new workflow execution rather than a new workflow. `jobCount`integer Number of jobs reset to queued. A re-run resets every job in the workflow, so this is the workflow's total job count. POST`/depot.ci.v1.CIService/RerunWorkflow` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RerunWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON ``` Response ``` { "workflowId": "workflow_123", "jobCount": 1} ``` ### CancelWorkflowCIService.CancelWorkflow Cancels a queued or running workflow and all its child jobs. ### Parameters `workflowId`stringrequired Unique identifier for the workflow to cancel. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`ListWorkflows`](/content/docs/api/ci/reference#ci-service-list-workflows/index.html). ### Returns `workflowId`string Unique identifier for the workflow. Matches the request `workflowId`. `status`string Updated workflow status. Should be "cancelled". POST`/depot.ci.v1.CIService/CancelWorkflow` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelWorkflow \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON ``` Response ``` { "workflowId": "workflow_123", "status": "status_example"} ``` ## Jobs Inspect, summarize, measure, retry, and cancel CI jobs. [GetJobPOST/depot.ci.v1.CIService/GetJob](/content/docs/api/ci/reference#ci-service-get-job/index.html) [SubmitJobInputPOST/depot.ci.v1.CIService/SubmitJobInput](/content/docs/api/ci/reference#ci-service-submit-job-input/index.html) [GetJobSummaryPOST/depot.ci.v1.CIService/GetJobSummary](/content/docs/api/ci/reference#ci-service-get-job-summary/index.html) [GetJobMetricsPOST/depot.ci.v1.CIService/GetJobMetrics](/content/docs/api/ci/reference#ci-service-get-job-metrics/index.html) [RetryJobPOST/depot.ci.v1.CIService/RetryJob](/content/docs/api/ci/reference#ci-service-retry-job/index.html) [RetryFailedJobsPOST/depot.ci.v1.CIService/RetryFailedJobs](/content/docs/api/ci/reference#ci-service-retry-failed-jobs/index.html) [CancelJobPOST/depot.ci.v1.CIService/CancelJob](/content/docs/api/ci/reference#ci-service-cancel-job/index.html) ### GetJobCIService.GetJob Returns a job's identity, status, timestamps, runner configuration, parent run and workflow context, dependencies, and attempt history. ### Parameters `jobId`stringrequired Unique identifier for the job. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`GetWorkflow`](/content/docs/api/ci/reference#ci-service-get-workflow/index.html). ### Returns `orgId`string Depot organization that owns this job. `runId`string Unique identifier for the parent CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the parent run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the parent run executes against. For pull\_request triggers, the merge commit SHA. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `runStatus`string Current state of the parent run. Can be "queued", "running", "finished", "failed", or "cancelled". `runCreatedAt`string Parent run creation time, in RFC 3339 format. `runStartedAt`string Parent run start time, in RFC 3339 format. Empty until the run starts. `runFinishedAt`string Parent run finish time, in RFC 3339 format. Empty until the run finishes. `workflowId`string Unique identifier for the parent workflow. `workflowName`string Parent workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string Parent workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via `workflowContent` in the [`Run`](/content/docs/api/ci/reference#ci-service-run/index.html) request. `workflowStatus`string Current state of the parent workflow. Can be "queued", "running", "finished", "failed", or "cancelled". `workflowErrorMessage`string Parent workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy. `workflowCreatedAt`string Parent workflow creation time, in RFC 3339 format. `workflowStartedAt`string Parent workflow start time, in RFC 3339 format. Empty until the workflow starts. `workflowFinishedAt`string Parent workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `jobId`string Unique identifier for the job. `jobKey`string Job key from the workflow. For example, "build" or "test". `jobDisplayName`string Human-readable display name from the workflow. Falls back to `jobKey` when no display name is set. `jobStatus`string `jobConclusion`string Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the job concludes. `jobErrorMessage`string Job error message populated for orchestration or worker failures. Empty when the job has no error. `jobCreatedAt`string Job creation time, in RFC 3339 format. `jobDispatchedAt`string Job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker. `jobStartedAt`string Job start time, in RFC 3339 format. Empty until the job starts. `jobFinishedAt`string Job finish time, in RFC 3339 format. Empty until the job finishes. `currentAttemptId`string Unique identifier for the most recent attempt for this job. Empty until the first attempt is dispatched, and cleared while a retried job waits for its next attempt to be dispatched. `currentAttempt`integer Most recent attempt number for this job. Zero until the first attempt is dispatched. `matrix`JobDetailMatrixValue\[\] Matrix key/value pairs for this job instance. Empty when the job is not part of a matrix strategy. +Show child parameters `key`string Matrix dimension name. For example, "os" or "node-version". `value`string Matrix dimension value for this job instance, serialized as a string. `strategy`JobDetailStrategy Strategy context exposing this job's index within its matrix expansion. Unset when no strategy context is available. +Show child parameters `jobIndex`integer Zero-based index of this job within the matrix expansion. `jobTotal`integer Total number of jobs produced by the matrix expansion. `runsOn`JobDetailRunsOn Runner configuration from the job's `runs-on`, such as labels, image, CPU, memory, and size. Unset when no runner configuration is available. +Show child parameters `labels`string\[\] Runner labels specified on the job's `runs-on`. `image`string Container image used for the job, when one is configured. Empty otherwise. `cpus`integer CPU count allocated to the runner. Zero when unset. `memoryGb`integer Memory allocated to the runner, in gigabytes. Zero when unset. `size`string Runner size from the job's `runs-on`, exactly as written in the workflow. Set whenever the runner config used a `${{ }}` expression in its size or image. The value is usually an expression like "${{ vars.RUNNER\_SIZE }}", but can be a literal like "4x16" when only the image was the expression. In that case `cpus` and `memoryGb` are zero and stay zero for the life of the job, so this is the only runner-size value the API reports for it. Empty when the size was a plain literal with no expressions, in which case `cpus` and `memoryGb` carry the resolved values instead. `dependencies`JobDetailDependency\[\] Jobs this job depends on. Contains every dependency when the job has 100 or fewer; for jobs with more, a preview of 100 entries that prioritizes failed and cancelled dependencies. +Show child parameters `jobId`string Unique identifier for the dependency job. `jobKey`string Job key from the workflow. For example, "build" or "test". `jobDisplayName`string Human-readable display name from the workflow. Falls back to `jobKey` when no display name is set. `status`string Current state of the dependency 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. `conclusion`string Conclusion of the dependency job. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the job concludes. `errorMessage`string Dependency job error message populated for orchestration or worker failures. Empty when the job has no error. `createdAt`string Dependency job creation time, in RFC 3339 format. `dispatchedAt`string Dependency job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker. `startedAt`string Dependency job start time, in RFC 3339 format. Empty until the job starts. `finishedAt`string Dependency job finish time, in RFC 3339 format. Empty until the job finishes. `attempts`JobDetailAttempt\[\] Attempt history for this job, ordered by attempt number ascending. +Show child parameters `attemptId`string Unique identifier for the job attempt. `attempt`integer Attempt number, starting at 1 for the first run. `status`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". `conclusion`string Conclusion of the attempt. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the attempt concludes. `errorMessage`string Attempt error message populated for orchestration or worker failures. Empty when the attempt has no error. `sandboxId`string Unique identifier for the sandbox that ran this attempt, when one exists. `sessionId`string Unique identifier for the interactive session attached to that sandbox, when one is available. `createdAt`string Attempt creation time, in RFC 3339 format. `dispatchedAt`string Attempt dispatch time, in RFC 3339 format. Empty until the attempt is dispatched to a worker. `startedAt`string Attempt start time, in RFC 3339 format. Empty until the attempt starts. `finishedAt`string Attempt finish time, in RFC 3339 format. Empty until the attempt finishes. `isCurrent`boolean True when this attempt is the job's current attempt. `dependencyCount`integer \| null Total number of dependencies. Set only when `dependencies` is a capped preview. `dependencyPreviewLimit`integer \| null Maximum number of entries returned in `dependencies`. Set only when `dependencies` is a capped preview. `snapshotRef`string Immutable snapshot image reference resolved for this job. Empty when the job is not a snapshot producer or the resolved ref is not available. `snapshotCached`boolean \| null True when the snapshot producer used an existing snapshot instead of running setup work. Unset when the job is not a snapshot producer or the resolved ref is not available. `waitingReason`string Reason a queued job is waiting. "timer" means it will become eligible at `waitUntil`. Empty otherwise. `waitUntil`string Time the job's configured delay ends, in RFC 3339 format. Empty when the job is not waiting on a timer. `inputRequest`JobInputRequest Resolved input controls and accepted response. Unset for jobs without a dispatched input request. +Show child parameters `text`string Resolved question presented to the responder. `fields`JobInputField\[\] Controls in presentation order. +Show child parameters `id`string Identifier used as the key in the submitted answer. `type`string Control type. Can be "select" or "buttons". `label`string Display label. Empty when the control has no label. `options`JobInputOption\[\] Available choices in presentation order. `answer`JobInputAnswer Accepted response. Unset until someone answers. +Show child parameters `fields`object Submitted values keyed by control identifier. `userId`string Identifier of the authenticated responder in the source channel. `answeredAt`string Acceptance time, in RFC 3339 format. Empty for older responses. `channel`string Channel through which the answer was submitted. Can be "web" or "slack". `deadline`string Response deadline, in RFC 3339 format. `attemptId`string Unique identifier for the attempt that requested input. POST`/depot.ci.v1.CIService/GetJob` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123"8}9JSON ``` Response ### SubmitJobInputCIService.SubmitJobInput Submit an answer to a running input job. ### Parameters `jobId`string Unique identifier for the job. Returned by [`GetJob`](/content/docs/api/ci/reference#ci-service-get-job/index.html). `attemptId`string Unique identifier for the current attempt. Returned by [`GetJob`](/content/docs/api/ci/reference#ci-service-get-job/index.html). `fields`object Selected values keyed by the declared control identifiers, including the clicked button. ### Returns This method does not document a success response. POST`/depot.ci.v1.CIService/SubmitJobInput` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/SubmitJobInput \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123",8 "attemptId": "attempt_123",9 "fields": "fields_example"10}11JSON ``` Response ``` {} ``` ### GetJobSummaryCIService.GetJobSummary Returns authored step summary markdown for a job, a specific attempt, or both. ### Parameters `jobId`string Unique identifier for the job whose current attempt should be summarized. Required unless attemptId is set. `attemptId`string Unique identifier for a specific job attempt to summarize. Required unless jobId is set. When sent alongside jobId, the attempt must belong to that job. ### Returns `orgId`string Organization that owns this job. `runId`string Unique identifier for the parent CI run. `workflowId`string Unique identifier for the parent workflow. `jobId`string Unique identifier for the job. `attemptId`string Unique identifier for the job attempt. Empty when no attempt exists yet. `attempt`integer Attempt number, starting at 1. Zero when no attempt exists yet. `jobStatus`string `attemptStatus`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". Empty when no attempt exists yet. `hasSummary`boolean True when authored step summary markdown is available for the selected attempt. `emptyReason`string Set when hasSummary is false, for example "no\_summary" or "no\_attempt". `stepCount`integer Count of non-empty step summaries included in markdown. `markdown`string Authored step summary markdown joined in step order. POST`/depot.ci.v1.CIService/GetJobSummary` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobSummary \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123",8 "attemptId": "attempt_123"9}10JSON ``` Response ``` { "orgId": "org_123", "runId": "run_123", "workflowId": "workflow_123", "jobId": "job_123", "attemptId": "attempt_123", "attempt": 1, "jobStatus": "jobStatus_example", "attemptStatus": "attemptStatus_example"} ``` ### GetJobMetricsCIService.GetJobMetrics Returns per-attempt CPU and memory metric summaries for one job. ### Parameters `jobId`stringrequired Unique identifier for the job. ### Returns `run`CIMetricsRunContext Parent run context: identifiers, trigger, status, and lifecycle timestamps. +Show child parameters `runId`string Unique identifier for the CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the run executes against. Empty for open pull\_request runs. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `status`string Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Run creation time, in RFC 3339 format. `startedAt`string Run start time, in RFC 3339 format. Empty until the run starts. `finishedAt`string Run finish time, in RFC 3339 format. Empty until the run finishes. `workflow`CIMetricsWorkflowContext Parent workflow context: identifiers, status, and lifecycle timestamps. +Show child parameters `workflowId`string Unique identifier for the workflow. `workflowPath`string `name`string Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `status`string Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Workflow creation time, in RFC 3339 format. `startedAt`string Workflow start time, in RFC 3339 format. Empty until the workflow starts. `finishedAt`string Workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `job`CIMetricsJobContext Job context: identifiers, status, conclusion, and lifecycle timestamps. +Show child parameters `jobId`string Unique identifier for the job. `jobKey`string Job key from the workflow. For example, "build" or "test". `status`string `conclusion`string Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the job concludes. `currentAttempt`integer Most recent attempt number for this job. Zero until the first attempt is dispatched. `createdAt`string Job creation time, in RFC 3339 format. `startedAt`string Job start time, in RFC 3339 format. Empty until the job starts. `finishedAt`string Job finish time, in RFC 3339 format. Empty until the job finishes. `attempts`CIMetricsAttemptSummary\[\] Per-attempt metric summaries for this job, ordered by attempt number ascending. +Show child parameters `attempt`CIMetricsAttemptContext Attempt context: identifiers, status, conclusion, and lifecycle timestamps. +Show child parameters `attemptId`string Unique identifier for the job attempt. `attempt`integer Attempt number, starting at 1 for the first run. `status`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". `conclusion`string Conclusion of the attempt. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the attempt concludes. `sandboxId`string Unique identifier for the sandbox that ran this attempt, when one exists. `sessionId`string Unique identifier for the interactive session attached to that sandbox, when one is available. `createdAt`string Attempt creation time, in RFC 3339 format. `startedAt`string Attempt start time, in RFC 3339 format. Empty until the attempt starts. `finishedAt`string Attempt finish time, in RFC 3339 format. Empty until the attempt finishes. `availability`CIMetricsAvailability Availability code and reason explaining why metrics are or are not present. +Show child parameters `code`CIMetricsAvailabilityCode Availability code. - AVAILABLE: Metrics samples were observed for the attempt. - NO\_SANDBOX: The attempt never ran on a sandbox, so no metrics could be collected. - NO\_TIME\_RANGE: The attempt has no resolvable start and finish time, so no metric window could be queried. - NO\_SAMPLES: The attempt ran on a sandbox but no samples were recorded in its time range. Possible enum values `CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED``CI_METRICS_AVAILABILITY_CODE_AVAILABLE``CI_METRICS_AVAILABILITY_CODE_NO_SANDBOX``CI_METRICS_AVAILABILITY_CODE_NO_TIME_RANGE``CI_METRICS_AVAILABILITY_CODE_NO_SAMPLES` `reason`string Short reason string matching the code, for example "available", "no\_sandbox", "no\_time\_range", or "no\_samples". `stats`CIMetricsStats Aggregate CPU and memory statistics computed across the raw samples. +Show child parameters `sampleCount`integer Total number of merged samples observed for the attempt. `cpuSampleCount`integer Number of samples that included a CPU utilization value. `memorySampleCount`integer Number of samples that included a memory utilization value. `peakCpuUtilization`number \| null Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed. `averageCpuUtilization`number \| null Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed. `peakMemoryUtilization`number \| null Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed. `averageMemoryUtilization`number \| null Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed. `observedStartedAt`string Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed. `observedFinishedAt`string Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed. `peakMemoryUsageBytes`integer \| string \| null Peak observed memory usage in bytes. Unset when no memory samples were observed. `averageMemoryUsageBytes`number \| null Average observed memory usage in bytes. Unset when no memory samples were observed. `cap`CIMetricsCapMetadata Downsampling metadata describing how raw samples were reduced for transport. +Show child parameters `rawSampleCount`integer Raw sample count observed before downsampling. `returnedSampleCount`integer Number of samples returned in the response. `maxReturnedSampleCount`integer Hard cap on the number of samples a single response will return. `downsampled`boolean True when the raw samples were downsampled to fit maxReturnedSampleCount. `downsampleStrategy`string Identifier for the downsampling strategy used, for example "peak\_preserving\_even". Empty when no downsampling was applied. `snapshotAt`string POST`/depot.ci.v1.CIService/GetJobMetrics` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobMetrics \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "jobId": "job_123"8}9JSON ``` Response ``` { "run": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "workflow": { "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "name": "name_example", "status": "status_example", "createdAt": "createdAt_example", "startedAt": "startedAt_example" }, "job": { "jobId": "job_123", "jobKey": "jobKey_example", "status": "status_example", "conclusion": "conclusion_example", "currentAttempt": 1, "createdAt": "createdAt_example" }, "attempts": [ { "attempt": { "attemptId": "attempt_123", "attempt": 1, "status": "status_example", "conclusion": "conclusion_example", "sandboxId": "sandbox_123", "sessionId": "session_123" }, "availability": { "code": "CI_METRICS_AVAILABILITY_CODE_UNSPECIFIED", "reason": "reason_example" }, "stats": { "sampleCount": 1, "cpuSampleCount": 1, "memorySampleCount": 1, "peakCpuUtilization": 1, "averageCpuUtilization": 1, "peakMemoryUtilization": 1 }, "cap": { "rawSampleCount": 1, "returnedSampleCount": 1, "maxReturnedSampleCount": 1, "downsampled": false, "downsampleStrategy": "downsampleStrategy_example" } } ], "snapshotAt": "snapshotAt_example"} ``` ### RetryJobCIService.RetryJob Retries a failed or cancelled job, along with any skipped jobs that depend on it. Fails when a job that depends on it has already started; use [`RetryFailedJobs`](/content/docs/api/ci/reference#ci-service-retry-failed-jobs/index.html) to retry related failures together. ### Parameters `workflowId`stringrequired Unique identifier for the workflow containing the job. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`ListWorkflows`](/content/docs/api/ci/reference#ci-service-list-workflows/index.html). `jobId`stringrequired Unique identifier for the job to retry. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`GetWorkflow`](/content/docs/api/ci/reference#ci-service-get-workflow/index.html). ### Returns `jobId`string Unique identifier for the job. Matches the request `jobId`. A retry creates a new attempt rather than a new job. `attemptId`string Empty in the response. The new attempt is created once the job runs again and appears in the `attempts` array returned by [`GetJob`](/content/docs/api/ci/reference#ci-service-get-job/index.html). `attempt`integer Attempt number the next attempt will use, one greater than the prior attempt. `status`string Updated job status. Should be "queued". POST`/depot.ci.v1.CIService/RetryJob` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123",8 "jobId": "job_123"9}10JSON ``` Response ``` { "jobId": "job_123", "attemptId": "attempt_123", "attempt": 1, "status": "status_example"} ``` ### RetryFailedJobsCIService.RetryFailedJobs Retries the failed and cancelled jobs in a workflow, along with every job that depends on them. A dependent that already succeeded or was skipped runs again too, because a job it consumed is running again. Queued dependents are left untouched, since they re-check their dependencies before starting. Fails without resetting anything when a waiting or running job depends on the retried set; wait for that job to finish, or cancel the workflow and use [`RerunWorkflow`](/content/docs/api/ci/reference#ci-service-rerun-workflow/index.html). ### Parameters `workflowId`stringrequired Unique identifier for the workflow containing failed jobs. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`ListWorkflows`](/content/docs/api/ci/reference#ci-service-list-workflows/index.html). ### Returns `workflowId`string Unique identifier for the workflow. Matches the request `workflowId`. A retry creates a new workflow execution rather than a new workflow. `jobIds`string\[\] Unique identifiers for jobs that were set back to queued. A new attempt is created for each job when it runs again. `jobCount`integer Number of jobs reset to queued. Includes the failed and cancelled jobs, plus every job that depends on them, whether it previously succeeded or was skipped. Equal to the number of entries in the `jobIds` array. POST`/depot.ci.v1.CIService/RetryFailedJobs` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/RetryFailedJobs \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123"8}9JSON ``` Response ``` { "workflowId": "workflow_123", "jobIds": [ "job_123" ], "jobCount": 1} ``` ### CancelJobCIService.CancelJob Cancels a queued, waiting, or running job and its active attempt. ### Parameters `workflowId`stringrequired `jobId`stringrequired Unique identifier for the job to cancel. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html) and [`GetWorkflow`](/content/docs/api/ci/reference#ci-service-get-workflow/index.html). ### Returns `jobId`string Unique identifier for the job. Matches the request `jobId`. `status`string Updated job status. Should be "cancelled". POST`/depot.ci.v1.CIService/CancelJob` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/CancelJob \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "workflowId": "workflow_123",8 "jobId": "job_123"9}10JSON ``` Response ``` { "jobId": "job_123", "status": "status_example"} ``` ## Attempts Inspect job attempts and their execution metrics. [GetAttemptPOST/depot.ci.v1.CIService/GetAttempt](/content/docs/api/ci/reference#ci-service-get-attempt/index.html) [GetJobAttemptMetricsPOST/depot.ci.v1.CIService/GetJobAttemptMetrics](/content/docs/api/ci/reference#ci-service-get-job-attempt-metrics/index.html) ### GetAttemptCIService.GetAttempt Returns an attempt's identity, status, timestamps, and sandbox/session IDs, with parent run, workflow, and job context. ### Parameters `attemptId`stringrequired Unique identifier for the job attempt. Returned by [`GetRunStatus`](/content/docs/api/ci/reference#ci-service-get-run-status/index.html), [`GetWorkflow`](/content/docs/api/ci/reference#ci-service-get-workflow/index.html), and [`GetJob`](/content/docs/api/ci/reference#ci-service-get-job/index.html). ### Returns `orgId`string Depot organization that owns this attempt. `runId`string Unique identifier for the parent CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the parent run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the parent run executes against. For pull\_request triggers, the merge commit SHA. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `runStatus`string Current state of the parent run. Can be "queued", "running", "finished", "failed", or "cancelled". `runCreatedAt`string Parent run creation time, in RFC 3339 format. `runStartedAt`string Parent run start time, in RFC 3339 format. Empty until the run starts. `runFinishedAt`string Parent run finish time, in RFC 3339 format. Empty until the run finishes. `workflowId`string Unique identifier for the parent workflow. `workflowName`string Parent workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string `workflowStatus`string Current state of the parent workflow. Can be "queued", "running", "finished", "failed", or "cancelled". `workflowErrorMessage`string Parent workflow error or cancellation reason. For example, a compilation or validation error. Empty when the workflow is healthy. `workflowCreatedAt`string Parent workflow creation time, in RFC 3339 format. `workflowStartedAt`string Parent workflow start time, in RFC 3339 format. Empty until the workflow starts. `workflowFinishedAt`string Parent workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `jobId`string Unique identifier for the parent job. `jobKey`string Parent job key from the workflow. For example, "build" or "test". `jobDisplayName`string Human-readable display name for the parent job. Falls back to `jobKey` when no display name is set. `jobStatus`string Current state of the parent 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. `jobConclusion`string Conclusion of the parent job. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the job concludes. `jobErrorMessage`string Parent job error message populated for orchestration or worker failures. Empty when the job has no error. `jobCreatedAt`string Parent job creation time, in RFC 3339 format. `jobDispatchedAt`string Parent job dispatch time, in RFC 3339 format. Empty until the job is dispatched to a worker. `jobStartedAt`string Parent job start time, in RFC 3339 format. Empty until the job starts. `jobFinishedAt`string Parent job finish time, in RFC 3339 format. Empty until the job finishes. `currentAttemptId`string Unique identifier for the parent job's most recent attempt. Equals `attempt.attemptId` when this is the current attempt. `currentAttempt`integer Most recent attempt number for the parent job. Equals `attempt.attempt` when this is the current attempt. `matrix`JobDetailMatrixValue\[\] Matrix key/value pairs for the parent job instance. Empty when the job is not part of a matrix strategy. +Show child parameters `key`string Matrix dimension name. For example, "os" or "node-version". `value`string Matrix dimension value for this job instance, serialized as a string. `strategy`JobDetailStrategy Strategy context exposing the parent job's index within its matrix expansion. Unset when no strategy context is available. +Show child parameters `jobIndex`integer Zero-based index of this job within the matrix expansion. `jobTotal`integer Total number of jobs produced by the matrix expansion. `runsOn`JobDetailRunsOn Runner configuration from the parent job's `runs-on`: labels, image, CPU, memory, and size. Unset when no runner configuration is available. +Show child parameters `labels`string\[\] Runner labels specified on the job's `runs-on`. `image`string Container image used for the job, when one is configured. Empty otherwise. `cpus`integer CPU count allocated to the runner. Zero when unset. `memoryGb`integer Memory allocated to the runner, in gigabytes. Zero when unset. `size`string Runner size from the job's `runs-on`, exactly as written in the workflow. `attempt`JobDetailAttempt The requested attempt's identifiers, lifecycle timestamps, conclusion, and sandbox/session linkage. +Show child parameters `attemptId`string Unique identifier for the job attempt. `attempt`integer Attempt number, starting at 1 for the first run. `status`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". `conclusion`string Conclusion of the attempt. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the attempt concludes. `errorMessage`string Attempt error message populated for orchestration or worker failures. Empty when the attempt has no error. `sandboxId`string Unique identifier for the sandbox that ran this attempt, when one exists. `sessionId`string Unique identifier for the interactive session attached to that sandbox, when one is available. `createdAt`string Attempt creation time, in RFC 3339 format. `dispatchedAt`string Attempt dispatch time, in RFC 3339 format. Empty until the attempt is dispatched to a worker. `startedAt`string Attempt start time, in RFC 3339 format. Empty until the attempt starts. `finishedAt`string Attempt finish time, in RFC 3339 format. Empty until the attempt finishes. `isCurrent`boolean True when this attempt is the job's current attempt. POST`/depot.ci.v1.CIService/GetAttempt` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetAttempt \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123"8}9JSON ``` Response ### GetJobAttemptMetricsCIService.GetJobAttemptMetrics Returns CPU and memory metrics for one job attempt. ### Parameters `attemptId`stringrequired Unique identifier for the job attempt. ### Returns `run`CIMetricsRunContext Parent run context: identifiers, trigger, status, and lifecycle timestamps. +Show child parameters `runId`string Unique identifier for the CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the run executes against. Empty for open pull\_request runs. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `status`string Current state of the run, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Run creation time, in RFC 3339 format. `startedAt`string Run start time, in RFC 3339 format. Empty until the run starts. `finishedAt`string Run finish time, in RFC 3339 format. Empty until the run finishes. `workflow`CIMetricsWorkflowContext Parent workflow context: identifiers, status, and lifecycle timestamps. +Show child parameters `workflowId`string Unique identifier for the workflow. `workflowPath`string `name`string Workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `status`string Current state of the workflow, for example "queued", "running", "finished", "failed", or "cancelled". `createdAt`string Workflow creation time, in RFC 3339 format. `startedAt`string Workflow start time, in RFC 3339 format. Empty until the workflow starts. `finishedAt`string Workflow finish time, in RFC 3339 format. Empty until the workflow finishes. `job`CIMetricsJobContext Parent job context: identifiers, status, conclusion, and lifecycle timestamps. +Show child parameters `jobId`string Unique identifier for the job. `jobKey`string Job key from the workflow. For example, "build" or "test". `status`string `conclusion`string Conclusion of the job. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the job concludes. `currentAttempt`integer Most recent attempt number for this job. Zero until the first attempt is dispatched. `createdAt`string Job creation time, in RFC 3339 format. `startedAt`string Job start time, in RFC 3339 format. Empty until the job starts. `finishedAt`string Job finish time, in RFC 3339 format. Empty until the job finishes. `attempt`CIMetricsAttemptMetrics Attempt-level metrics: attempt context, availability, summary stats, downsampling metadata, and raw samples. +Show child parameters `attempt`CIMetricsAttemptContext Attempt context: identifiers, status, conclusion, and lifecycle timestamps. +Show child parameters `attemptId`string Unique identifier for the job attempt. `attempt`integer Attempt number, starting at 1 for the first run. `status`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". `conclusion`string Conclusion of the attempt. Can be "success", "failure", "cancelled", "skipped", or "timed\_out". Empty until the attempt concludes. `sandboxId`string Unique identifier for the sandbox that ran this attempt, when one exists. `sessionId`string Unique identifier for the interactive session attached to that sandbox, when one is available. `createdAt`string Attempt creation time, in RFC 3339 format. `startedAt`string Attempt start time, in RFC 3339 format. Empty until the attempt starts. `finishedAt`string Attempt finish time, in RFC 3339 format. Empty until the attempt finishes. `availability`CIMetricsAvailability Availability code and reason explaining why metrics are or are not present. +Show child parameters `code`CIMetricsAvailabilityCode Availability code. Possible enum values `reason`string Short reason string matching the code, for example "available", "no\_sandbox", "no\_time\_range", or "no\_samples". `stats`CIMetricsStats Aggregate CPU and memory statistics computed across the raw samples. +Show child parameters `sampleCount`integer Total number of merged samples observed for the attempt. `cpuSampleCount`integer Number of samples that included a CPU utilization value. `memorySampleCount`integer Number of samples that included a memory utilization value. `peakCpuUtilization`number \| null Peak observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed. `averageCpuUtilization`number \| null Average observed CPU utilization as a fraction from 0 to 1. Unset when no CPU samples were observed. `peakMemoryUtilization`number \| null Peak observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed. `averageMemoryUtilization`number \| null Average observed memory utilization as a fraction from 0 to 1. Unset when no memory samples were observed. `observedStartedAt`string Timestamp of the first observed sample, in RFC 3339 format. Empty when no samples were observed. `observedFinishedAt`string Timestamp of the last observed sample, in RFC 3339 format. Empty when no samples were observed. `peakMemoryUsageBytes`integer \| string \| null Peak observed memory usage in bytes. Unset when no memory samples were observed. `averageMemoryUsageBytes`number \| null Average observed memory usage in bytes. Unset when no memory samples were observed. `cap`CIMetricsCapMetadata Downsampling metadata describing how raw samples were reduced for transport. +Show child parameters `rawSampleCount`integer Raw sample count observed before downsampling. `returnedSampleCount`integer Number of samples returned in the response. `maxReturnedSampleCount`integer Hard cap on the number of samples a single response will return. `downsampled`boolean True when the raw samples were downsampled to fit maxReturnedSampleCount. `downsampleStrategy`string Identifier for the downsampling strategy used, for example "peak\_preserving\_even". Empty when no downsampling was applied. `samples`CIMetricSample\[\] Time-ordered CPU and memory samples for the attempt, possibly downsampled. +Show child parameters `timestamp`string Sample timestamp, in RFC 3339 format. `cpuUtilization`number \| null CPU utilization as a fraction from 0 to 1. Unset when no CPU sample was recorded at this timestamp. `memoryUtilization`number \| null Memory utilization as a fraction from 0 to 1. Unset when no memory sample was recorded at this timestamp. `memoryUsageBytes`integer \| string \| null Memory usage in bytes. Unset when no memory sample was recorded at this timestamp. `snapshotAt`string POST`/depot.ci.v1.CIService/GetJobAttemptMetrics` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptMetrics \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123"8}9JSON ``` Response ## Logs Read, stream, and export job attempt logs. [GetJobAttemptLogsPOST/depot.ci.v1.CIService/GetJobAttemptLogs](/content/docs/api/ci/reference#ci-service-get-job-attempt-logs/index.html) [StreamJobAttemptLogsPOST/depot.ci.v1.CIService/StreamJobAttemptLogs](/content/docs/api/ci/reference#ci-service-stream-job-attempt-logs/index.html) [ExportJobAttemptLogsPOST/depot.ci.v1.CIService/ExportJobAttemptLogs](/content/docs/api/ci/reference#ci-service-export-job-attempt-logs/index.html) ### GetJobAttemptLogsCIService.GetJobAttemptLogs Returns persisted log lines for a job attempt, oldest first. Identify the attempt by `attemptId`, or by `jobId` to use the job's latest attempt. Poll with `pageToken` to fetch lines persisted after a previous response. ### Parameters `attemptId`string Unique identifier for the job attempt. Set exactly one of `attemptId` or `jobId`. `pageToken`string Token to fetch lines after a previous response. Use the `nextPageToken` value from a prior response. Leave empty to fetch from the first line. `jobId`string \| null Unique identifier for a CI job. Resolves to the job's latest attempt; the page token pins that attempt, so later pages stay on the same attempt even if a retry creates a newer one. Set exactly one of `attemptId` or `jobId`. ### Returns `lines`LogLine\[\] Persisted log lines for the attempt, ordered by timestamp and line number. +Show child parameters `stepKey`string Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step. `timestampMs`integer \| string Log timestamp as Unix epoch milliseconds. `lineNumber`integer Persisted line number within the emitting stream. `stream`integer 0 for stdout, 1 for stderr. `body`string Log line content, without a trailing newline. `stepId`string User-authored workflow step ID from the step's `id:` key. Empty when not set. `stepName`string User-authored workflow step name from the step's `name:` key. Empty when not set. `nextPageToken`string Token to fetch lines persisted after this response. Empty when the response contains no lines. While the attempt is running, poll with the newest token to tail new lines. POST`/depot.ci.v1.CIService/GetJobAttemptLogs` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetJobAttemptLogs \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "attemptId": "attempt_123",8 "pageToken": "pageToken_example",9 "jobId": "job_123"10}11JSON ``` Response ``` { "lines": [ { "stepKey": "stepKey_example", "timestampMs": 1, "lineNumber": 1, "stream": 1, "body": "body_example", "stepId": "step_123" } ], "nextPageToken": "nextPageToken_example"} ``` ### StreamJobAttemptLogsCIService.StreamJobAttemptLogsstream Follows a job attempt's persisted log lines, streaming new lines while the attempt runs. The response is a Connect/gRPC server stream, not raw text. Consume it with a generated client or a decoder that understands stream framing. Every response reports the attempt's current status. Responses that carry a log line also include `nextCursor`. To resume a dropped stream, save the newest `nextCursor` and send it as `cursor` on a new request. The new stream picks up after the last line you received. The stream ends on its own once the attempt has finished, failed, or been cancelled and all persisted lines have been sent. ### Parameters `attemptId`string Unique identifier for the job attempt. Set exactly one of `attemptId` or `jobId`. `cursor`string Opaque cursor returned by a previous stream response for the same target. Omit it to stream from the first persisted line. `jobId`string Unique identifier for a CI job. The stream resolves it to that job's latest attempt. Set exactly one of `attemptId` or `jobId`. ### Returns `line`LogLine Set when this response carries a persisted log line. Status-only responses can omit it while the stream is waiting for rows. +Show child parameters `stepKey`string Depot-assigned key correlating the line with a workflow step. Stable across responses for the same step. `timestampMs`integer \| string Log timestamp as Unix epoch milliseconds. `lineNumber`integer Persisted line number within the emitting stream. `stream`integer 0 for stdout, 1 for stderr. `body`string Log line content, without a trailing newline. `stepId`string User-authored workflow step ID from the step's `id:` key. Empty when not set. `stepName`string User-authored workflow step name from the step's `name:` key. Empty when not set. `nextCursor`string Opaque cursor to resume after the emitted line. Set on responses that carry a line. Persist the newest value and send it as `cursor` on a later request. `attemptStatus`string Current state of the attempt. Can be "queued", "waiting", "running", "finished", "failed", or "cancelled". Server-streaming RPC. The examples show decoded message payloads; the raw HTTP response is Connect-framed and should be read with a generated client or protocol-aware decoder. POST`/depot.ci.v1.CIService/StreamJobAttemptLogs` cURLNode.jsGo ``` 1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.StreamJobAttemptLogs6# Path: /depot.ci.v1.CIService/StreamJobAttemptLogs ``` Stream messages ``` { "line": { "stepKey": "stepKey_example", "timestampMs": 1, "lineNumber": 1, "stream": 1, "body": "body_example", "stepId": "step_123" }, "nextCursor": "nextCursor_example", "attemptStatus": "attemptStatus_example"} ``` ### ExportJobAttemptLogsCIService.ExportJobAttemptLogsstream Exports a finite snapshot of persisted log lines. The response is a Connect/gRPC server stream, not a raw HTTP file download. Consume it with a generated client or a decoder that understands stream framing. Read the first metadata response, then append each following chunk response to a file or writer in order. Use the Depot CLI `depot ci logs --output-file` when a shell-native file download is needed. ### Parameters `attemptId`string Unique identifier for the job attempt. Set exactly one of `attemptId` or `jobId`. `jobId`string Unique identifier for a CI job. Export resolves it to that job's latest attempt at stream start. Set exactly one of `attemptId` or `jobId`. `format`JobAttemptLogExportFormat Selects the export byte format. Default: text. Possible enum values `JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED``JOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXT``JOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL` ### Returns chunkobject `chunk`stringrequired Export file bytes, at most 256 KiB per chunk. Append chunks in stream order to reconstruct the text or JSONL export. In JSON-encoded Connect/grpc-web protocols, bytes are represented using the protocol's base64 encoding. metadataobject `metadata`JobAttemptLogExportMetadatarequired First response in every successful export stream. Describes the byte format and advisory filename for following chunks. +Show child parameters `filename`string Suggested filename for saving the export, with the extension matching the format. .txt for text or .jsonl for JSONL. The naming pattern isn't guaranteed and may change, so don't extract the attempt ID or other values from it. `contentType`string Exact media type for chunk bytes. `text/plain; charset=utf-8` for text or `application/x-ndjson; charset=utf-8` for JSONL. `format`JobAttemptLogExportFormat Selected byte format for following chunk responses. Possible enum values `JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED``JOB_ATTEMPT_LOG_EXPORT_FORMAT_TEXT``JOB_ATTEMPT_LOG_EXPORT_FORMAT_JSONL` POST`/depot.ci.v1.CIService/ExportJobAttemptLogs` cURLNode.jsGo ``` 1# Server-streaming RPC2# Use a generated Connect client or protocol-aware decoder.3# Raw curl cannot send or decode this framed stream as shown.4# Protocol spec: https://connectrpc.com/docs/protocol/#streaming-rpcs5# RPC: CIService.ExportJobAttemptLogs6# Path: /depot.ci.v1.CIService/ExportJobAttemptLogs ``` Stream messages ``` { "metadata": { "filename": "filename_example", "contentType": "contentType_example", "format": "JOB_ATTEMPT_LOG_EXPORT_FORMAT_UNSPECIFIED" }} { "chunk": "chunk_example"} ``` ## Artifacts List artifacts and create signed artifact download URLs. [ListArtifactsPOST/depot.ci.v1.CIService/ListArtifacts](/content/docs/api/ci/reference#ci-service-list-artifacts/index.html) [GetArtifactDownloadURLPOST/depot.ci.v1.CIService/GetArtifactDownloadURL](/content/docs/api/ci/reference#ci-service-get-artifact-download-url/index.html) ### ListArtifactsCIService.ListArtifacts Returns CI artifact metadata for one run, optionally narrowed to a workflow, job, or attempt. Download URLs are not included; request one per artifact with [`GetArtifactDownloadURL`](/content/docs/api/ci/reference#ci-service-get-artifact-download-url/index.html). ### Parameters `runId`stringrequired `workflowId`string \| null Narrows the list to artifacts from one workflow. Must belong to the run. Leave unset to include all workflows. `jobId`string \| null Narrows the list to artifacts from one job. Must belong to the run, and to `workflowId` when both are set. Leave unset to include all jobs. `attemptId`string \| null Narrows the list to artifacts from one job attempt. Must belong to the run, and to `workflowId` and `jobId` when set. Leave unset to include all attempts. `pageSize`integer Number of artifacts to return per page. Maximum: 500. Default: 100. `pageToken`string Token to fetch the next page of artifacts. Use the `nextPageToken` value from a prior response with the same filters. Leave empty to fetch the first page. ### Returns `artifacts`Artifact\[\] Artifacts matching the request, up to `pageSize` entries. +Show child parameters `artifactId`string Unique identifier for the artifact. Pass it to [`GetArtifactDownloadURL`](/content/docs/api/ci/reference#ci-service-get-artifact-download-url/index.html) to download the artifact. `runId`string Unique identifier for the parent CI run. `workflowId`string Unique identifier for the parent workflow. `workflowPath`string `jobId`string Unique identifier for the parent job. `jobKey`string Parent job key from the workflow. For example, "build" or "test". `attemptId`string Unique identifier for the job attempt that produced the artifact. `attempt`integer Attempt number that produced the artifact, starting at 1. `name`string Artifact name as authored by the workflow. `sizeBytes`integer \| string Artifact size in bytes. `createdAt`string Artifact creation time, in RFC 3339 format. `nextPageToken`string \| null Token to retrieve the next page of results. Unset when no more pages are available. POST`/depot.ci.v1.CIService/ListArtifacts` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/ListArtifacts \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 "workflowId": "workflow_123",9 "jobId": "job_123",10 "attemptId": "attempt_123",11 "pageSize": 1,12 "pageToken": "pageToken_example"13}14JSON ``` Response ``` { "artifacts": [ { "artifactId": "artifact_123", "runId": "run_123", "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" } ], "nextPageToken": "nextPageToken_example"} ``` ### GetArtifactDownloadURLCIService.GetArtifactDownloadURL Returns a short-lived signed HTTPS URL for one artifact. The URL expires 5 minutes after issuance. ### Parameters `artifactId`stringrequired Unique identifier for the artifact. Returned by [`ListArtifacts`](/content/docs/api/ci/reference#ci-service-list-artifacts/index.html). ### Returns `artifact`Artifact Artifact metadata for the requested `artifactId`. +Show child parameters `artifactId`string Unique identifier for the artifact. Pass it to `GetArtifactDownloadURL` to download the artifact. `runId`string Unique identifier for the parent CI run. `workflowId`string Unique identifier for the parent workflow. `workflowPath`string `jobId`string Unique identifier for the parent job. `jobKey`string Parent job key from the workflow. For example, "build" or "test". `attemptId`string Unique identifier for the job attempt that produced the artifact. `attempt`integer Attempt number that produced the artifact, starting at 1. `name`string Artifact name as authored by the workflow. `sizeBytes`integer \| string Artifact size in bytes. `createdAt`string Artifact creation time, in RFC 3339 format. `url`string Signed HTTPS URL for the artifact content. Works with any standard HTTPS client and needs no extra authentication; anyone holding the URL can download the artifact until it expires. `expiresAt`string Signed URL expiration time, in RFC 3339 format. URLs expire 5 minutes after issuance. Artifact retention is unaffected. POST`/depot.ci.v1.CIService/GetArtifactDownloadURL` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetArtifactDownloadURL \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "artifactId": "artifact_123"8}9JSON ``` Response ``` { "artifact": { "artifactId": "artifact_123", "runId": "run_123", "workflowId": "workflow_123", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" }, "url": "https://example.com", "expiresAt": "expiresAt_example"} ``` ## Secrets List and manage CI secrets and their variants. [ListSecretsPOST/depot.ci.v3beta2.SecretService/ListSecrets](/content/docs/api/ci/reference#secret-service-list-secrets/index.html) [ListSecretAttributesPOST/depot.ci.v3beta2.SecretService/ListSecretAttributes](/content/docs/api/ci/reference#secret-service-list-secret-attributes/index.html) [GetSecretPOST/depot.ci.v3beta2.SecretService/GetSecret](/content/docs/api/ci/reference#secret-service-get-secret/index.html) [GetSecretVariantPOST/depot.ci.v3beta2.SecretService/GetSecretVariant](/content/docs/api/ci/reference#secret-service-get-secret-variant/index.html) [CreateSecretVariantPOST/depot.ci.v3beta2.SecretService/CreateSecretVariant](/content/docs/api/ci/reference#secret-service-create-secret-variant/index.html) [SetSecretVariantPOST/depot.ci.v3beta2.SecretService/SetSecretVariant](/content/docs/api/ci/reference#secret-service-set-secret-variant/index.html) [UpdateSecretVariantMetadataPOST/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata](/content/docs/api/ci/reference#secret-service-update-secret-variant-metadata/index.html) [UpdateSecretVariantValuePOST/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue](/content/docs/api/ci/reference#secret-service-update-secret-variant-value/index.html) [DeleteSecretVariantPOST/depot.ci.v3beta2.SecretService/DeleteSecretVariant](/content/docs/api/ci/reference#secret-service-delete-secret-variant/index.html) [DeleteSecretPOST/depot.ci.v3beta2.SecretService/DeleteSecret](/content/docs/api/ci/reference#secret-service-delete-secret/index.html) ### ListSecretsSecretService.ListSecrets ### Parameters `page`PageRequest +Show child parameters `page`integer 1-based page number. Defaults to 1. `pageSize`integer Number of parent resources per page. `query`string Optional name search/prefix/filter depending on product behavior. `attributes`Attribute\[\] Optional filter for variants matching these attributes. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `context`Attribute\[\] Optional job context for variants that could apply to a workflow run. Variants without a context key match all values for that key. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `secrets`Secret\[\] +Show child parameters `id`string `name`string `variants`SecretVariant\[\] +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Server-computed for list requests with context. Describes whether this variant is the definite winner, could still win with more context, or is lower priority than another candidate. Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Deprecated: use SecretVariant.resolution for per-row resolution details. Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `page`PageResponse +Show child parameters `page`integer `pageSize`integer `hasMore`boolean POST`/depot.ci.v3beta2.SecretService/ListSecrets` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/ListSecrets \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "page": {8 "page": 1,9 "pageSize": 110 },11 "query": "query_example",12 "attributes": [13 {14 "key": "key_example",15 "value": "value_example"16 }17 ],18 "context": [19 {20 "key": "key_example",21 "value": "value_example"22 }23 ]24}25JSON ``` Response ``` { "secrets": [ { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" } ], "page": { "page": 1, "pageSize": 1, "hasMore": false }} ``` ### ListSecretAttributesSecretService.ListSecretAttributes ### Parameters This method does not require request parameters. ### Returns `attributes`AttributeLinkCount\[\] +Show child parameters `attribute`Attribute +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `linkCount`integer Number of variants linked to this attribute. POST`/depot.ci.v3beta2.SecretService/ListSecretAttributes` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/ListSecretAttributes \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{}7JSON ``` Response ``` { "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]} ``` ### GetSecretSecretService.GetSecret ### Parameters idobject `id`stringrequired nameobject `name`stringrequired ### Returns `secret`Secret +Show child parameters `id`string `name`string `variants`SecretVariant\[\] +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Deprecated: use SecretVariant.resolution for per-row resolution details. Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` POST`/depot.ci.v3beta2.SecretService/GetSecret` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/GetSecret \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` { "secret": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }} ``` ### GetSecretVariantSecretService.GetSecretVariant ### Parameters `id`stringrequired ### Returns `variant`SecretVariant +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` POST`/depot.ci.v3beta2.SecretService/GetSecretVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/GetSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` { "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }} ``` ### CreateSecretVariantSecretService.CreateSecretVariant ### Parameters `secretName`stringrequired `variantName`string Name of the variant to create. Leave empty to name it after its `attributes`: after the repository for a `repository` attribute, or "default" with no attributes, suffixed "-2", "-3", and so on when that name is taken. For example, a variant for "acme/api" is named "acme-api". Fails when a variant with exactly these `attributes` already exists. `value`stringrequired `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. Empty attributes means the variant is available everywhere. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `secret`Secret +Show child parameters `id`string `name`string `variants`SecretVariant\[\] +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Deprecated: use SecretVariant.resolution for per-row resolution details. Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variant`SecretVariant +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `createdSecret`boolean `createdVariant`boolean POST`/depot.ci.v3beta2.SecretService/CreateSecretVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/CreateSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "secretName": "secretName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON ``` Response ``` { "secret": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ "attributes_example" ], "lastModified": "2026-05-18T18:00:00Z" } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "secretId": "secret_123", "name": "name_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ], "lastModified": "2026-05-18T18:00:00Z" }, "createdSecret": false, "createdVariant": false} ``` ### SetSecretVariantSecretService.SetSecretVariant ### Parameters `secretName`stringrequired `variantName`string Name of the variant to write. Leave empty, or pass "default", to write the variant whose `attributes` match exactly, or else create one named after them: after the repository for a `repository` attribute, or "default" with no attributes, suffixed "-2", "-3", and so on when that name is taken. For example, a new variant for "acme/api" is named "acme-api". `value`stringrequired `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. Empty attributes means the variant is available everywhere. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `secret`Secret +Show child parameters `id`string `name`string `variants`SecretVariant\[\] +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Deprecated: use SecretVariant.resolution for per-row resolution details. Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variant`SecretVariant +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `createdSecret`boolean `createdVariant`boolean POST`/depot.ci.v3beta2.SecretService/SetSecretVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/SetSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "secretName": "secretName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON ``` Response ### UpdateSecretVariantMetadataSecretService.UpdateSecretVariantMetadata ### Parameters `variantId`stringrequired `name`stringrequired Allows renaming a variant, e.g. default -> production. `description`string `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `variant`SecretVariant +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` POST`/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/UpdateSecretVariantMetadata \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "name": "name_example",9 "description": "description_example",10 "attributes": [11 {12 "key": "key_example",13 "value": "value_example"14 }15 ]16}17JSON ``` Response ### UpdateSecretVariantValueSecretService.UpdateSecretVariantValue ### Parameters `variantId`stringrequired `value`stringrequired ### Returns `variant`SecretVariant +Show child parameters `id`string `secretId`string `name`string `description`string \| null `attributes`Attribute\[\] Attributes describe the job context this variant matches against. A variant with no attributes matches all jobs. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `valueGroupIndex`integer \| null Deprecated: value group indicators are no longer displayed. `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` POST`/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/UpdateSecretVariantValue \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "value": "value_example"9}10JSON ``` Response ### DeleteSecretVariantSecretService.DeleteSecretVariant ### Parameters `variantId`stringrequired ### Returns `deletedSecret`boolean POST`/depot.ci.v3beta2.SecretService/DeleteSecretVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/DeleteSecretVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123"8}9JSON ``` Response ``` { "deletedSecret": false} ``` ### DeleteSecretSecretService.DeleteSecret ### Parameters idobject `id`stringrequired nameobject `name`stringrequired ### Returns This method does not document a success response. POST`/depot.ci.v3beta2.SecretService/DeleteSecret` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.SecretService/DeleteSecret \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` {} ``` ## Variables List and manage CI variables and their variants. [ListVariablesPOST/depot.ci.v3beta2.VariableService/ListVariables](/content/docs/api/ci/reference#variable-service-list-variables/index.html) [ListVariableAttributesPOST/depot.ci.v3beta2.VariableService/ListVariableAttributes](/content/docs/api/ci/reference#variable-service-list-variable-attributes/index.html) [GetVariablePOST/depot.ci.v3beta2.VariableService/GetVariable](/content/docs/api/ci/reference#variable-service-get-variable/index.html) [GetVariableVariantPOST/depot.ci.v3beta2.VariableService/GetVariableVariant](/content/docs/api/ci/reference#variable-service-get-variable-variant/index.html) [CreateVariableVariantPOST/depot.ci.v3beta2.VariableService/CreateVariableVariant](/content/docs/api/ci/reference#variable-service-create-variable-variant/index.html) [SetVariableVariantPOST/depot.ci.v3beta2.VariableService/SetVariableVariant](/content/docs/api/ci/reference#variable-service-set-variable-variant/index.html) [UpdateVariableVariantMetadataPOST/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata](/content/docs/api/ci/reference#variable-service-update-variable-variant-metadata/index.html) [UpdateVariableVariantValuePOST/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue](/content/docs/api/ci/reference#variable-service-update-variable-variant-value/index.html) [DeleteVariableVariantPOST/depot.ci.v3beta2.VariableService/DeleteVariableVariant](/content/docs/api/ci/reference#variable-service-delete-variable-variant/index.html) [DeleteVariablePOST/depot.ci.v3beta2.VariableService/DeleteVariable](/content/docs/api/ci/reference#variable-service-delete-variable/index.html) ### ListVariablesVariableService.ListVariables ### Parameters `page`PageRequest +Show child parameters `page`integer 1-based page number. Defaults to 1. `pageSize`integer Number of parent resources per page. `query`string `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `context`Attribute\[\] Optional job context for variants that could apply to a workflow run. Variants without a context key match all values for that key. +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `variables`Variable\[\] +Show child parameters `id`string `name`string `variants`VariableVariant\[\] +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] `lastModified`oneOf `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `page`PageResponse +Show child parameters `page`integer `pageSize`integer `hasMore`boolean POST`/depot.ci.v3beta2.VariableService/ListVariables` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/ListVariables \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "page": {8 "page": 1,9 "pageSize": 110 },11 "query": "query_example",12 "attributes": [13 {14 "key": "key_example",15 "value": "value_example"16 }17 ],18 "context": [19 {20 "key": "key_example",21 "value": "value_example"22 }23 ]24}25JSON ``` Response ``` { "variables": [ { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" } ], "page": { "page": 1, "pageSize": 1, "hasMore": false }} ``` ### ListVariableAttributesVariableService.ListVariableAttributes ### Parameters This method does not require request parameters. ### Returns `attributes`AttributeLinkCount\[\] +Show child parameters `attribute`Attribute +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `linkCount`integer Number of variants linked to this attribute. POST`/depot.ci.v3beta2.VariableService/ListVariableAttributes` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/ListVariableAttributes \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{}7JSON ``` Response ``` { "attributes": [ { "attribute": { "key": "key_example", "value": "value_example" }, "linkCount": 1 } ]} ``` ### GetVariableVariableService.GetVariable ### Parameters idobject `id`stringrequired nameobject `name`stringrequired ### Returns `variable`Variable +Show child parameters `id`string `name`string `variants`VariableVariant\[\] +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] `lastModified`oneOf `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` POST`/depot.ci.v3beta2.VariableService/GetVariable` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/GetVariable \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` { "variable": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }} ``` ### GetVariableVariantVariableService.GetVariableVariant ### Parameters `id`stringrequired ### Returns `variant`VariableVariant +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf POST`/depot.ci.v3beta2.VariableService/GetVariableVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/GetVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` { "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }} ``` ### CreateVariableVariantVariableService.CreateVariableVariant ### Parameters `variableName`stringrequired `variantName`string `value`stringrequired `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `variable`Variable +Show child parameters `id`string `name`string `variants`VariableVariant\[\] +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] `lastModified`oneOf `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variant`VariableVariant +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `createdVariable`boolean `createdVariant`boolean POST`/depot.ci.v3beta2.VariableService/CreateVariableVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/CreateVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variableName": "variableName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON ``` Response ``` { "variable": { "id": "id_123", "name": "name_example", "variants": [ { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ "attributes_example" ] } ], "variantCount": 1, "lastModified": "2026-05-18T18:00:00Z", "resolution": "VARIANT_RESOLUTION_UNSPECIFIED" }, "variant": { "id": "id_123", "variableId": "variable_123", "name": "name_example", "value": "value_example", "description": "description_example", "attributes": [ { "key": "key_example", "value": "value_example" } ] }, "createdVariable": false, "createdVariant": false} ``` ### SetVariableVariantVariableService.SetVariableVariant ### Parameters `variableName`stringrequired `variantName`string `value`stringrequired `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `variable`Variable +Show child parameters `id`string `name`string `variants`VariableVariant\[\] +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] `lastModified`oneOf `variantCount`integer `lastModified`oneOf `resolution`VariantResolution Possible enum values `VARIANT_RESOLUTION_UNSPECIFIED``VARIANT_RESOLUTION_RESOLVED``VARIANT_RESOLUTION_INDETERMINATE``VARIANT_RESOLUTION_LOWER_PRIORITY` `variant`VariableVariant +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf `createdVariable`boolean `createdVariant`boolean POST`/depot.ci.v3beta2.VariableService/SetVariableVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/SetVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variableName": "variableName_example",8 "variantName": "variantName_example",9 "value": "value_example",10 "description": "description_example",11 "attributes": [12 {13 "key": "key_example",14 "value": "value_example"15 }16 ]17}18JSON ``` Response ### UpdateVariableVariantMetadataVariableService.UpdateVariableVariantMetadata ### Parameters `variantId`stringrequired `name`stringrequired `description`string `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. ### Returns `variant`VariableVariant +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf POST`/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/UpdateVariableVariantMetadata \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "name": "name_example",9 "description": "description_example",10 "attributes": [11 {12 "key": "key_example",13 "value": "value_example"14 }15 ]16}17JSON ``` Response ### UpdateVariableVariantValueVariableService.UpdateVariableVariantValue ### Parameters `variantId`stringrequired `value`stringrequired ### Returns `variant`VariableVariant +Show child parameters `id`string `variableId`string `name`string `value`string `description`string \| null `attributes`Attribute\[\] +Show child parameters `key`stringrequired Attribute dimension. Can be "repository", "environment", "branch", or "workflow". `value`stringrequired Exact value or pattern, depending on `key`. `lastModified`oneOf POST`/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/UpdateVariableVariantValue \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123",8 "value": "value_example"9}10JSON ``` Response ### DeleteVariableVariantVariableService.DeleteVariableVariant ### Parameters `variantId`stringrequired ### Returns `deletedVariable`boolean POST`/depot.ci.v3beta2.VariableService/DeleteVariableVariant` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/DeleteVariableVariant \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "variantId": "variant_123"8}9JSON ``` Response ``` { "deletedVariable": false} ``` ### DeleteVariableVariableService.DeleteVariable ### Parameters idobject `id`stringrequired nameobject `name`stringrequired ### Returns This method does not document a success response. POST`/depot.ci.v3beta2.VariableService/DeleteVariable` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v3beta2.VariableService/DeleteVariable \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "id": "id_123"8}9JSON ``` Response ``` {} ``` ## Diagnostics Fetch deterministic failure diagnosis for CI resources. [GetFailureDiagnosisPOST/depot.ci.v1.CIService/GetFailureDiagnosis](/content/docs/api/ci/reference#ci-service-get-failure-diagnosis/index.html) ### GetFailureDiagnosisCIService.GetFailureDiagnosis Returns a failure diagnosis for a run, workflow, job, or attempt. For run and workflow targets, identical failures are grouped together by error fingerprint. For job and attempt targets, the response is a focused diagnosis of that single job or attempt. When too many jobs failed to diagnose individually, the response is a per-workflow and per-job breakdown instead. When no failure evidence is found, the response is empty. The response is limited to a fixed size and reflects the run's current state. The diagnosis can change while a run is in progress. As more jobs fail, a later call can surface new failures or turn an empty result into a grouped one. As job summaries become available, a later call can also add summary drill-down commands. ### Parameters `targetId`stringrequired Unique identifier for the resource to diagnose: a CI run, workflow, job, or attempt. Must match `targetType`. `targetType`FailureDiagnosisTargetTyperequired Resource type for `targetId`: run, workflow, job, or attempt. Possible enum values `FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED``FAILURE_DIAGNOSIS_TARGET_TYPE_RUN``FAILURE_DIAGNOSIS_TARGET_TYPE_WORKFLOW``FAILURE_DIAGNOSIS_TARGET_TYPE_JOB``FAILURE_DIAGNOSIS_TARGET_TYPE_ATTEMPT` ### Returns `orgId`string Depot organization that owns the diagnosed resource. `target`FailureDiagnosisTarget The resource the diagnosis was requested for: run, workflow, job, or attempt. +Show child parameters `targetId`string Unique identifier for the diagnosed resource. `targetType`FailureDiagnosisTargetType Resource type for `targetId`: run, workflow, job, or attempt. Possible enum values `status`FailureDiagnosisResourceStatus Current state of the target resource. Possible enum values `FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_QUEUED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_WAITING``FAILURE_DIAGNOSIS_RESOURCE_STATUS_RUNNING``FAILURE_DIAGNOSIS_RESOURCE_STATUS_FINISHED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_FAILED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_CANCELLED``FAILURE_DIAGNOSIS_RESOURCE_STATUS_SKIPPED` `context`FailureDiagnosisContext Resolved parent context for the target, with identifiers, statuses, and conclusions. +Show child parameters `runId`string Unique identifier for the parent CI run. `repo`string GitHub repository in `owner/name` format. For example, "depot/cli". `ref`string Git ref the run was triggered against. Empty when the trigger carries no ref. `sha`string Commit SHA the run executes against. Empty for open pull\_request runs. `headSha`string Source commit SHA for pull\_request and merge\_group triggers. Empty for triggers that don't carry a head SHA. `trigger`string `runStatus`FailureDiagnosisResourceStatus Current state of the parent run. Possible enum values `workflowId`string Unique identifier for the parent workflow. Empty when the target is a run. `workflowName`string Parent workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string Parent workflow file path. For example, ".depot/workflows/ci.yml". Empty when the workflow YAML was passed via `workflowContent` in the [`Run`](/content/docs/api/ci/reference#ci-service-run/index.html) request, or when the target is a run. `workflowStatus`FailureDiagnosisResourceStatus Current state of the parent workflow. Possible enum values `jobId`string Unique identifier for the parent job. Empty when the target is a run or workflow. `jobKey`string Parent job key from the workflow. Empty when the target is a run or workflow. `jobDisplayName`string Human-readable display name for the parent job. Falls back to `jobKey` when no display name is set. `jobStatus`FailureDiagnosisResourceStatus Current state of the parent job. Possible enum values `jobConclusion`FailureDiagnosisConclusion Conclusion of the parent job. Unspecified until the job concludes. Possible enum values `FAILURE_DIAGNOSIS_CONCLUSION_UNSPECIFIED``FAILURE_DIAGNOSIS_CONCLUSION_SUCCESS``FAILURE_DIAGNOSIS_CONCLUSION_FAILURE``FAILURE_DIAGNOSIS_CONCLUSION_CANCELLED``FAILURE_DIAGNOSIS_CONCLUSION_SKIPPED``FAILURE_DIAGNOSIS_CONCLUSION_TIMED_OUT` `attemptId`string Unique identifier for the parent attempt. Empty unless the target is an attempt. `attempt`integer Attempt number for the parent attempt. Zero unless the target is an attempt. `attemptStatus`FailureDiagnosisResourceStatus Current state of the parent attempt. Possible enum values `attemptConclusion`FailureDiagnosisConclusion Conclusion of the parent attempt. Unspecified until the attempt concludes. Possible enum values `truncatedContextFields`string\[\] Names of context fields that were truncated to fit the response limits. `state`FailureDiagnosisState Overall diagnosis state. - EMPTY: No failure evidence found. `failureGroups` and `representativeAttempts` are empty. - GROUPED\_FAILURES: Failures grouped by fingerprint into `failureGroups`. Returned for run and workflow targets. - FOCUSED\_FAILURE: Diagnosis focuses on a single job or attempt. Returned for job and attempt targets. - OVER\_LIMIT: Too many failed candidates to diagnose individually. `overLimitBreakdown` lists per-workflow and per-job counts instead. Possible enum values `FAILURE_DIAGNOSIS_STATE_UNSPECIFIED``FAILURE_DIAGNOSIS_STATE_EMPTY``FAILURE_DIAGNOSIS_STATE_GROUPED_FAILURES``FAILURE_DIAGNOSIS_STATE_FOCUSED_FAILURE``FAILURE_DIAGNOSIS_STATE_OVER_LIMIT` `emptyReason`FailureDiagnosisEmptyReason Reason the diagnosis is empty. Set only when `state` is EMPTY. Possible enum values `FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED``FAILURE_DIAGNOSIS_EMPTY_REASON_NO_FAILURE_EVIDENCE` `failureGroups`FailureGroup\[\] Failures grouped by deterministic error fingerprint. Empty when `state` is EMPTY or OVER\_LIMIT. +Show child parameters `fingerprint`string Identifier for this failure group, computed from the error text. Two failures share a fingerprint when their errors match after variable details like timestamps, IDs, and file paths are removed, so the same logical error from different attempts falls into the same group. `source`string Origin of the error text used to form the fingerprint. Can be "attempt\_error", "job\_error", "workflow\_error", or "status". `count`integer Number of candidate attempts that fell into this group. `errorMessage`string Representative error message for the group, possibly truncated. `errorMessageTruncated`boolean True when `errorMessage` was truncated to fit the response limit. `errorMessageOriginalLength`integer Length of the full `errorMessage`, in characters, before any truncation. `diagnosis`string AI-generated diagnosis summarizing the failure. Empty when no diagnosis is available. `possibleFix`string AI-generated suggested fix. Empty when no suggestion is available. `representatives`RepresentativeAttempt\[\] Attempts chosen as samples of the group's failure, up to `bounds.representativesPerGroupLimit` entries. Each job's current attempt is preferred, then more recent attempts. +Show child parameters `runId`string Unique identifier for the parent CI run. `workflowId`string Unique identifier for the parent workflow. `workflowName`string Parent workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string `jobId`string Unique identifier for the parent job. `jobKey`string Parent job key from the workflow. `jobDisplayName`string Human-readable display name for the parent job. Falls back to `jobKey` when no display name is set. `jobStatus`FailureDiagnosisResourceStatus Current state of the parent job. Possible enum values `jobConclusion`FailureDiagnosisConclusion Conclusion of the parent job. Unspecified until the job concludes. Possible enum values `attemptId`string Unique identifier for this attempt. `attempt`integer Attempt number, starting at 1 for the first run. `attemptStatus`FailureDiagnosisResourceStatus Current state of the attempt. Possible enum values `attemptConclusion`FailureDiagnosisConclusion Conclusion of the attempt. Unspecified until the attempt concludes. Possible enum values `errorMessage`string Error message captured for this attempt, possibly truncated. `errorMessageTruncated`boolean True when `errorMessage` was truncated to fit the response limit. `errorMessageOriginalLength`integer Length of the full `errorMessage`, in characters, before any truncation. `diagnosis`string AI-generated diagnosis for this attempt. Empty when no diagnosis is available. `possibleFix`string AI-generated suggested fix for this attempt. Empty when no suggestion is available. `relevantLines`RelevantErrorLine\[\] AI-selected log lines correlated with the failure. Empty when no log analysis is available. `nextCommands`DrillDownCommand\[\] Drill-down commands suggested for this attempt. For example, "depot ci logs" or "depot ci summary". `omittedRepresentativeCount`integer Number of additional candidate attempts omitted from representatives. `representativeAttempts`RepresentativeAttempt\[\] Representative attempts from all failure groups in one list. Contains the same entries as the nested `failureGroups[].representatives` lists. Empty when `state` is EMPTY or OVER\_LIMIT. +Show child parameters `runId`string Unique identifier for the parent CI run. `workflowId`string Unique identifier for the parent workflow. `workflowName`string Parent workflow name from the YAML `name:` key. Falls back to the file path stem when the workflow doesn't set `name:`. Empty when neither is available. `workflowPath`string `jobId`string Unique identifier for the parent job. `jobKey`string Parent job key from the workflow. `jobDisplayName`string Human-readable display name for the parent job. Falls back to `jobKey` when no display name is set. `jobStatus`FailureDiagnosisResourceStatus Current state of the parent job. Possible enum values `jobConclusion`FailureDiagnosisConclusion Conclusion of the parent job. Unspecified until the job concludes. Possible enum values `attemptId`string Unique identifier for this attempt. `attempt`integer Attempt number, starting at 1 for the first run. `attemptStatus`FailureDiagnosisResourceStatus Current state of the attempt. Possible enum values `attemptConclusion`FailureDiagnosisConclusion Conclusion of the attempt. Unspecified until the attempt concludes. Possible enum values `errorMessage`string Error message captured for this attempt, possibly truncated. `errorMessageTruncated`boolean True when `errorMessage` was truncated to fit the response limit. `errorMessageOriginalLength`integer Length of the full `errorMessage`, in characters, before any truncation. `diagnosis`string AI-generated diagnosis for this attempt. Empty when no diagnosis is available. `possibleFix`string AI-generated suggested fix for this attempt. Empty when no suggestion is available. `relevantLines`RelevantErrorLine\[\] AI-selected log lines correlated with the failure. Empty when no log analysis is available. +Show child parameters `stepId`string Workflow step identifier the line was emitted from. Empty when not associated with a step. `lineNumber`integer Persisted line number within the emitting stream. `content`string Log line content, possibly truncated. `contentTruncated`boolean True when `content` was truncated to fit the per-line limit. `contentOriginalLength`integer Length of the full `content`, in characters, before any truncation. `nextCommands`DrillDownCommand\[\] Drill-down commands suggested for this attempt. For example, "depot ci logs" or "depot ci summary". +Show child parameters `kind`DrillDownCommandKind Kind of drill-down command. - LOGS: Equivalent to `depot ci logs `. - SUMMARY: Equivalent to `depot ci summary `. - DIAGNOSE\_WORKFLOW: Equivalent to `depot ci diagnose --workflow `. - DIAGNOSE\_JOB: Equivalent to `depot ci diagnose --job `. Possible enum values `DRILL_DOWN_COMMAND_KIND_UNSPECIFIED``DRILL_DOWN_COMMAND_KIND_LOGS``DRILL_DOWN_COMMAND_KIND_SUMMARY``DRILL_DOWN_COMMAND_KIND_DIAGNOSE_WORKFLOW``DRILL_DOWN_COMMAND_KIND_DIAGNOSE_JOB` `argv`string\[\] Suggested command and arguments. For example, \["depot", "ci", "logs", ""\]. `targetId`string Unique identifier for the resource the command targets. `label`string Human-readable label for the command. For example, "Logs" or "Diagnose workflow". `bounds`FailureDiagnosisBounds Limits and counts that describe how the diagnosis was bounded or truncated. +Show child parameters `failedProblemCandidateCount`integer Number of failed problem candidates, the failed and cancelled jobs the diagnosis examined. `failedProblemCandidateCap`integer Maximum number of failed problem candidates the diagnosis examines. Above this limit the response switches to the over-limit breakdown. `totalProblemJobCount`integer Total number of jobs identified as problem candidates. `skippedDependentCount`integer Number of jobs skipped because a failed dependency prevented them from running. `totalFailureGroupCount`integer Total number of distinct failure groups identified. `omittedFailureGroupCount`integer Number of omitted failure groups. `failureGroupLimit`integer Maximum number of failure groups returned in a single response. 0 means no group limit. `representativesPerGroupLimit`integer Maximum number of representative attempts returned per failure group. `recentAttemptLimit`integer Maximum number of recent attempts considered for focused diagnoses. `totalAttemptCount`integer Total number of attempts examined for the target. Populated for focused job diagnoses. `omittedAttemptCount`integer Number of attempts omitted because the response exceeded the recent attempt limit. `relevantLineLimit`integer Maximum number of relevant log lines returned per representative attempt. `errorLineBodyCharLimit`integer Character cap applied to each relevant log line body. `errorMessageCharLimit`integer Character cap applied to errorMessage values in the response. `contextLabelCharLimit`integer Character cap applied to context label strings such as repo, ref, and workflowName. `overLimitWorkflowBreakdownLimit`integer Maximum number of workflow breakdown rows returned in an over-limit response. `overLimitJobBreakdownLimit`integer Maximum number of job breakdown rows returned in an over-limit response. `omittedWorkflowBreakdownCount`integer Number of workflow breakdown rows omitted because they exceeded the limit. `omittedJobBreakdownCount`integer Number of job breakdown rows omitted because they exceeded the limit. `truncated`boolean True when any part of the response was truncated to fit the limits above. `nextCommands`DrillDownCommand\[\] Drill-down commands from all representative attempts in one list. For example, "depot ci logs" or "depot ci diagnose". Contains the same entries as the nested `representativeAttempts[].nextCommands` lists. In an OVER\_LIMIT response, contains the diagnose commands from `overLimitBreakdown[].nextCommands` instead. Empty when `state` is EMPTY. +Show child parameters `kind`DrillDownCommandKind Kind of drill-down command. Possible enum values `argv`string\[\] Suggested command and arguments. For example, \["depot", "ci", "logs", ""\]. `targetId`string Unique identifier for the resource the command targets. `label`string Human-readable label for the command. For example, "Logs" or "Diagnose workflow". `commandCapabilities`FailureDiagnosisCommandCapabilities Availability flags for the suggested drill-down commands. Clients should hide commands whose flag is false. Unset means all commands are available. +Show child parameters `summaryCommandAvailable`boolean True when the summary drill-down command is available for this diagnosis. `overLimitBreakdown`FailureDiagnosisBreakdownRow\[\] Failure counts by workflow and by job, returned when failed problem candidates exceed `bounds.failedProblemCandidateCap`. Empty for other states. +Show child parameters `targetType`FailureDiagnosisTargetType Resource type for `targetId`: workflow or job. Possible enum values `targetId`string Unique identifier for the resource this row describes. `label`string Human-readable label for the resource. For example, a workflow name or job key. `status`FailureDiagnosisResourceStatus Current state of the resource. Possible enum values `failedProblemCandidateCount`integer Number of failed problem candidates attributed to this resource. `nextCommands`DrillDownCommand\[\] Drill-down commands suggested for this resource. +Show child parameters `kind`DrillDownCommandKind Kind of drill-down command. Possible enum values `argv`string\[\] Suggested command and arguments. For example, \["depot", "ci", "logs", ""\]. `targetId`string Unique identifier for the resource the command targets. `label`string Human-readable label for the command. For example, "Logs" or "Diagnose workflow". POST`/depot.ci.v1.CIService/GetFailureDiagnosis` cURLNode.jsGo ``` 1curl -X POST https://api.depot.dev/depot.ci.v1.CIService/GetFailureDiagnosis \2 -H "Authorization: Bearer $DEPOT_TOKEN" \3 -H "Content-Type: application/json" \4 -H "Connect-Protocol-Version: 1" \5 --json @- <<'JSON'6{7 "targetId": "target_123",8 "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED"9}10JSON ``` Response ``` { "orgId": "org_123", "target": { "targetId": "target_123", "targetType": "FAILURE_DIAGNOSIS_TARGET_TYPE_UNSPECIFIED", "status": "FAILURE_DIAGNOSIS_RESOURCE_STATUS_UNSPECIFIED" }, "context": { "runId": "run_123", "repo": "repo_example", "ref": "ref_example", "sha": "b2f5ff47436671b6e533d8dc3614845d", "headSha": "b2f5ff47436671b6e533d8dc3614845d", "trigger": "trigger_example" }, "state": "FAILURE_DIAGNOSIS_STATE_UNSPECIFIED", "emptyReason": "FAILURE_DIAGNOSIS_EMPTY_REASON_UNSPECIFIED", "failureGroups": [ { "fingerprint": "fingerprint_example", "source": "source_example", "count": 1, "errorMessage": "errorMessage_example", "errorMessageTruncated": false, "errorMessageOriginalLength": 1 } ], "representativeAttempts": [ { "runId": "run_123", "workflowId": "workflow_123", "workflowName": "workflowName_example", "workflowPath": "workflowPath_example", "jobId": "job_123", "jobKey": "jobKey_example" } ], "bounds": { "failedProblemCandidateCount": 1, "failedProblemCandidateCap": 1, "totalProblemJobCount": 1, "skippedDependentCount": 1, "totalFailureGroupCount": 1, "omittedFailureGroupCount": 1 }} ``` ## Errors Every method returns errors as a Connect error object with a string `code`, a developer-facing `message`, and optional `details`. The status code maps to an HTTP status for callers using the JSON over HTTP transport. The following codes may be returned by the Depot CI API. Code HTTP When it happens Common causes `unauthenticated`gRPC 16 401 The request has no valid token. Missing Authorization header, a non-Bearer scheme, or an invalid or expired token. `permission_denied`gRPC 7 403 The token is valid but not allowed for this resource or action. Wrong token type, the caller is not a member of the organization, a missing x-depot-org header on an organization token, or the organization has no GitHub Code Connection. `invalid_argument`gRPC 3 400 A request field is missing or malformed. A repo not in owner/name format, a missing run, workflow, or artifact identifier, an invalid page token, a non-numeric pr, a malformed sha, or an unsupported target\_type or log format. `not_found`gRPC 5 404 The referenced resource does not exist or is not visible to the caller. An unknown run, workflow, job, attempt, or artifact identifier, or a workflow that has no workflow\_dispatch trigger. `failed_precondition`gRPC 9 412 The resource exists but is not in a valid state for the action. Cancelling a run, workflow, or job that is not queued or running, retrying before a workflow finishes, or a status that changed mid-request. `resource_exhausted`gRPC 8 429 A limit was reached. Too many concurrent log streams for the token, organization, or attempt, a log stream or export that exceeded its maximum duration, or a metrics result that is too large. `unavailable`gRPC 14 503 A dependency is temporarily down. The request can be retried. The log or metrics store is unavailable, or a transient read failure occurred. `internal`gRPC 13 500 An unexpected server-side failure occurred. A download URL could not be generated, a trigger config failed to parse, or a database write failed. Ask AI StripeM-Inner