---
title: "Check a workload for an available upgrade"
method: GET
path: "/api/v1beta/workloads/{name}/upgrade-check"
tags: ["workloads"]
---

# Check a workload for an available upgrade

`GET /api/v1beta/workloads/{name}/upgrade-check`

Check whether a single workload has a newer image available in
its source registry. This is an offline metadata comparison; it
does not pull images. Secret values are never returned.

## Path parameters

- `name` string, required

## 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

---

[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)