API
Pipelines
Workflows, runs, logs, artifacts, environments, secrets, and the endpoints runners call.
See Pipelines. Runners call /v1/runner with their job's token (Authorization: Bearer sjt_…), which works only while that job is queued or running.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/runner/job | The job's plan: steps, contexts and its secrets. The job counts as running from here. |
POST /v1/runner/checkout | A git credential for the run's repository, minutes long. |
POST /v1/runner/status | Step progress and a heartbeat; answers whether to stop. |
POST /v1/runner/complete | The job's result. |
POST /v1/runner/logs | Self-hosted runners' output, in batches of timestamped lines. |
POST /v1/runner/cache/restore | Finds a cache for key (exact) or restoreKeys (prefixes, newest first) with the same version, in the job's ref, a pull request's target, then the default branch. Answers hit (exact, partial, none) and a presigned download. |
POST /v1/runner/cache/save | A presigned upload for a cache in the job's own ref only (key, version, size), or exists when that key is already saved there (caches are immutable). |
POST /v1/runner/cache/commit | Finishes a cache after its upload; the repository's oldest unused caches go when it passes its quota. |
POST /v1/runner/artifacts/upload | Starts an artifact of the job's run (name, size, files, retentionDays): a presigned PUT for exactly that size. Names are unique per run attempt. |
POST /v1/runner/artifacts/commit | Finishes an artifact after its upload; it's then listed with the run and kept until its retention ends. |
POST /v1/runner/artifacts/download | Presigned downloads of the run's artifacts (name for one; this attempt's first, then earlier attempts'). |
GET /v1/orgs/:orgId/repos/:name/pipelines/workflows | The workflows of a branch (default: the default branch), with their problems and last run. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/workflows/:file | Turns a workflow on or off (off: no event starts it). |
POST /v1/orgs/:orgId/repos/:name/pipelines/workflows/:file/dispatches | Runs a workflow by hand on a branch with inputs (workflow_dispatch). |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs | Runs, newest first, filtered by workflow, branch, status, actor and event. |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs/:number | A run (an attempt of it): jobs with steps, the job graph, approvals, artifacts. |
POST /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/cancel | Cancels a run: queued and waiting jobs end at once, running ones are stopped. Needs git:write. |
POST /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/rerun | Re-runs a finished run as a new attempt: all jobs, the failed ones, or one job (and what needs it). |
POST /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/approvals | Approves or rejects the jobs of the current attempt waiting for an environment (its reviewers only). |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/jobs/:jobId | One job of a run: status, runner, environment, steps, annotations, summary and error. |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/jobs/:jobId/logs | A page of a job's log after cursor; done when the job finished and everything was read. |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/jobs/:jobId/logs/raw | The whole log as text (up to 5 MB). |
GET /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/artifacts/:artifact | A download link for one of the run's artifacts (15 minutes); attempt picks an earlier attempt's. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/runs/:number/artifacts/:artifact | Deletes an artifact of the run now. Needs git:admin. |
GET /v1/orgs/:orgId/repos/:name/pipelines/statuses | What the runs of commits add up to (up to 100: ?sha=…&sha=…). |
GET /v1/orgs/:orgId/repos/:name/pipelines/environments | Environments with their rules, and the names of their secrets and variables. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment | Creates or changes an environment's rules: reviewers (up to 6 people or groups; empty means no approval), preventSelfReview, waitMinutes, branchPolicy (all, protected or selected with branchPatterns). Needs git:admin. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment | Removes an environment with its secrets and variables. Needs git:admin. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment/secrets/:secret | Sets an environment secret (value, at most the platform's size). Only that environment's jobs get it, after its rules pass. Needs git:admin. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment/secrets/:secret | Removes an environment secret. Needs git:admin. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment/variables/:variable | Sets an environment variable (value). Needs git:admin. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/environments/:environment/variables/:variable | Removes an environment variable. Needs git:admin. |
GET /v1/orgs/:orgId/repos/:name/pipelines/secrets | Secret names (never values): the repository's, and the org's visible to it. Needs git:write. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/secrets/:secret | Sets a repository secret (value): KMS-encrypted, never returned, handed only to running jobs. Needs git:admin. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/secrets/:secret | Removes a repository secret. Needs git:admin. |
GET /v1/orgs/:orgId/repos/:name/pipelines/variables | Variables (values are visible): the repository's and the org's visible to it. |
PUT /v1/orgs/:orgId/repos/:name/pipelines/variables/:variable | Sets a repository variable (value, readable in vars). Needs git:admin. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/variables/:variable | Removes a repository variable. Needs git:admin. |
GET /v1/orgs/:orgId/repos/:name/pipelines/caches | The repository's caches: key, ref, size and when each was last used. |
DELETE /v1/orgs/:orgId/repos/:name/pipelines/caches | Removes caches: one key (on one ref, or every ref), or all of them. |
GET /v1/orgs/:orgId/pipelines/secrets | Org secret names and which repositories see them (never values). |
PUT /v1/orgs/:orgId/pipelines/secrets/:secret | Sets an organization secret: value (required for a new one), and visibility (all repositories, or selected with repoIds). Needs git:admin. |
DELETE /v1/orgs/:orgId/pipelines/secrets/:secret | Removes an organization secret. Needs git:admin. |
GET /v1/orgs/:orgId/pipelines/variables | Organization variables with their values and which repositories see them. |
PUT /v1/orgs/:orgId/pipelines/variables/:variable | Sets an organization variable: value, visibility and repoIds as for secrets. Needs git:admin. |
DELETE /v1/orgs/:orgId/pipelines/variables/:variable | Removes an organization variable. Needs git:admin. |
GET /v1/orgs/:orgId/pipelines/usage | Minutes this month (or month=2026-10) against the plan, by runner type. |
GET /v1/orgs/:orgId/pipelines/runners | Hosted runner types the org can use, and its self-hosted runners (devices approved for pipelines). |
PUT /v1/orgs/:orgId/pipelines/runners/:deviceId/labels | A self-hosted runner's own labels (runs-on: [self-hosted, <label>]). |