Lists repositories. By default the ones the authenticated account can see in Woodpecker; with include_inactive it also lists repositories that exist in the forge but were never activated, which is where the forge_remote_id for activate_repository comes from. scope="instance" lists every repository on the server and needs an administrator.

Returns the full Woodpecker configuration of one repository: trusted flags, timeout, approval mode, config file path and the extension endpoints.

Resolves an "owner/name" pair to a repository id. Every other repository tool takes the numeric id, and this is how you get one. A repository that exists in the forge but was never activated in Woodpecker answers 404 — use list_repositories with include_inactive to find it.

What the authenticated account may do with this repository: pull, push and admin. Woodpecker inherits these from the forge, so this answers "why was that 403" without guessing.

Lists the branches of a repository, as Woodpecker sees them in the forge. Useful before trigger_pipeline, which fails with a bare 400 on a branch that does not exist.

Lists the open pull requests of a repository, with the index a pipeline ref like "refs/pull/42/head" refers to.

Turns on Woodpecker for a repository that exists in the forge, which installs the webhook and makes pipelines run. Takes the forge-side id, NOT an owner/name pair and not a Woodpecker id — call list_repositories with include_inactive=true and read forge_remote_id from the entry.

Changes Woodpecker settings of a repository. Only the fields you pass are touched. Note that "trusted" grants pipelines of this repository elevated container privileges and is an administrator-only change.

Re-installs the forge webhook and refreshes the stored repository data. This is the fix for "pushes no longer start a pipeline" after a repository was renamed or the Woodpecker URL changed. With scope="instance" it does that for every repository on the server, which is two-step and hits the forge API once per repository.

Tells Woodpecker that a repository moved to a different owner or name in the forge. It does NOT move anything in the forge — do that first, then call this so Woodpecker follows. Two-step. IMPORTANT on older instances: verified against 3.11, this endpoint performs the move and THEN answers HTTP 500 ("could not determine repo for permission") when the caller is an instance administrator. The move has happened — read the repository back with get_repository before deciding anything, and do not retry, which would move it a second time. Verified against 3.18, the call answers cleanly. Most of the time it is not needed at all: forges that send webhooks report a rename and Woodpecker follows it by itself, and calling this afterwards fails on a duplicate redirection.

Makes the authenticated account the repository's owner in Woodpecker. The owner's forge token is what Woodpecker uses to read the repository and report build status, so this is the fix when the previous owner left. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Removes a repository from Woodpecker: the webhook, every pipeline, all logs, secrets, registries and cron jobs of that repository. The forge repository itself is untouched. Two-step.

Lists a repository's pipelines, newest first, summarised to what a list needs. Filters are applied by the server. Note that "number" — not the pipeline id — is what every other pipeline tool takes.

Returns one pipeline with its workflows and steps, including each step id — which is what get_step_logs needs. Step state and exit_code say which step to look at.

Returns the pipeline YAML files this run was built from, as they were at that commit. This is the config that actually ran, not the one currently in the branch.

Returns the metadata Woodpecker exposes to the pipeline itself — the CI_* environment a step sees, plus the previous pipeline of the same workflow. Useful when a step behaves differently than its config suggests.

Lists the pipelines waiting in the server queue across all repositories. This is the instance-wide view: what is stuck, and behind what. get_queue_info adds the agent side of the same picture.

Starts a pipeline manually on a branch. It runs the config as it is in that branch right now, with event "manual". A branch that does not exist is rejected with a bare 400, so check list_repository_branches first. Not idempotent and there is no way to make it so — Woodpecker has no idempotency key — so a retry after a timeout starts a second pipeline. Read list_pipelines before calling again.

Runs an existing pipeline again, at the same commit and with the same config it used then. The re-run gets a new number; the original is kept. Every call is another run — a retry after a timeout starts a second one, and Woodpecker offers no idempotency key to prevent that.

Stops a pipeline that is pending or running. Its steps are killed where they are, so anything half-written stays half-written. The pipeline can be restarted afterwards.

Releases a pipeline that is waiting for approval (status "blocked") and lets it run. Read what you are approving first: pipelines are usually blocked because they come from a fork, and approving one runs code from that fork with this repository's secrets.

Refuses a pipeline that is waiting for approval. It ends as "declined" and never runs; the pipeline entry and its metadata stay.

Removes a pipeline and everything attached to it, including its logs. A running pipeline cannot be deleted — cancel it first. Two-step.

Returns the output of one pipeline step as text, newest end first by default — a failing step almost always explains itself in its last lines. The step id comes from get_pipeline (workflows[].steps[].id). Woodpecker returns these lines base64-encoded; this tool decodes and reassembles them.

Deletes the stored output of a single step. The step and the pipeline stay, their logs do not. This is what you use when a step printed a secret. Two-step. Rotate the leaked credential as well — the log was readable until now, and deleting it does not un-read it.

Deletes the stored output of every step of a pipeline. The pipeline and its step results stay, so it still shows which step failed — just not why. Two-step.

Lists the secrets at one level — repository, organization or instance-wide. Values are never returned by Woodpecker, not even here; you get names, events and image restrictions. Note that a pipeline sees all three levels, so a name missing here may still exist one level up.

Returns one secret's metadata: which events and images it applies to, and its note. The value is not part of the answer — Woodpecker strips it from every response, including the one right after creating it.

Creates a secret at the chosen level. The value is write-only: it is never readable again through the API, so store it somewhere else too. At least one event is required — the API has no defaults, and a secret without pull_request is invisible to pull-request builds.

Changes a secret. Only the fields you pass are touched — but "events" and "images" are replaced wholesale, not merged, so pass the complete list. Passing "value" rotates the secret.

Deletes a secret. Any pipeline that reads it starts failing — or worse, keeps running with an empty value. Two-step.

Lists the container registry credentials at one level. These are what let a pipeline pull private images. Passwords are never returned.

Returns one registry entry — its address and username. The password is stripped by Woodpecker (Registry.Copy), so it is never in the answer.

Stores credentials for a container registry so pipelines can pull private images from it. The address is the identifier — there is no separate name — so "docker.io" and "index.docker.io" are two different entries.

Changes the username or password of a registry entry. The address itself cannot be changed — it is the identifier; delete and re-create instead.

Removes stored credentials for a registry. Pipelines that pull private images from it start failing at the pull step. Two-step.

Lists the scheduled pipeline runs of a repository, with the next execution time of each.

Returns one cron job, including the variables it passes.

Schedules a pipeline run. The pipeline runs with event "cron", so steps and secrets restricted to other events do not apply to it — a cron job whose steps all have "when: event: push" runs and does nothing.

Changes a cron job. Only the fields you pass are touched — including "enabled", which is how a schedule is paused without losing it.

Starts the cron job's pipeline immediately, without waiting for its schedule. The schedule itself is unchanged, and the run counts as a cron event — which is the point: this is how you test that a nightly job works before waiting a night for it. Every call is another run; a retry after a timeout starts a second one.

Removes a scheduled run. If you only want it to stop for now, update_cron with enabled=false keeps the definition. Two-step.

Lists the organizations known to this Woodpecker instance. Admin only. Note that an entry with is_user=true is a personal account, not a real organization — Woodpecker models both the same way, and org-level secrets work for both.

Returns one organization by its numeric id.

Resolves an organization name to its id — the id every other org-level call needs, including org-scoped secrets and registries.

What the authenticated account may do in this organization: member and admin. Org-level secrets and agents need admin here.

Removes an organization from Woodpecker together with its org-level secrets, registries and agents. Admin only. It does not touch the forge, and it does not delete the repositories — but anything of theirs that relied on an org-level secret stops working. Two-step.

Returns the account WOODPECKER_TOKEN belongs to, including whether it is an instance administrator. This is the first thing to call when a tool answers 403: the admin-only tools need admin=true here.

The activity feed of the authenticated account: the latest pipeline of every repository it can see, newest first. This is the "what is the state of everything" call — one request instead of list_pipelines per repository.

Lists the accounts known to this Woodpecker instance. Admin only. Woodpecker creates an account the first time someone logs in, so this is everyone who has ever used it, not a managed roster.

Returns one account by its login. Admin only. forge_id is required — see list_users for the value.

Registers an account ahead of its first login. Admin only. This does not create anything in the forge and grants no access there — the person still signs in through the forge; this only pre-creates the Woodpecker record, which is how you make someone an admin before they first log in. Passing admin=true asks a person first.

Changes an account. Admin only. The one that matters is "admin": granting it gives full control of the instance, including every secret of every repository. Fields you do not pass are preserved.

Removes an account from Woodpecker. Admin only. Repositories the account owned keep running on a token that no longer exists, which shows up later as pipelines that stop starting — chown_repository moves ownership to someone else, and doing that first is the point. Two-step.

Lists the build agents, with their platform, capacity, version and last contact — the call that answers "why is nothing being built". Without org_id this is the instance-wide list and needs an administrator. Agent tokens are redacted.

Returns one agent. Admin only. Its token is redacted; an agent that lost its token needs a new one, which means delete_agent and create_agent.

The work an agent is currently running. Admin only. This is how you find out what is occupying a busy agent, and which pipeline to cancel.

Registers a new build agent and returns its token. THE TOKEN IS A CREDENTIAL: whoever holds it can attach a machine to this server, receive pipeline workloads and read every secret those pipelines use. It is part of this answer because it is the only way to get it — put it straight into the agent's configuration and do not paste it anywhere else.

Changes an agent. Admin only. no_schedule=true is the drain switch: the agent finishes its current work and takes nothing new.

Removes an agent and invalidates its token. Anything it was running is lost and has to be restarted. Drain it first with update_agent no_schedule=true. Two-step.

Lists the forges this Woodpecker authenticates against. Admin only. The forge_id shown here is what get_user and delete_user require.

Returns one forge configuration. Admin only. The OAuth client secret is not part of the read model and is never returned.

Registers an additional forge. Admin only. The OAuth application has to exist on the forge side first, with this Woodpecker as its callback.

Changes a forge configuration. Admin only, and two-step: this is the setting every login and every repository read depends on, and a wrong value locks everyone out of the instance — including whoever is fixing it.

Removes a forge from Woodpecker. Admin only. Everyone who signs in through it loses access, and its repositories can no longer be read. Two-step.

Returns the Woodpecker version and whether the server reports itself healthy. Works without a token, which makes it the call to use when nothing else does: if this answers, WOODPECKER_URL is right and the problem is WOODPECKER_TOKEN.

The server-side build queue: what is pending, running and waiting on an agent, plus the agent statistics. Admin only. Together with list_queued_pipelines this is the whole answer to "why is my build not starting".

Returns the current log level of the Woodpecker server. Admin only.

Stops the server from handing new work to agents. Running pipelines finish; everything else queues up. Admin only, and instance-wide — this stops CI for everybody, and it stays paused until someone calls resume_queue. Two-step.

Lets the server hand work to agents again. Admin only. Queued pipelines start at once, so expect a burst.

Changes the log level of the running Woodpecker server, without a restart. Admin only. "debug" and "trace" are loud — set it back when you are done, and remember that trace logs request bodies.