---
title: "Apply an available upgrade to a workload"
method: POST
path: "/api/v1beta/workloads/{name}/upgrade"
tags: ["workloads"]
---

# Apply an available upgrade to a workload

`POST /api/v1beta/workloads/{name}/upgrade`

Apply a registry-sourced upgrade to a single workload. This
re-resolves and verifies the candidate image, pulls it, and only
then recreates the workload with the new image, preserving the
existing configuration. If the workload is already up to date or
is not registry-sourced, the current check result is returned
unchanged (no-op). Secret values are never accepted or returned.

## Path parameters

- `name` string, required

## Request body

- union
  - object
  - PkgApiV1UpgradeRequest — Request to apply an available upgrade to a workload. All fields are optional; an empty body applies the upgrade preserving the workload's existing configuration.
    - `env` object — Env holds additional or overriding environment variables to merge into the upgraded workload's configuration.
    - `secrets` string[] — Secrets holds additional secret parameters (`<name>,target=<env>`) to merge into the upgraded workload's configuration. Only references are accepted; no secret values are transmitted in the request.

## Response `200`

OK

- PkgApiV1UpgradeCheckResponse — Result of checking a single workload for an available upgrade
  - `result` GithubComStacklokToolhivePkgWorkloadsUpgradeCheckResult — Result is the upgrade-check outcome for the workload. It carries only metadata (status, image references, drift) and never secret values.
    - `candidate_image` string — CandidateImage is the image reference the registry currently reports.
    - `config_drift` GithubComStacklokToolhivePkgWorkloadsUpgradeConfigDrift — ConfigDrift describes posture differences (transport, permission profile) between the workload and the candidate registry entry.
      - `permission_profile` GithubComStacklokToolhivePkgWorkloadsUpgradeStringChange — PermissionProfile is set when the candidate's permission profile differs from the workload's current profile.
        - `from` string
        - `to` string
      - `transport` GithubComStacklokToolhivePkgWorkloadsUpgradeStringChange — PermissionProfile is set when the candidate's permission profile differs from the workload's current profile.
        - `from` string
        - `to` string
    - `current_image` string — CurrentImage is the image reference the workload is currently running.
    - `env_var_drift` GithubComStacklokToolhivePkgWorkloadsUpgradeEnvVarDrift — EnvVarDrift describes environment variables the candidate registry entry declares that differ from the workload's current configuration.
      - `added` GithubComStacklokToolhivePkgWorkloadsUpgradeEnvVarInfo[] — Added lists environment variables the candidate declares that the workload does not currently supply (via plain env vars or secrets).
        - `default` string — Default is the candidate's default value. It is cleared (left empty) whenever Secret is true: a secret env var's default could carry sensitive data, and surfacing it in a drift report (which may be logged or returned over the API) would leak it. Non-secret defaults are safe to display.
        - `description` string — Description is the human-readable purpose of the variable.
        - `name` string — Name is the environment variable name.
        - `required` boolean — Required indicates whether the candidate marks the variable as required.
        - `secret` boolean — Secret indicates whether the variable holds sensitive data.
      - `removed` GithubComStacklokToolhivePkgWorkloadsUpgradeEnvVarInfo[] — Removed lists environment variables the workload supplies that the candidate no longer declares. Populated on a best-effort basis; may be empty even when removals exist (forward-compatible field).
        - `default` string — Default is the candidate's default value. It is cleared (left empty) whenever Secret is true: a secret env var's default could carry sensitive data, and surfacing it in a drift report (which may be logged or returned over the API) would leak it. Non-secret defaults are safe to display.
        - `description` string — Description is the human-readable purpose of the variable.
        - `name` string — Name is the environment variable name.
        - `required` boolean — Required indicates whether the candidate marks the variable as required.
        - `secret` boolean — Secret indicates whether the variable holds sensitive data.
    - `reason` string — Reason provides additional context, primarily for StatusUnknown.
    - `registry_server` string — RegistryServer is the registry entry name the workload was sourced from. Empty when the workload is not registry-sourced.
    - `status` 'up-to-date' | 'upgrade-available' | 'not-registry-sourced' | 'server-not-found' | 'unknown' — Status is the upgrade status for the workload.
    - `workload_name` string — WorkloadName is the name of the workload that was checked.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

## Changes

> 49 revisions in range; 6 could not be searched.

- **2026-06-04** `1be6c27731fa` — 1 info
  - endpoint added
- **2026-01-29** `ff6ce8dd8f3a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/stacklok/apis/toolhive-api/changes/api/v1beta/workloads/:name/upgrade/post.md)

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/e9f942effcda/schema)