---
title: "Get tenant app versions by app ID"
method: GET
path: "/v2/tenant-apps/{appId}/versions"
tags: ["apps_management_Tenant Apps"]
---

# Get tenant app versions by app ID

`GET /v2/tenant-apps/{appId}/versions`

Retrieves a paginated list of every version uploaded for a specific tenant app.

Returns each version's TenantAppVersionResponse record. The legacy_format parameter controls whether version identification is returned as the legacy build_number or the newer version_code.

**About Get Tenant App Versions**

⚠️ iOS and Windows only. Every time a new build of a tenant app is uploaded, it becomes a new version under the same appId. This endpoint lists all of them, which is the standard way to find the version_id needed to install a specific build or to reference in a blueprint.

**Key Fields / Query Parameters**

legacy_format — when true (the default), returns build_number for backward compatibility; set to false to receive version_code instead

app_name — filters by app name

**Common Use Cases**

Finding the latest version of an app before assigning it to a blueprint

Auditing the upload history of a tenant app

**Best Practices**

Set legacy_format to false in new integrations to work with version_code directly, rather than relying on the legacy build_number field

Sort or filter results to confirm you're referencing the intended version before using it in a blueprint or install command

**Workflow**

Call this endpoint with the appId

Identify the versionId of the version you need

Call GET /v2/tenant-apps/{appId}/versions/{versionId} for that version's full detail

## Path parameters

- `appId` string, uuid, required

## Query parameters

- `limit` number
- `offset` number
- `app_name` string
- `app_type` string
- `is_active` boolean
- `legacy_format` boolean

## Response `200`

Success

- object
  - `content` object
    - `count` integer — number of results returned
    - `prev` string — URL for previous page of results
    - `next` string — URL for next page of results
    - `results` AppsManagementTenantAppVersionResponse[]
      - `id` string
      - `app_id` string
      - `app_type` 'TENANT_IOS' | 'TENANT_WINDOWS' | 'TENANT_WINDOWS_EXE' | 'TENANT_WINDOWS_UWP'
      - `tenant_id` string
      - `app_name` string
      - `app_icon_url` string
      - `release_notes` string
      - `description` string
      - `file_size_in_kb` integer
      - `device_family` string[]
      - `version_name` string
      - `build_number` string — Build number of the app. Omitted when legacy_format is false.
      - `version_code` string — Version code of the app (same as build_number). Only present when legacy_format is false.
      - `min_sdk_version` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `created_by` string
      - `updated_by` string
      - `is_active` boolean, nullable — Present only when app_type is TENANT_WINDOWS_EXE. True only when install_script, uninstall_script, and success_criteria are all set. Gates downstream install commands — a version with is_active=false cannot be deployed.
      - `success_criteria_type` 'REGISTRY_VALIDATION' | 'FILE_VALIDATION', nullable — Present only when app_type is TENANT_WINDOWS_EXE. Discriminator for the validation check performed after install/uninstall.
      - `success_criteria` union — Present only when app_type is TENANT_WINDOWS_EXE. Contains the validation args. Shape depends on success_criteria_type.
        - AppsManagementWindowsExeRegistryValidationArgs
          - `registry_path` string, required — Registry path. e.g. HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\MyApp
          - `registry_key` string, required — Registry value name within the path.
          - `registry_value` string, required — Expected value.
        - AppsManagementWindowsExeFileValidationArgs
          - `file_path` string, required — File path to check.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)