API Reference

Common Convention

Base URL

https://openapi.gency.ai

Content-Type

All requests and responses use the application/json format.

Authentication

Every API request requires one of the following authentication headers.

Method	Header	Description
OAuth2 Token	`Authorization: Bearer {access_token}`	A token issued through the OAuth flow
API Key	`X-API-Key: {api_key}`	A key issued in the API Center

Success Response

The success response of every API is wrapped in the {"data": ...} form.

{
  "data": {
    // 리소스 데이터
  }
}

Error Response

On error, responses are returned in the following format.

{
  "status": 400,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "요청이 올바르지 않습니다."
  },
  "data": null,
  "timestamp": "2025-01-01T00:00:00.000Z"
}

Field	Type	Description
`status`	Integer	HTTP status code
`error.code`	String	Error code
`error.message`	String	Error message
`data`	Any	Additional error data (optional)
`timestamp`	String	Error timestamp (ISO 8601, UTC)

Team

Get My Team Information

GET /openapi/v1/teams/me

Required Scope: team:read

Response:

{
  "data": {
    "teamId": "01HABC...",
    "teamName": "김젠시의 팀",
    "plan": "MASTER_PLAN_01"
  }
}

Field	Type	Description
`teamId`	String	Team ID
`teamName`	String	Team name
`plan`	String	Plan (`BASIC`: basic, `ENTERPRISE`: enterprise)

Get Credits

GET /openapi/v1/usage/credits

Required Scope: team:read

Response:

{
"data": {
    "credit": 100
  }
}

Field	Type	Description
`credit`	Integer	Credit

Workspaces

Get Workspace List

GET /openapi/v1/workspaces

Required Scope: team:read

Response:

{
  "data": {
    "workspaces": [
      {
        "workspaceId": "01HXYZ...",
        "workspaceName": "My Workspace",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

Create Workspace

POST /openapi/v1/workspaces

Required Scope: team:write

Request Body:

{
  "name": "New Workspace"
}

Field	Type	Required	Description
`name`	String	O	Workspace name (up to 100 characters)

Rename Workspace

PATCH /openapi/v1/workspaces/{workspaceId}

Required Scope: team:write

Request Body:

{
  "name": "Updated Name"
}

Templates

Get Template List

GET /openapi/v1/templates?workspaceId={workspaceId}&productType={productType}

Required Scope: product:read

Query Parameters:

Parameter	Type	Required	Description
`workspaceId`	String	O	Workspace ID
`productType`	String	X	Product type (default: `FASHION`)

Response:

{
  "data": {
    "templateIds": ["template_01", "template_02"]
  }
}

Products

Get Product List

GET /openapi/v1/products?workspaceId={workspaceId}

Required Scope: product:read

Query Parameters:

Parameter	Type	Required	Description
`workspaceId`	String	O	Workspace ID

Response:

{
  "data": {
    "products": [
      {
        "productId": "01HXYZ...",
        "workspaceId": "01HABC...",
        "projectId": "01HDEF...",
        "name": "상품명",
        "titleImageId": "01HIMG...",
        "status": "REVIEW_COMPLETE",
        "categoryId": "01HCAT...",
        "productType": "FASHION",
        "createdId": "01HUSR...",
        "updatedId": "01HUSR...",
        "createdAt": "2025-01-01T00:00:00+09:00",
        "updatedAt": "2025-01-02T00:00:00+09:00"
      }
    ]
  }
}

Get Product Details

GET /openapi/v1/products/{productId}

Required Scope: product:read

Response:

{
  "data": {
    "productId": "01HXYZ...",
    "workspaceId": "01HABC...",
    "projectId": "01HDEF...",
    "name": "상품명",
    "titleImageId": "01HIMG...",
    "status": "REVIEW_COMPLETE",
    "categoryId": "01HCAT...",
    "productType": "FASHION",
    "createdId": "01HUSR...",
    "updatedId": "01HUSR...",
    "createdAt": "2025-01-01T00:00:00+09:00",
    "updatedAt": "2025-01-02T00:00:00+09:00"
  }
}

Create Product

POST /openapi/v1/products

Required Scope: product:write

Request Body:

{
  "workspaceId": "01HABC...",
  "products": [
    {
      "category": "TOP",
      "images": ["01HIMG..."],
      "projectId": "01HDEF...",
      "productNameKo": "상품명(한국어)",
      "productNameEn": "Product Name",
      "colors": ["BLACK", "WHITE"],
      "fabrics": ["COTTON"],
      "templateId": "TEMPLATE_01",
      "additionalInfo": {
        "features": ["스트레치 소재"],
        "laundryTips": ["드라이클리닝"],
        "sizeName": "FREE",
        "sizeTables": [["사이즈","어깨","기장"],["S", "55", "80"], ["M", "60", "85"]],
        "manufactureDate": "2025-01",
        "manufactureCountry": "대한민국",
        "certificationNumber": "KC-12345"
      }
    }
  ]
}

Request Fields

Field	Type	Required	Description
`workspaceId`	string	O	Workspace ID
`products`	array	O	Array of product metadata (at least 1)
`products[].category`	string	O	Product category (see below)
`products[].images`	array	O	Array of image IDs (at least 6, must be pre-uploaded via upload URL)
`products[].projectId`	string		Management name (project ID)
`products[].productName`	string		Product name
`products[].productNameKo`	string		Product name (Korean)
`products[].productNameEn`	string		Product name (English)
`products[].colors`	array	O	Color list
`products[].fabrics`	array	O	Fabric list
`products[].templateId`	string	O	Template ID
`products[].additionalInfo`	object		Additional information
`products[].additionalInfo.features`	array		Features
`products[].additionalInfo.laundryTips`	array		Laundry information
`products[].additionalInfo.sizeName`	string		Size name
`products[].additionalInfo.sizeTables`	array		Size table (2D array, the first row is header information)
`products[].additionalInfo.manufactureDate`	string		Manufacture date
`products[].additionalInfo.manufactureCountry`	string		Country of manufacture
`products[].additionalInfo.certificationNumber`	string		Certification number

Category Values

Only CLOTHING is supported; expansion is planned

Response:

{
  "data": {
    "productIds": ["01HXYZ...", "01HABC..."]
  }
}

Change Product Review Status

PATCH /openapi/v1/products/{productId}/status

Required Scope: product:write

Request Body:

{
  "status": "IN_REVIEW"
}

Field	Type	Required	Description
`status`	String	O	The status to change to

Possible status values:

Status	Description
`BEFORE_REVIEW`	Before review
`IN_REVIEW`	In review
`REVIEW_COMPLETE`	Review complete

Note: Changes are only possible when the status is before review / in review / review complete.

Users

Get My Information

GET /openapi/v1/users/me

Required Scope: user:read

Response:

{
  "data": {
    "userId": "01HXYZ...",
    "email": "user@example.com",
    "name": "김젠시",
    "permission": "MANAGER",
    "createdAt": "2025-01-01T00:00:00+09:00"
  }
}

Field	Type	Description
`userId`	String	User ID
`email`	String	Email
`name`	String	User name
`permission`	String	Permission (`OWNER`: owner, `MANAGER`: manager, `MEMBER`: member)
`createdAt`	String	Sign-up timestamp (ISO 8601)

Get Member Information

GET /openapi/v1/users/{userId}

Required Scope: user:read

Path Parameters:

Parameter	Type	Required	Description
`userId`	String	O	The user ID to look up

Note: You can only look up users who belong to the same team (master).

Response:

{
  "data": {
    "userId": "01HXYZ...",
    "email": "user@example.com",
    "name": "김젠시",
    "permission": "MANAGER",
    "createdAt": "2025-01-01T00:00:00+09:00"
  }
}

Get Team Member List

GET /openapi/v1/users

Required Scope: user:read

Response:

{
  "data": {
    "members": [
      {
        "userId": "01HXYZ...",
        "userName": "김젠시",
        "email": "user@example.com",
        "permission": "OWNER",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

Images

Issue Upload URL

POST /openapi/v1/images/upload-url

Required Scope: product:write

Request Body:

{
  "workspaceId": "01HABC...",
  "extension": "png"
}

Field	Type	Required	Description
`workspaceId`	String	O	Workspace ID
`extension`	String	O	File extension (`png`, `jpg`, `jpeg`, `webp`)

Response:

{
  "data": {
    "imageId": "01HXYZ...",
    "uploadUrl": "https://s3.amazonaws.com/..."
  }
}

Field	Type	Description
`imageId`	String	Image identifier (used when creating a product)
`uploadUrl`	String	S3 Presigned URL (valid for 1 hour)

Download Product Image

GET /openapi/v1/images/download/{productId}?templateId={templateId}

Required Scope: product:read

Query Parameters:

Parameter	Type	Required	Description
`templateId`	String	X	Template ID

Response: PNG image file (binary)

Full Endpoint Summary

Feature	Method	Endpoint	Scope
Get team info	GET	`/openapi/v1/team`	`team:read`
Get credits	GET	`/openapi/v1/usage/credits`	`team:read`
List workspaces	GET	`/openapi/v1/workspaces`	`team:read`
Create workspace	POST	`/openapi/v1/workspaces`	`team:write`
Update workspace	PATCH	`/openapi/v1/workspaces/{workspaceId}`	`team:write`
List templates	GET	`/openapi/v1/templates`	`product:read`
List products	GET	`/openapi/v1/products`	`product:read`
Product details	GET	`/openapi/v1/products/{productId}`	`product:read`
Create clothing product	POST	`/openapi/v1/products`	`product:write`
Change product status	PATCH	`/openapi/v1/products/{productId}/status`	`product:write`
Get my info	GET	`/openapi/v1/users/me`	`user:read`
Get member info	GET	`/openapi/v1/users/{userId}`	`user:read`
Team member list	GET	`/openapi/v1/users`	`user:read`
Create upload URL	POST	`/openapi/v1/images/upload-url`	`product:write`
Download image	GET	`/openapi/v1/images/download/{productId}`	`product:read`

Common Convention​

Team​

Get My Team Information​

Get Credits​

Workspaces​

Get Workspace List​

Create Workspace​

Rename Workspace​

Templates​

Get Template List​

Products​

Get Product List​

Get Product Details​

Create Product​

Change Product Review Status​

Users​

Get My Information​

Get Member Information​

Get Team Member List​

Images​

Issue Upload URL​

Download Product Image​

Full Endpoint Summary​

Common Convention

Team

Get My Team Information

Get Credits

Workspaces

Get Workspace List

Create Workspace

Rename Workspace

Templates

Get Template List

Products

Get Product List

Get Product Details

Create Product

Change Product Review Status

Users

Get My Information

Get Member Information

Get Team Member List

Images

Issue Upload URL

Download Product Image

Full Endpoint Summary