---
title: "Create Product Version"
method: POST
path: "/v1/products/{product_id}/versions"
tags: ["Product Catalog Versions"]
---

# Create Product Version

`POST /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

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

- `Idempotency-Key` string, nullable
- `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 입니다.

## Request body

- ProductVersionCreateRequest: `POST /v1/products/{product_id}/versions` 요청 본문. 자세한 SCHEMA 매핑과 제약은 이 클래스 위 주석에 있다.
  - `version` string, required: 버전 식별자(예: 'v1'/'v2'). 같은 상품 안에서 유일해야 한다. 형식 `^[A-Za-z0-9._-]{1,20}$`.
  - `provider` string, required: 등록된 기관 식별자. 등록되지 않은 값이면 400 VALIDATION_INVALID_FIELD 로 거절한다. 형식 `^[a-z][a-z0-9_]{0,63}$`.
  - `action` string, required: 등록된 액션 식별자. 기관에 종속한다. 형식 `^[a-z][a-z0-9_.]{0,63}$`.
  - `params_schema_ref` string, nullable: `provider.action.vN` 형식. 작업 결과의 schema 값과 같은 형식이다.
  - `result_schema_ref` string, nullable: 동상.
  - `pricing_hint` object, nullable: 가격 표시 힌트. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
  - `rate_limit_hint` object, nullable: rate limit 표시 힌트. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
  - `metadata` object, nullable: 자유 메타데이터. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
  - `publish_immediately` boolean: true 이면 발행 트랜잭션 안에서 version_status='PUBLISHED' + published_at=now(). false 이면 DRAFT 발행.
  - `set_as_current` boolean: publish_immediately=true + 본 필드 true ⇒ api_products.current_version_id 동시 UPDATE. publish_immediately=false + 본 필드 true ⇒ 422 VALIDATION_SEMANTIC_ERROR.

## Response `201`

Successful Response

- ProductVersionResponse: 상품 버전 단일 객체 응답. SCHEMA → DTO 매핑: - `api_product_versions.id` → `id`. - `product_id` / `version` / `version_status` / `provider` / `action` / 스키마 ref 2종 / `pricing_hint` / `rate_limit_hint` / `metadata` / `env_scope` / `created_at` → 직접 매핑. - lifecycle timestamps (`published_at` / `deprecated_at` / `retired_at`) — append-only 트리거가 단방향 전이 시 자동 채움. DRAFT 행은 모두 NULL. 응답에서 `metadata`/`pricing_hint`/`rate_limit_hint` 노출 허용 (자유 표시 메타다).
  - `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

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