---
title: "List Product Versions"
method: GET
path: "/v1/products/{product_id}/versions"
tags: ["Product Catalog Versions"]
---

# List Product Versions

`GET /v1/products/{product_id}/versions`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/products/{product_id}/versions`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

## Path parameters

- `product_id` integer, required

## Query parameters

- `query` ProductVersionListQuery, required: `GET /v1/products/{product_id}/versions` 쿼리 파라미터. 페이지네이션 + 필터. 부모 `product_id` 는 경로 파라미터(본 DTO 영역 외).
  - `limit` integer
  - `cursor` string, nullable: opaque 커서 (BIGINT after_id 또는 URL-safe base64 인코딩 페이로드 — RFC 4648 §5). 최대 2048자 — RFC 7230 권고 HTTP URI 한도 (~8KB) 아래 안전 마진. 클라이언트는 본문을 해석하거나 만들지 않는다.
  - `sort` 'created_at:asc' | 'created_at:desc' | 'version:asc' | 'version:desc'
  - `version_status` string[], nullable: 버전 상태 필터. 다중 콤마 (`?version_status=PUBLISHED,DEPRECATED`) 또는 반복형 양쪽 허용. 최대 20 원소.
- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Response `200`

Successful Response

- PageEnvelopeProductVersionResponse
  - `items` ProductVersionResponse[]: Page result items. Empty list allowed.
    - `id` integer, required: api_product_versions.id.
    - `product_id` integer, required: 부모 api_products.id.
    - `version` string, required
    - `version_status` 'DRAFT' | 'PUBLISHED' | 'DEPRECATED' | 'RETIRED', required
    - `provider` string, required
    - `action` string, required
    - `params_schema_ref` string, nullable
    - `result_schema_ref` string, nullable
    - `pricing_hint` object, nullable
    - `rate_limit_hint` object, nullable
    - `metadata` object
    - `env_scope` 'sandbox' | 'real_test' | 'production', required: 부모 상품의 환경을 상속한다.
    - `published_at` string, date-time, nullable: 발행 시각. DRAFT 행은 NULL. PUBLISHED 진입 시 trg_*_lifecycle_timestamps 자동 채움.
    - `deprecated_at` string, date-time, nullable: 폐기 시각. PUBLISHED → DEPRECATED 전이 시 자동 채움.
    - `retired_at` string, date-time, nullable: 종결 시각. DEPRECATED → RETIRED 전이 시 자동 채움. terminal.
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable: Opaque cursor for next page, or null on last page.
  - `has_more` boolean: Whether another page exists. False when next_cursor is null.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)