---
title: "Check workloads for available upgrades"
method: GET
path: "/api/v1beta/workloads/upgrade-check"
tags: ["workloads"]
---

# Check workloads for available upgrades

`GET /api/v1beta/workloads/upgrade-check`

Check all workloads (optionally filtered by group) for newer
images available in their source registries. This is an offline
metadata comparison; it does not pull images. Secret values are
never returned.

## Query parameters

- `all` boolean
- `group` string

## Response `200`

OK

- PkgApiV1UpgradeCheckBulkResponse — Results of checking multiple workloads for available upgrades
  - `results` GithubComStacklokToolhivePkgWorkloadsUpgradeCheckResult[] — Results holds one upgrade-check outcome per scoped workload, in the order the workloads were enumerated. Each entry carries only metadata 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` — Group not found

## 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/upgrade-check/get.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)