{ "openapi": "3.0.3", "info": { "title": "Product Library Open API", "version": "1.0.0", "description": "Existing MuseDAM API keys require explicit team-scoped API Key Collaborator access and fresh caller-key validation upstream. The current local role alone determines capabilities; no selectable operation allowlist remains. MuseDAM owns issuance and lifecycle; this API has no key-management or collaborator endpoints. JSON operations use the standard envelope; successful downloads and exports return attachments. All request bodies are capped at 1048576 bytes, including GET requests. Errors before attachment delivery use the shared Error envelope. No CORS/rate-limit contract, 429, bulk writes, multipart upload, webhooks or approval callbacks are provided by v1. Aborted lock conflicts return 503 write_conflict with Retry-After: 1; committed mutations whose response is unavailable return 409 mutation_response_unavailable with an explicit mutationOutcome." }, "servers": [ { "url": "https://open.musedam.cc/api/product", "description": "MuseDAM Product Library API" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "brands" }, { "name": "categories" }, { "name": "product-info-templates" }, { "name": "products" }, { "name": "assets" }, { "name": "product-activity" } ], "paths": { "/brands": { "get": { "operationId": "listBrands", "tags": [ "brands" ], "summary": "List brands", "description": "Returns public metadata ordered by sortOrder then id. Raw logo URLs are excluded.", "x-permissions": { "allOf": [ "brands:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": 10, "name": "Example brand", "code": "example-code", "description": null, "website": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "createBrand", "tags": [ "brands" ], "summary": "Create brand", "description": "Creates a brand; duplicate names are allowed and code is generated by the server. See BrandCreate for logo host restrictions.", "x-permissions": { "allOf": [ "brands:create" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 10, "name": "Example brand", "code": "example-code", "description": null, "website": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_code_in_use_idempotency_key_reused" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCreate" }, "examples": { "request": { "value": { "name": "Example brand" } } } } } } } }, "/brands/{id}": { "get": { "operationId": "getBrand", "tags": [ "brands" ], "summary": "Read brand", "description": "Returns the specified brand’s public metadata and current strong ETag. Raw logo URLs are excluded.", "x-permissions": { "allOf": [ "brands:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 10, "name": "Example brand", "code": "example-code", "description": null, "website": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "patch": { "operationId": "updateBrand", "tags": [ "brands" ], "summary": "Update brand", "description": "Updates the provided metadata fields; omitted properties remain unchanged. No file upload or generic asset replacement.", "x-permissions": { "allOf": [ "brands:update" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 10, "name": "Example brand", "code": "example-code", "description": "Updated by API", "website": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:05:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_mutation_response_unavailable" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPatch" }, "examples": { "request": { "value": { "description": "Updated by API" } } } } } } }, "delete": { "operationId": "deleteBrand", "tags": [ "brands" ], "summary": "Delete brand", "description": "Deletes only a brand with no live categories or products. Returns 409 otherwise; never cascades into products.", "x-permissions": { "allOf": [ "brands:delete" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedIdResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 10 }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_brand_has_dependents" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } } } }, "/categories": { "get": { "operationId": "listCategorys", "tags": [ "categories" ], "summary": "List categorys", "description": "Returns a flat live tree ordered by brandId, parentId, sortOrder and id. Optional brand filter; no implicit subtree expansion.", "x-permissions": { "allOf": [ "categories:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/BrandId" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": 20, "brandId": 10, "parentId": null, "name": "Catalog", "pathKey": "/Catalog", "description": null, "iconEmoji": null, "iconAssetId": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "createCategory", "tags": [ "categories" ], "summary": "Create category", "description": "Creates a live node in the specified brand. Parent must be live in the same brand/library. Max depth 10 and max 5000 live nodes per brand. Sibling names must be unique. The library default template is explicitly bound only when it has no brand bindings or includes this brand; otherwise creation succeeds without an explicit binding, preserving ancestor, brand, then library-default template resolution.", "x-permissions": { "allOf": [ "categories:create" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 20, "brandId": 10, "parentId": null, "name": "Catalog", "pathKey": "/Catalog", "description": null, "iconEmoji": null, "iconAssetId": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_name_in_use_idempotency_key_reused" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" }, "examples": { "request": { "value": { "name": "Catalog", "brandId": 10 } } } } } } } }, "/categories/{id}": { "get": { "operationId": "getCategory", "tags": [ "categories" ], "summary": "Read category", "description": "Returns the specified nondeleted category and current strong ETag. A missing category or one outside the current library returns 404.", "x-permissions": { "allOf": [ "categories:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 20, "brandId": 10, "parentId": null, "name": "Catalog", "pathKey": "/Catalog", "description": null, "iconEmoji": null, "iconAssetId": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "patch": { "operationId": "updateCategory", "tags": [ "categories" ], "summary": "Update category", "description": "Updates or moves a node within its existing brand; brandId is immutable. Rejects cycles/depth/node limits and invalid sort index. Updates descendant paths atomically.", "x-permissions": { "allOf": [ "categories:update" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 20, "brandId": 10, "parentId": null, "name": "Catalog", "pathKey": "/Catalog", "description": "Updated by API", "iconEmoji": null, "iconAssetId": null, "sortOrder": 0, "isEnabled": true, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:05:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_name_in_use" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryPatch" }, "examples": { "request": { "value": { "description": "Updated by API" } } } } } } }, "delete": { "operationId": "deleteCategory", "tags": [ "categories" ], "summary": "Delete category", "description": "Soft-deletes the entire category subtree only if no live products reference any descendant. Does not delete or demote products.", "x-permissions": { "allOf": [ "categories:delete" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedIdResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 20 }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_category_has_products" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } } } }, "/product-info-templates": { "get": { "operationId": "listTemplates", "tags": [ "product-info-templates" ], "summary": "List templates", "description": "Returns live template metadata, bindings and ordered groups/fields, including preview-only configuration. Ordered by createdAt descending then id.", "x-permissions": { "allOf": [ "templates:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": "template_example", "name": "Example template", "description": null, "enabled": true, "isSystemDefault": false, "isLibraryDefault": false, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "boundBrandIds": [], "boundCategoryIds": [], "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_name", "key": "name", "name": "商品名称", "type": "text", "required": true, "placeholder": null, "sortOrder": 0, "isSystemField": true, "systemKey": "name", "config": {} }, { "id": "field_sku", "key": "sku", "name": "SKU", "type": "text", "required": true, "placeholder": null, "sortOrder": 1, "isSystemField": true, "systemKey": "sku", "config": {} }, { "id": "field_main_image", "key": "mainImage", "name": "商品主图", "type": "image", "required": true, "placeholder": null, "sortOrder": 2, "isSystemField": true, "systemKey": "mainImage", "config": {} }, { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 3, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "createTemplate", "tags": [ "product-info-templates" ], "summary": "Create template", "description": "Creates a template and an immutable version. syncStrategy is optional and only newOnly is supported. Allows at most 200 fields and leaves existing products unchanged.", "x-permissions": { "allOf": [ "templates:create" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "template_example", "name": "Example template", "description": null, "enabled": true, "isSystemDefault": false, "isLibraryDefault": false, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "boundBrandIds": [], "boundCategoryIds": [], "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_name", "key": "name", "name": "商品名称", "type": "text", "required": true, "placeholder": null, "sortOrder": 0, "isSystemField": true, "systemKey": "name", "config": {} }, { "id": "field_sku", "key": "sku", "name": "SKU", "type": "text", "required": true, "placeholder": null, "sortOrder": 1, "isSystemField": true, "systemKey": "sku", "config": {} }, { "id": "field_main_image", "key": "mainImage", "name": "商品主图", "type": "image", "required": true, "placeholder": null, "sortOrder": 2, "isSystemField": true, "systemKey": "mainImage", "config": {} }, { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 3, "isSystemField": false, "systemKey": null, "config": {} } ] } ] }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_name_in_use_idempotency_key_reused" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreate" }, "examples": { "request": { "value": { "name": "Example template", "groups": [ { "name": "Details", "fields": [ { "key": "color", "name": "Color", "type": "text", "config": {} } ] } ] } } } } } } } }, "/product-info-templates/{id}": { "get": { "operationId": "getTemplate", "tags": [ "product-info-templates" ], "summary": "Read template", "description": "Returns the specified nondeleted template’s metadata, bindings, and groups/fields, including preview-only configuration. Groups and fields are ordered by sortOrder then id, ascending. The current strong ETag covers live fields, groups, bindings, and the default designation.", "x-permissions": { "allOf": [ "templates:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "template_example", "name": "Example template", "description": null, "enabled": true, "isSystemDefault": false, "isLibraryDefault": false, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "boundBrandIds": [], "boundCategoryIds": [], "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_name", "key": "name", "name": "商品名称", "type": "text", "required": true, "placeholder": null, "sortOrder": 0, "isSystemField": true, "systemKey": "name", "config": {} }, { "id": "field_sku", "key": "sku", "name": "SKU", "type": "text", "required": true, "placeholder": null, "sortOrder": 1, "isSystemField": true, "systemKey": "sku", "config": {} }, { "id": "field_main_image", "key": "mainImage", "name": "商品主图", "type": "image", "required": true, "placeholder": null, "sortOrder": 2, "isSystemField": true, "systemKey": "mainImage", "config": {} }, { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 3, "isSystemField": false, "systemKey": null, "config": {} } ] } ] }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "patch": { "operationId": "updateTemplate", "tags": [ "product-info-templates" ], "summary": "Update template", "description": "Uses the shared browser batch operation. Supplied groups/fields are a complete replacement; omitted groups are preserved. Stable IDs and protected system/default fields are validated. Creates a new immutable version without migrating existing product pins or values; bindings/default changes affect future template resolution.", "x-permissions": { "allOf": [ "templates:update" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "template_example", "name": "Example template", "description": "Updated by API", "enabled": true, "isSystemDefault": false, "isLibraryDefault": false, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:05:00.000Z", "boundBrandIds": [], "boundCategoryIds": [], "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_name", "key": "name", "name": "商品名称", "type": "text", "required": true, "placeholder": null, "sortOrder": 0, "isSystemField": true, "systemKey": "name", "config": {} }, { "id": "field_sku", "key": "sku", "name": "SKU", "type": "text", "required": true, "placeholder": null, "sortOrder": 1, "isSystemField": true, "systemKey": "sku", "config": {} }, { "id": "field_main_image", "key": "mainImage", "name": "商品主图", "type": "image", "required": true, "placeholder": null, "sortOrder": 2, "isSystemField": true, "systemKey": "mainImage", "config": {} }, { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 3, "isSystemField": false, "systemKey": null, "config": {} } ] } ] }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_name_in_use" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePatch" }, "examples": { "request": { "value": { "description": "Updated by API" } } } } } } }, "delete": { "operationId": "deleteTemplate", "tags": [ "product-info-templates" ], "summary": "Delete template", "description": "Soft-deletes the live template while retaining immutable versions used by existing products. Current library default requires an explicit replacement or null; default/system protections still apply. Removes bindings without rewriting existing product pins.", "x-permissions": { "allOf": [ "templates:delete" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedTemplateIdResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "template_example" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_default_template_replacement_required" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDelete" }, "examples": { "request": { "value": { "replacementForLibraryDefault": null } } } } } } } }, "/products": { "get": { "operationId": "listProducts", "tags": [ "products" ], "summary": "List or synchronize products", "description": "Ordinary pagination orders updatedAt/id descending. sync=true uses ascending (updatedAt,id), inclusive lower and exclusive fixed upper bound (PostgreSQL clock minus 30 seconds). A full scan omits updatedAfter; continue every nextCursor, even with an empty data page. Cursor binds key/role/library/filters/pageSize/bounds. Save syncedUntil verbatim only after exhaustion; replay/deduplicate by id and updatedAt. Transactions longer than the 30-second safety window are an accepted v1 limitation. view_only/usable see only published products.", "x-permissions": { "allOf": [ "products:read" ], "conditional": [ "products:download" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Search" }, { "$ref": "#/components/parameters/BrandId" }, { "$ref": "#/components/parameters/CategoryId" }, { "$ref": "#/components/parameters/Status" }, { "$ref": "#/components/parameters/Sync" }, { "$ref": "#/components/parameters/UpdatedAfter" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [] } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } }, "sync": { "value": { "success": true, "data": [ { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.123456Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [] } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "pageSize": 20, "syncedUntil": "2026-10-08T10:01:00.123456Z", "nextCursor": null, "hasMore": false } } }, "emptyContinuation": { "value": { "success": true, "data": [], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "pageSize": 20, "syncedUntil": "2026-10-08T10:01:00.123456Z", "nextCursor": "opaque-continuation-token", "hasMore": true } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "createProduct", "tags": [ "products" ], "summary": "Create a draft product", "description": "Creates draft only. Resolves and pins a template version at creation; template fields validate against that immutable definition. Attach existing same-library FilePath IDs; no upload, remote import or provider write-back. Idempotent replay preserves original scalar result/ETag and reprojects only original media still valid in the same current slot under current grants.", "x-permissions": { "allOf": [ "products:create" ], "conditional": [ "products:read", "products:download" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [], "templateDefinition": { "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 0, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_sku_in_use_idempotency_key_reused" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreate" }, "examples": { "request": { "value": { "name": "Example product", "spu": "EXAMPLE-001", "brandId": 10, "categoryId": 20, "coverAssetId": 30, "imageAssetIds": [ 30 ] } } } } } } } }, "/products/{id}": { "get": { "operationId": "getProduct", "tags": [ "products" ], "summary": "Read a product and its pinned definition", "description": "Returns an accessible live product with its pinned immutable template definition, even after the live template changes or is deleted. Does not require templates:read. Media preview/download is authorized on every response; download requires products:read plus products:download and role usable or higher. Drafts are invisible to view_only/usable.", "x-permissions": { "allOf": [ "products:read" ], "conditional": [ "products:download" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [], "templateDefinition": { "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 0, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } }, "noTemplateOrMedia": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": null, "templateVersionId": null, "templateFields": {}, "cover": null, "images": [], "relatedAssets": [], "templateDefinition": null }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } }, "authorizedDownload": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example", "downloadUrl": "https://media.example.test/original?signature=example", "downloadUrlExpiresAt": "2026-10-08T10:05:00.000Z" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [], "templateDefinition": { "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 0, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "patch": { "operationId": "updateProduct", "tags": [ "products" ], "summary": "Partially update a product", "description": "Merges scalar/custom fields and replaces submitted media lists. Uses the immutable pinned definition, including when the live template is deleted. Published products additionally require products:publish and stay published; full resulting-state validation must pass atomically. Status/template switching is not accepted here.", "x-permissions": { "allOf": [ "products:update" ], "conditional": [ "products:publish", "products:read", "products:download" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "draft", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": null, "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [], "templateDefinition": { "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 0, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_sku_in_use" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPatch" }, "examples": { "request": { "value": { "description": null, "templateFields": { "field_color": "Blue" } } } } } } } }, "delete": { "operationId": "deleteProduct", "tags": [ "products" ], "summary": "Soft-delete a product", "description": "Soft-deletes a visible live product. Draft requires delete; published requires delete and publish. Leaves historical template versions intact. No provider synchronization. A repeated delete returns 404.", "x-permissions": { "allOf": [ "products:delete" ], "conditional": [ "products:publish" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedIdResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 40 }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_mutation_response_unavailable" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } } } }, "/products/{id}/status": { "patch": { "operationId": "setProductStatus", "tags": [ "products" ], "summary": "Publish or return a product to draft", "description": "Always requires both update and publish grants. Publishing validates all pinned required/type/option/media rules; invalid state returns 422 with field details and makes no changes. Repeated published keeps publishedAt, returning to draft clears it. No approval workflow is started.", "x-permissions": { "allOf": [ "products:update", "products:publish" ], "conditional": [ "products:read", "products:download" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 40, "name": "Example product", "spu": "EXAMPLE-001", "description": null, "status": "published", "brandId": 10, "categoryId": 20, "ownerUserId": null, "publishedAt": "2026-10-08T10:00:00.000Z", "createdAt": "2026-10-08T10:00:00.000Z", "updatedAt": "2026-10-08T10:00:00.000Z", "draftReason": null, "templateId": "template_example", "templateVersionId": "version_one", "templateFields": { "field_color": "Blue" }, "cover": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "images": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "relatedAssets": [], "templateDefinition": { "groups": [ { "id": "group_details", "name": "Details", "isDefault": true, "sortOrder": 0, "fields": [ { "id": "field_color", "key": "color", "name": "Color", "type": "text", "required": false, "placeholder": null, "sortOrder": 0, "isSystemField": false, "systemKey": null, "config": {} } ] } ] } }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409_mutation_response_unavailable" }, "412": { "$ref": "#/components/responses/Error412_precondition_failed" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductStatus" }, "examples": { "request": { "value": { "status": "published" } } } } } } } }, "/products/visibility": { "post": { "operationId": "checkProductVisibility", "tags": [ "products" ], "summary": "Reconcile known product IDs", "description": "Checks up to 100 known IDs under current key visibility. Keeps order and duplicates, accepts an empty array. not_visible does not distinguish deleted, missing, foreign-library and role-hidden items. Use periodically to remove stale local entries because sync has no deletion tombstones. This read operation has no Idempotency-Key or ETag.", "x-permissions": { "allOf": [ "products:read" ] }, "x-roles": [ "view_only", "usable", "editable", "manage" ], "parameters": [], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": 40, "visibility": "visible" }, { "id": 41, "visibility": "not_visible" } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityInput" }, "examples": { "request": { "value": { "ids": [ 40, 41 ] } } } } } } } }, "/assets": { "get": { "operationId": "listAssets", "tags": [ "assets" ], "summary": "Find existing library assets", "description": "Lists live non-directory FilePath assets in the key library, ordered by id. Requires either products:create or products:update under editable/manage role, not products:read. Returns previews only, never original download fields. Use FilePath id in product writes; uploads are outside v1.", "x-permissions": { "allOf": [], "anyOf": [ "products:create", "products:update" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Search" }, { "$ref": "#/components/parameters/MimeType" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryAssetListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } } }, "/assets/{id}": { "get": { "operationId": "getAsset", "tags": [ "assets" ], "summary": "Read an existing library asset", "description": "Returns a live same-library FilePath with preview-only media metadata. Same create-or-update gate as listing. Returns an opaque strong ETag based on the FilePath and linked AssetObject identities and maintained update timestamps; temporary signature changes do not change this tag.", "x-permissions": { "allOf": [], "anyOf": [ "products:create", "products:update" ] }, "x-roles": [ "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryAssetResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": 30, "name": "cover.jpg", "mimeType": "image/jpeg", "size": "9007199254740993", "width": 1200, "height": 900, "duration": null, "previewUrl": "https://media.example.test/preview?signature=example" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } } }, "/product-shares": { "get": { "operationId": "listProductShares", "tags": [ "product-activity" ], "summary": "List team share history", "description": "Lists records from every browser actor and API key in the current team, newest first by createdAt and id. Optional productId returns complete matching operations; omission selects all team records. Only productId, page and pageSize are accepted; unknown or repeated parameters return 422. The current API key or creator never implicitly narrows the list. Requires manage plus products:history, without products:read.", "x-permissions": { "allOf": [ "products:history" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductShareListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": "share-example", "url": "https://your-deployment.example/share/products/example-recipient-token", "products": [ { "id": 40, "name": "Example product", "spu": "SKU-40" } ], "createdById": null, "createdByApiKeyId": "integration-key-id", "createdByName": "Catalog integration", "createdAt": "2026-10-09T10:00:00.000Z", "expiresAt": "2026-10-16T10:00:00.000Z", "revokedAt": null, "allowDownload": false, "hasAccessCode": false, "status": "active", "canRevoke": true } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "createProductShare", "tags": [ "product-activity" ], "summary": "Create product share", "description": "Creates a fixed selection of published products with a 7/30/90-day or unlimited lifetime. accessCode is optional and exactly four digits. allowDownload additionally requires products:download. The recipient needs no login or API key; unpublished/deleted products disappear from the live share. Creator-key changes do not revoke the independent team share. Optional 24-hour idempotency reuses the same share.", "x-permissions": { "allOf": [ "products:read", "products:share" ], "conditional": [ "products:download" ] }, "x-roles": [ "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/ShareIdempotencyKey" } ], "responses": { "201": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductShareResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "share-example", "url": "https://your-deployment.example/share/products/example-recipient-token", "products": [ { "id": 40, "name": "Example product", "spu": "SKU-40" } ], "createdById": null, "createdByApiKeyId": "integration-key-id", "createdByName": "Catalog integration", "createdAt": "2026-10-09T10:00:00.000Z", "expiresAt": "2026-10-16T10:00:00.000Z", "revokedAt": null, "allowDownload": false, "hasAccessCode": false, "status": "active", "canRevoke": false }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "409": { "$ref": "#/components/responses/Error409ShareReplay" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductShareCreate" }, "examples": { "request": { "value": { "productIds": [ 40 ], "expiresInDays": 7, "allowDownload": false } } } } } } } }, "/product-shares/{id}": { "delete": { "operationId": "revokeProductShare", "tags": [ "product-activity" ], "summary": "Revoke product share", "description": "Revokes any share in the current team. Requires manage and products:share, without products:read. Repeating a revocation returns the original revokedAt. Unknown or foreign-team IDs return 404. No ETag or If-Match is used.", "x-permissions": { "allOf": [ "products:share" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/ShareId" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedProductShareResponse" }, "examples": { "success": { "value": { "success": true, "data": { "id": "share-example", "revokedAt": "2026-10-09T11:00:00.000Z" }, "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" }, "503": { "$ref": "#/components/responses/Error503_write_conflict" } } } }, "/product-downloads": { "get": { "operationId": "listProductDownloads", "tags": [ "product-activity" ], "summary": "List team download history", "description": "Lists records from every browser actor and API key in the current team, newest first by createdAt and id. Optional productId returns complete matching operations; omission selects all team records. Only productId, page and pageSize are accepted; unknown or repeated parameters return 422. The current API key or creator never implicitly narrows the list. Requires manage plus products:history, without products:read.", "x-permissions": { "allOf": [ "products:history" ] }, "x-roles": [ "manage" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDownloadListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "id": "download-example", "kind": "product_export", "status": "requested", "actorType": "api_key", "actorId": null, "apiKeyId": "integration-key-id", "actorName": "Catalog integration", "shareId": null, "products": [ { "id": 40, "name": "Example product", "spu": "SKU-40" } ], "files": [ { "id": "export:xlsx", "productId": 40, "name": "products.xlsx" } ], "createdAt": "2026-10-09T10:00:00.000Z" } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111", "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } }, "post": { "operationId": "downloadProducts", "tags": [ "product-activity" ], "summary": "Download originals or export products", "description": "Returns one original, a ZIP of selected originals, or an XLSX/CSV/JSON business-table export. Requires current read and download grants under usable or higher; usable sees published products only. Accepted operations are recorded before delivery. Export links default to authenticated single-file GET URLs; each accepted retrieval has its own business record. Optional Idempotency-Key retains one record for 24 hours while each retry reauthorizes and transfers current content. Product reads, previews and legacy storage downloadUrl use are not recorded by this operation.", "x-permissions": { "allOf": [ "products:read", "products:download" ] }, "x-roles": [ "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/DownloadIdempotencyKey" } ], "responses": { "200": { "description": "Attachment bytes, not a success envelope. JSON exports contain a localized array of business-table rows. A failure after streaming begins can terminate the body and mark the record failed; it cannot replace the committed response with a JSON error.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-Download-Record-Id": { "$ref": "#/components/headers/X-Download-Record-Id" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/X-Idempotency-Replayed" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactiveAttachment" }, "403": { "$ref": "#/components/responses/Error403_forbiddenAttachment" }, "404": { "$ref": "#/components/responses/Error404_not_foundAttachment" }, "409": { "$ref": "#/components/responses/Error409ProductDownloadAttachment" }, "413": { "$ref": "#/components/responses/Error413ProductDownloadAttachment" }, "422": { "$ref": "#/components/responses/Error422_validation_failedAttachment" }, "500": { "$ref": "#/components/responses/Error500_internal_server_errorAttachment" }, "503": { "$ref": "#/components/responses/Error503_write_conflictAttachment" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDownloadCreate" }, "examples": { "request": { "value": { "kind": "export", "productIds": [ 40 ], "format": "xlsx", "includeAssetUrls": true, "locale": "zh-CN" } } } } } } } }, "/products/{id}/download-assets": { "get": { "operationId": "listProductDownloadAssets", "tags": [ "product-activity" ], "summary": "List product download candidates", "description": "Returns current candidate selection keys and downloadable availability under read and download authorization. No business download record is created, and no original or preview URLs are returned. Use the single-file route or POST product-downloads to retrieve bytes.", "x-permissions": { "allOf": [ "products:read", "products:download" ] }, "x-roles": [ "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful request.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDownloadCandidateListResponse" }, "examples": { "success": { "value": { "success": true, "data": [ { "key": "p40:a2", "name": "example.png", "productId": 40, "productName": "Example product", "category": "main", "mimeType": "image/png", "size": "1024", "downloadable": true } ], "code": null, "message": null, "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactive" }, "403": { "$ref": "#/components/responses/Error403_forbidden" }, "404": { "$ref": "#/components/responses/Error404_not_found" }, "413": { "$ref": "#/components/responses/Error413_payload_too_large" }, "422": { "$ref": "#/components/responses/Error422_validation_failed" }, "500": { "$ref": "#/components/responses/Error500_internal_server_error" } } } }, "/products/{id}/download-assets/{assetKey}": { "get": { "operationId": "downloadProductAsset", "tags": [ "product-activity" ], "summary": "Download one product original", "description": "Fetches one current product original identified by an encoded candidate key. Requires a Bearer header and current read/download authorization; the URL contains no API-key secret. Creates a business record before delivery. Optional 24-hour idempotency is scoped separately from POST downloads, reuses the record, and still reauthorizes and transfers current bytes.", "x-permissions": { "allOf": [ "products:read", "products:download" ] }, "x-roles": [ "usable", "editable", "manage" ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/AssetKey" }, { "$ref": "#/components/parameters/DownloadIdempotencyKey" } ], "responses": { "200": { "description": "Attachment bytes, not a success envelope. JSON exports contain a localized array of business-table rows. A failure after streaming begins can terminate the body and mark the record failed; it cannot replace the committed response with a JSON error.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-Download-Record-Id": { "$ref": "#/components/headers/X-Download-Record-Id" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/X-Idempotency-Replayed" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error401_invalid_credentials_key_inactiveAttachment" }, "403": { "$ref": "#/components/responses/Error403_forbiddenAttachment" }, "404": { "$ref": "#/components/responses/Error404_not_foundAttachment" }, "409": { "$ref": "#/components/responses/Error409ProductDownloadAttachment" }, "413": { "$ref": "#/components/responses/Error413ProductDownloadAttachment" }, "422": { "$ref": "#/components/responses/Error422_validation_failedAttachment" }, "500": { "$ref": "#/components/responses/Error500_internal_server_errorAttachment" }, "503": { "$ref": "#/components/responses/Error503_write_conflictAttachment" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Existing MuseDAM API key with an explicit team-scoped collaborator grant. Send Authorization: Bearer over HTTPS. The assigned local role determines capabilities independently of the creator; every admitted request validates the caller key upstream. Removed or unadded keys have no access. Upstream unavailability fails closed." } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": "Positive signed 32-bit resource ID." }, "TemplateId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Opaque template ID; do not assume UUID syntax." }, "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Ordinary page number. Not allowed when sync=true. Excessive offset causing integer overflow is rejected." }, "PageSize": { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 20 }, "description": "Page size; values above 100 are capped at 100. Nonpositive/noninteger values are rejected." }, "Search": { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Trimmed case-insensitive substring: product name/spu, or library asset name." }, "BrandId": { "name": "brandId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": "Filter by brand ID within this library." }, "CategoryId": { "name": "categoryId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "description": "Filter by exact category ID, not its descendants." }, "Status": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "published" ] }, "description": "Requested product status; does not widen role visibility." }, "MimeType": { "name": "mimeType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Trimmed case-insensitive MIME prefix, for example image/ or application/pdf." }, "Sync": { "name": "sync", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "description": "true selects bounded keyset synchronization; false is ordinary pagination." }, "UpdatedAfter": { "name": "updatedAfter", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only with sync=true. Inclusive lower bound; RFC3339 Z/offset, 0..6 fractional digits, valid calendar/offset. Save and reuse syncedUntil as a string. Omit for a full scan." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 8192 }, "description": "Opaque continuation token, only with sync=true. Binds key, role, library, bounds, filters and page size. On continuation omit other parameters or repeat equivalent values. Duplicate sync parameters are rejected." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional nonblank value without ASCII controls. Scoped to team, key and create operation for 24 hours. Same canonical payload replays 201 and original scalar result/ETag; changed payload gives 409. Product media is reprojected using current authorization and valid original same-slot associations." }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional strong quoted ETag, * or comma-separated candidate tags. Weak tags do not match. Stale mismatch gives 412 after row lock, without writes; omission uses last-writer-wins. Refetch current data before reconciling. No If-None-Match/304 support." }, "ProductId": { "name": "productId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PositiveId" }, "description": "Filter matching activity by one product ID. The full operation is returned, including other products and files. Omit for all records in the current team." }, "ShareId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Opaque share identifier." }, "AssetKey": { "name": "assetKey", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "URL-encoded selection key returned by the product download-candidate list. Not a FilePath or AssetObject ID." }, "ShareIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional nonblank value without ASCII controls, at most 255 characters. Scoped to team, API key and share creation for 24 hours. Matching input reuses the share; changed input returns 409. No header or expired retention creates a new operation. Current authorization is checked on replay." }, "DownloadIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional nonblank value without ASCII controls, at most 255 characters. Scoped to team, API key and download operation for 24 hours. Matching input reuses the business record but reauthorizes, reads current content and transfers again; file bytes are not cached. POST and single-file GET have separate operation scopes. Changed input returns 409. Omission, a new key or expiry creates a new record; deduplication is not permanent." } }, "headers": { "Cache-Control": { "description": "Always private, no-store, including errors. Do not cache signed media or credentials.", "schema": { "type": "string", "enum": [ "private, no-store" ] } }, "X-Request-Id": { "description": "Server-generated correlation ID; JSON envelopes also include requestId.", "schema": { "type": "string", "format": "uuid" } }, "ETag": { "description": "Strong opaque quoted resource validator; send verbatim in If-Match for a later mutation. It covers stored resource state, not expiring media URL text.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Attachment filename. One original keeps its filename; multiple originals use products.zip; exports use products.xlsx, products.csv or products.json.", "schema": { "type": "string" } }, "X-Download-Record-Id": { "description": "Business record ID for this accepted operation; retries with the retained idempotency key reuse it. It does not certify delivery or local-save completion.", "schema": { "type": "string" } }, "X-Idempotency-Replayed": { "description": "Present with true only when the retained business record is reused.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "PositiveId": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "TemplateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "Page": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 } }, "required": [ "page", "pageSize", "totalCount", "totalPages" ], "additionalProperties": false }, "SyncPage": { "type": "object", "properties": { "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "syncedUntil": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d\\d-\\d\\dT\\d\\d:\\d\\d:\\d\\d\\.\\d{6}Z$", "description": "PostgreSQL clock minus 30 seconds, fixed for the cycle. Save this exact string only after nextCursor is null." }, "nextCursor": { "type": "string", "maxLength": 8192, "nullable": true }, "hasMore": { "type": "boolean" } }, "required": [ "pageSize", "syncedUntil", "nextCursor", "hasMore" ], "additionalProperties": false }, "Brand": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "code": { "type": "string" }, "description": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "sortOrder": { "type": "integer" }, "isEnabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." } }, "required": [ "id", "name", "code", "description", "website", "sortOrder", "isEnabled", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Public scalar metadata. logoUrl is never returned. code is server-generated and read-only; website, sortOrder and isEnabled are read-only in v1." }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "parentId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "name": { "type": "string" }, "pathKey": { "type": "string" }, "description": { "type": "string", "nullable": true }, "iconEmoji": { "type": "string", "nullable": true }, "iconAssetId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "sortOrder": { "type": "integer" }, "isEnabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." } }, "required": [ "id", "brandId", "parentId", "name", "pathKey", "description", "iconEmoji", "iconAssetId", "sortOrder", "isEnabled", "createdAt", "updatedAt" ], "additionalProperties": false, "description": "Flat tree node. iconAssetId refers to CategoryIconAsset, not FilePath. No icon URL is returned." }, "PreviewAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "name": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "pattern": "^\\d+$", "description": "Decimal byte count string; never a JSON number.", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "previewUrl": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "id", "name", "mimeType", "size", "width", "height", "duration", "previewUrl" ], "additionalProperties": false, "description": "Preview-only asset projection used by library asset lookup and template configuration. FilePath ID, or null for unresolved/legacy media. No download properties." }, "LibraryAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "pattern": "^\\d+$", "description": "Decimal byte count string; never a JSON number.", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "previewUrl": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "id", "name", "mimeType", "size", "width", "height", "duration", "previewUrl" ], "additionalProperties": false, "description": "A live FilePath in this product library. Use its id in product media writes. Contains preview fields only, regardless of products:download." }, "PublicAsset": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "name": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "pattern": "^\\d+$", "description": "Decimal byte count string; never a JSON number.", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "previewUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrlExpiresAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits.", "nullable": true } }, "required": [ "id", "name", "mimeType", "size", "width", "height", "duration", "previewUrl" ], "additionalProperties": false, "description": "Product media projection. id is FilePath.id, never AssetObject.id or ProductAsset.id. Download properties are omitted unless a current, resolvable product association is downloadable under products:read + products:download and role usable/editable/manage. An authorized unavailable original may return null. Non-image originals never serve as previews. Preview null means unavailable. For a finite key, stored third-party previews with unverifiable expiry return null. Keys without expiry retain eligible stored third-party previews; their lifetime is provider-controlled, without a service-issued TTL guarantee." }, "FieldConfig": { "type": "object", "additionalProperties": true, "description": "Type-dependent configuration; media references in reads are projected to PreviewAsset, removing storage paths and credentials. Write config rules: plain text/textarea/email/phone/url/color/date/dateRange use {}; number allows unit; currency requires code/symbol and decimals 0..4; richtext mode is html or delta; select/radio/checkbox require nonempty options with unique value, label, sortOrder and optional archived; image/file accept maxCount and maxSizeMB > 0 plus accept string array. System customPlaceholder may be at most 255 characters. System brand/category cannot accept custom options." }, "OptionConfig": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "sortOrder": { "type": "integer", "minimum": 0 }, "archived": { "type": "boolean" } }, "required": [ "value", "label", "sortOrder" ], "additionalProperties": true }, "EmptyFieldConfig": { "type": "object", "properties": {}, "additionalProperties": false }, "NumberFieldConfig": { "type": "object", "properties": { "unit": { "type": "string" } }, "additionalProperties": true }, "CurrencyFieldConfig": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 }, "symbol": { "type": "string", "minLength": 1 }, "decimals": { "type": "integer", "minimum": 0, "maximum": 4 } }, "required": [ "code", "symbol", "decimals" ], "additionalProperties": true }, "RichtextFieldConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "html", "delta" ] } }, "required": [ "mode" ], "additionalProperties": true }, "ChoiceFieldConfig": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/OptionConfig" }, "minItems": 1 } }, "required": [ "options" ], "additionalProperties": true, "description": "Option values must be unique. Unknown config/option properties are stripped by validation." }, "MediaFieldConfig": { "type": "object", "properties": { "maxCount": { "type": "integer", "minimum": 1 }, "maxSizeMB": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "accept": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "SystemFieldConfig": { "type": "object", "properties": { "customPlaceholder": { "type": "string", "maxLength": 255 } }, "additionalProperties": false }, "FieldConfigInput": { "type": "object", "additionalProperties": true, "description": "Validated using the resolved field type/system identity, including existing field identity on PATCH. See x-config-by-field-type and SystemFieldConfig; existing protected system settings cannot be reassigned. Unknown properties are rejected by empty/system configs and stripped by other config validators.", "x-config-by-field-type": { "text": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "textarea": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "email": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "phone": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "url": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "color": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "richtext": { "$ref": "#/components/schemas/RichtextFieldConfig" }, "number": { "$ref": "#/components/schemas/NumberFieldConfig" }, "currency": { "$ref": "#/components/schemas/CurrencyFieldConfig" }, "date": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "dateRange": { "$ref": "#/components/schemas/EmptyFieldConfig" }, "select": { "$ref": "#/components/schemas/ChoiceFieldConfig" }, "radio": { "$ref": "#/components/schemas/ChoiceFieldConfig" }, "checkbox": { "$ref": "#/components/schemas/ChoiceFieldConfig" }, "image": { "$ref": "#/components/schemas/MediaFieldConfig" }, "file": { "$ref": "#/components/schemas/MediaFieldConfig" } }, "x-system-config": { "$ref": "#/components/schemas/SystemFieldConfig" } }, "VersionField": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "email", "phone", "url", "color", "richtext", "number", "currency", "date", "dateRange", "select", "radio", "checkbox", "image", "file" ] }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "nullable": true }, "sortOrder": { "type": "integer" }, "isSystemField": { "type": "boolean" }, "systemKey": { "type": "string", "enum": [ "name", "sku", "brand", "category", "description", "mainImage", null ], "nullable": true }, "config": { "$ref": "#/components/schemas/FieldConfig" } }, "required": [ "id", "key", "name", "type", "required", "placeholder", "sortOrder", "isSystemField", "systemKey", "config" ], "additionalProperties": false }, "VersionGroup": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/VersionField" } } }, "required": [ "id", "name", "isDefault", "sortOrder", "fields" ], "additionalProperties": false }, "TemplateDefinition": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/VersionGroup" } } }, "required": [ "groups" ], "additionalProperties": false, "description": "Immutable version pinned by the product, including after the live template is edited or soft-deleted. Does not require templates:read." }, "NullableTemplateDefinition": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/VersionGroup" } } }, "required": [ "groups" ], "additionalProperties": false, "description": "Immutable version pinned by the product, including after the live template is edited or soft-deleted. Does not require templates:read.", "nullable": true }, "Template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "isSystemDefault": { "type": "boolean" }, "isLibraryDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "boundBrandIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "boundCategoryIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/VersionGroup" } } }, "required": [ "id", "name", "description", "enabled", "isSystemDefault", "isLibraryDefault", "createdAt", "updatedAt", "boundBrandIds", "boundCategoryIds", "groups" ], "additionalProperties": false }, "ProductSummary": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "spu": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "ownerUserId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "draftReason": { "type": "string", "nullable": true }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "templateVersionId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "templateFields": { "type": "object", "additionalProperties": {}, "description": "Map keyed by stable field ID from the pinned definition, not field key/name. Custom image/file values are projected PublicAsset arrays when populated; an empty value may be null, and a field with no stored value may be omitted. Scalars retain their JSON types." }, "cover": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "name": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "pattern": "^\\d+$", "description": "Decimal byte count string; never a JSON number.", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "previewUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrlExpiresAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits.", "nullable": true } }, "required": [ "id", "name", "mimeType", "size", "width", "height", "duration", "previewUrl" ], "additionalProperties": false, "description": "Product media projection. id is FilePath.id, never AssetObject.id or ProductAsset.id. Download properties are omitted unless a current, resolvable product association is downloadable under products:read + products:download and role usable/editable/manage. An authorized unavailable original may return null. Non-image originals never serve as previews. Preview null means unavailable. For a finite key, stored third-party previews with unverifiable expiry return null. Keys without expiry retain eligible stored third-party previews; their lifetime is provider-controlled, without a service-issued TTL guarantee.", "nullable": true }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAsset" } }, "relatedAssets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAsset" } } }, "required": [ "id", "name", "spu", "description", "status", "brandId", "categoryId", "ownerUserId", "publishedAt", "createdAt", "updatedAt", "draftReason", "templateId", "templateVersionId", "templateFields", "cover", "images", "relatedAssets" ], "additionalProperties": false, "description": "List and sync item. templateDefinition is deliberately absent. SKU is named spu on the wire. view_only/usable keys see published products only." }, "ProductDetail": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string" }, "spu": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "ownerUserId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits.", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "updatedAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits." }, "draftReason": { "type": "string", "nullable": true }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "templateVersionId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "templateFields": { "type": "object", "additionalProperties": {}, "description": "Map keyed by stable field ID from the pinned definition, not field key/name. Custom image/file values are projected PublicAsset arrays when populated; an empty value may be null, and a field with no stored value may be omitted. Scalars retain their JSON types." }, "cover": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "name": { "type": "string", "nullable": true }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "pattern": "^\\d+$", "description": "Decimal byte count string; never a JSON number.", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration": { "type": "number", "nullable": true }, "previewUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrl": { "type": "string", "format": "uri", "nullable": true }, "downloadUrlExpiresAt": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp string. Preserve all fractional digits; sync product updatedAt uses six digits.", "nullable": true } }, "required": [ "id", "name", "mimeType", "size", "width", "height", "duration", "previewUrl" ], "additionalProperties": false, "description": "Product media projection. id is FilePath.id, never AssetObject.id or ProductAsset.id. Download properties are omitted unless a current, resolvable product association is downloadable under products:read + products:download and role usable/editable/manage. An authorized unavailable original may return null. Non-image originals never serve as previews. Preview null means unavailable. For a finite key, stored third-party previews with unverifiable expiry return null. Keys without expiry retain eligible stored third-party previews; their lifetime is provider-controlled, without a service-issued TTL guarantee.", "nullable": true }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAsset" } }, "relatedAssets": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAsset" } }, "templateDefinition": { "$ref": "#/components/schemas/NullableTemplateDefinition" } }, "required": [ "id", "name", "spu", "description", "status", "brandId", "categoryId", "ownerUserId", "publishedAt", "createdAt", "updatedAt", "draftReason", "templateId", "templateVersionId", "templateFields", "cover", "images", "relatedAssets", "templateDefinition" ], "additionalProperties": false }, "DeletedId": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "id" ], "additionalProperties": false }, "DeletedTemplateId": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id" ], "additionalProperties": false }, "Visibility": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "visibility": { "type": "string", "enum": [ "visible", "not_visible" ] } }, "required": [ "id", "visibility" ], "additionalProperties": false, "description": "not_visible combines missing, deleted, foreign-library and role-hidden IDs without revealing existence." }, "BrandCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Trimmed before validation." }, "description": { "type": "string", "maxLength": 512, "nullable": true }, "logoUrl": { "type": "string", "maxLength": 512, "description": "Null/empty clears. Only HTTP(S), no credentials, allowlisted MuseDAM CDN or configured storage host; query and fragment removed before storage. No upload; not echoed in reads.", "nullable": true } }, "required": [ "name" ], "additionalProperties": false }, "BrandPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Trimmed before validation." }, "description": { "type": "string", "maxLength": 512, "nullable": true }, "logoUrl": { "type": "string", "maxLength": 512, "description": "Null/empty clears. Only HTTP(S), no credentials, allowlisted MuseDAM CDN or configured storage host; query and fragment removed before storage. No upload; not echoed in reads.", "nullable": true } }, "additionalProperties": false, "minProperties": 1 }, "CategoryCreate": { "type": "object", "properties": { "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?=.*\\S)[^/]+$", "description": "Exact value, not trimmed. Must contain non-whitespace and no slash; unique among live siblings." }, "parentId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Sibling insertion index, no greater than destination sibling count. Omitted: append on create/move, preserve for same parent." }, "description": { "type": "string", "nullable": true }, "iconEmoji": { "type": "string", "maxLength": 16, "nullable": true }, "iconAssetId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true, "description": "Existing same-library CategoryIconAsset ID, not FilePath ID." }, "isEnabled": { "type": "boolean" } }, "required": [ "brandId", "name" ], "additionalProperties": false }, "CategoryPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(?=.*\\S)[^/]+$", "description": "Exact value, not trimmed. Must contain non-whitespace and no slash; unique among live siblings." }, "parentId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Sibling insertion index, no greater than destination sibling count. Omitted: append on create/move, preserve for same parent." }, "description": { "type": "string", "nullable": true }, "iconEmoji": { "type": "string", "maxLength": 16, "nullable": true }, "iconAssetId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true, "description": "Existing same-library CategoryIconAsset ID, not FilePath ID." }, "isEnabled": { "type": "boolean" } }, "additionalProperties": false, "minProperties": 1 }, "TemplateFieldInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Required for new fields; valid identifier. Immutable for existing fields." }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "type": "string", "enum": [ "text", "textarea", "email", "phone", "url", "color", "richtext", "number", "currency", "date", "dateRange", "select", "radio", "checkbox", "image", "file" ] }, "required": { "type": "boolean" }, "placeholder": { "type": "string", "maxLength": 255, "nullable": true }, "sortOrder": { "type": "integer", "minimum": 0 }, "config": { "$ref": "#/components/schemas/FieldConfigInput" }, "isSystemField": { "type": "boolean" }, "systemKey": { "type": "string", "enum": [ "name", "sku", "brand", "category", "description", "mainImage", null ], "nullable": true }, "typeChangeConfirmed": { "type": "boolean" } }, "additionalProperties": false, "description": "New fields require key/name/type. Existing IDs must belong to this group; preserve their key and system identity. System fields cannot be created. Type changes need typeChangeConfirmed where the existing batch rules require it and migrate config for the target type, even when config is omitted. Supply target configuration when required. Omitted new-field defaults: required=false, placeholder=null, config={}, sortOrder=array index. On template creation, custom fields in the first group follow the three protected fields, so their supplied sortOrder or array index is increased by 3. sortOrder values must be unique within each group." }, "TemplateGroupInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateFieldInput" }, "maxItems": 200 } }, "required": [ "name", "fields" ], "additionalProperties": false, "description": "Name is trimmed. Existing ID must belong to this template. Existing groups retain their stored order; new groups append in supplied order. No isDefault or sortOrder input." }, "TemplateCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30 }, "description": { "type": "string", "maxLength": 50, "nullable": true }, "enabled": { "type": "boolean" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateGroupInput" }, "minItems": 1, "maxItems": 200 }, "boundBrandIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 10000 }, "boundCategoryIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 10000 }, "isLibraryDefault": { "type": "boolean" }, "syncStrategy": { "type": "string", "enum": [ "newOnly" ], "default": "newOnly" } }, "required": [ "name", "groups" ], "additionalProperties": false, "description": "Trim name/description. At most 200 fields across all groups. Bindings must be same-library, replace the provided binding set, and may move a binding from another template. When selected brands are nonempty, selected categories must belong to those brands. Only newOnly is supported; never bulk-repin existing products." }, "TemplatePatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30 }, "description": { "type": "string", "maxLength": 50, "nullable": true }, "enabled": { "type": "boolean" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateGroupInput" }, "minItems": 1, "maxItems": 200 }, "boundBrandIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 10000 }, "boundCategoryIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 10000 }, "isLibraryDefault": { "type": "boolean" }, "syncStrategy": { "type": "string", "enum": [ "newOnly" ], "default": "newOnly" } }, "additionalProperties": false, "minProperties": 1, "description": "Omitted groups are preserved; supplied groups replace the entire live set. Preserve stable group/field IDs. Omitted groups/fields are deleted, subject to protected default/system fields. Every successful write creates a new immutable version, including metadata-only updates." }, "TemplateDelete": { "type": "object", "properties": { "replacementForLibraryDefault": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true } }, "additionalProperties": false, "description": "Optional body. If deleting the current library default, this property is required: a different live same-library template ID, or explicit null to clear the default. Historical versions remain available to pinned products." }, "ProductCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Trimmed; optional/empty for draft." }, "spu": { "type": "string", "maxLength": 64, "description": "Trimmed; null/blank clears. Unique within the library, including soft-deleted products.", "nullable": true }, "description": { "type": "string", "nullable": true }, "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "ownerUserId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "templateId": { "type": "string", "minLength": 1, "maxLength": 128, "nullable": true }, "templateFields": { "type": "object", "additionalProperties": {}, "description": "Shallow merge by stable custom field ID; null clears one field. Unknown/system IDs rejected. Types/options validated even for drafts. image/file values are arrays of FilePath IDs or null; not URL/object snapshots. PATCH validates against the pinned version, even if its live template was deleted." }, "coverAssetId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "imageAssetIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 100 }, "relatedAssetIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 100 } }, "additionalProperties": false, "description": "Always creates draft. Explicit templateId must be a live same-library template and takes precedence. When templateId is omitted/null and a non-null categoryId is supplied, resolution follows category or ancestor binding, then that category's brand binding, then library default. When categoryId is omitted or null, only the library default is considered, even if brandId is supplied. If no template resolves, the product has no template. Category must match resulting brand; owner must be a same-team member and defaults to null, not key creator. At most 100 total references across cover/images/related/custom media. Image slots require images; custom media must satisfy pinned count/size/type limits." }, "ProductPatch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Trimmed; optional/empty for draft." }, "spu": { "type": "string", "maxLength": 64, "description": "Trimmed; null/blank clears. Unique within the library, including soft-deleted products.", "nullable": true }, "description": { "type": "string", "nullable": true }, "brandId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "ownerUserId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "templateFields": { "type": "object", "additionalProperties": {}, "description": "Shallow merge by stable custom field ID; null clears one field. Unknown/system IDs rejected. Types/options validated even for drafts. image/file values are arrays of FilePath IDs or null; not URL/object snapshots. PATCH validates against the pinned version, even if its live template was deleted." }, "coverAssetId": { "type": "integer", "minimum": 1, "maximum": 2147483647, "nullable": true }, "imageAssetIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 100 }, "relatedAssetIds": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 100 } }, "additionalProperties": false, "description": "Omitted fields remain unchanged; explicit null clears nullable fields and [] clears lists. templateFields merges; media arrays replace their slot. If imageAssetIds is provided without coverAssetId, first image becomes cover. Published products require products:publish and remain published, with full resulting-state validation. templateId, templateVersionId and status are rejected." }, "ProductStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "published" ] } }, "required": [ "status" ], "additionalProperties": false, "description": "Both products:update and products:publish required for either transition, including same-status requests. Publish validates all required pinned fields and current media; failure is atomic. publishedAt is set on first publication, retained on repeated publication and cleared on draft." }, "VisibilityInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "maxItems": 100 } }, "required": [ "ids" ], "additionalProperties": false, "description": "0..100 IDs. Output preserves input order and duplicates; [] returns []." }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "nullable": true, "enum": [ null ] }, "code": { "type": "string", "enum": [ "invalid_credentials", "authentication_unavailable", "key_inactive", "forbidden", "not_found", "sku_in_use", "code_in_use", "name_in_use", "brand_has_dependents", "category_has_products", "default_template_replacement_required", "idempotency_key_reused", "precondition_failed", "payload_too_large", "validation_failed", "internal_server_error", "write_conflict", "mutation_response_unavailable", "download_unavailable", "download_too_large" ] }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ], "additionalProperties": false } }, "mutationOutcome": { "type": "string", "enum": [ "committed", "replayed" ], "description": "Present only for mutation_response_unavailable. Confirms completion; never blindly repeat the mutation." } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false, "oneOf": [ { "properties": { "code": { "not": { "enum": [ "mutation_response_unavailable" ] } } }, "not": { "required": [ "mutationOutcome" ] } }, { "properties": { "code": { "enum": [ "mutation_response_unavailable" ] } }, "required": [ "mutationOutcome" ] } ] }, "BrandResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Brand" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "CategoryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Category" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "TemplateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Template" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "ProductDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProductDetail" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "LibraryAssetResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/LibraryAsset" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "DeletedIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DeletedId" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "DeletedTemplateIdResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/DeletedTemplateId" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "BrandListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "CategoryListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "TemplateListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "LibraryAssetListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryAsset" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "ProductListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Page" }, { "$ref": "#/components/schemas/SyncPage" } ] } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "VisibilityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Visibility" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "MutationResponseUnavailable": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "required": [ "mutationOutcome" ], "properties": { "code": { "type": "string", "enum": [ "mutation_response_unavailable" ] } } } ] }, "ProductLabelSnapshot": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PositiveId" }, "name": { "type": "string" }, "spu": { "type": "string", "nullable": true } }, "required": [ "id", "name", "spu" ], "additionalProperties": false }, "FileLabelSnapshot": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "$ref": "#/components/schemas/PositiveId" }, "name": { "type": "string" } }, "required": [ "id", "productId", "name" ], "additionalProperties": false }, "ProductShare": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLabelSnapshot" } }, "createdById": { "type": "integer", "nullable": true }, "createdByApiKeyId": { "type": "string", "nullable": true }, "createdByName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time" }, "revokedAt": { "type": "string", "nullable": true, "format": "date-time" }, "allowDownload": { "type": "boolean" }, "hasAccessCode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "canRevoke": { "type": "boolean" } }, "required": [ "id", "url", "products", "createdById", "createdByApiKeyId", "createdByName", "createdAt", "expiresAt", "revokedAt", "allowDownload", "hasAccessCode", "status", "canRevoke" ], "additionalProperties": false, "description": "A team-owned share with an absolute recipient URL and creation-time labels. Access codes and hashes are never returned. Creator key identity and name are attribution snapshots; key lifecycle changes do not revoke the share or cap its lifetime. Recipient content is current published content from the fixed product selection." }, "ProductShareCreate": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "$ref": "#/components/schemas/PositiveId" }, "minItems": 1, "maxItems": 100 }, "expiresInDays": { "type": "integer", "nullable": true, "enum": [ 7, 30, 90, null ] }, "accessCode": { "type": "string", "pattern": "^[0-9]{4}$" }, "allowDownload": { "type": "boolean" } }, "required": [ "productIds", "expiresInDays", "allowDownload" ], "additionalProperties": false }, "RevokedProductShare": { "type": "object", "properties": { "id": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "revokedAt" ], "additionalProperties": false }, "ProductDownloadRecord": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "product_export", "asset_download" ] }, "status": { "type": "string", "enum": [ "requested", "failed" ] }, "actorType": { "type": "string", "enum": [ "member", "external", "api_key" ] }, "actorId": { "type": "integer", "nullable": true }, "apiKeyId": { "type": "string", "nullable": true }, "actorName": { "type": "string" }, "shareId": { "type": "string", "nullable": true }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLabelSnapshot" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileLabelSnapshot" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "status", "actorType", "actorId", "apiKeyId", "actorName", "shareId", "products", "files", "createdAt" ], "additionalProperties": false, "description": "One accepted logical operation, with first-acceptance product/file labels and actor attribution retained. requested records acceptance, not completed transfer or client save. failed records a detected preparation or stream failure and is not reset by a later retry. A product filter retains the complete multi-product operation." }, "ProductDownloadCandidate": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "productId": { "$ref": "#/components/schemas/PositiveId" }, "productName": { "type": "string" }, "category": { "type": "string", "enum": [ "main", "related", "field" ] }, "mimeType": { "type": "string", "nullable": true }, "size": { "type": "string", "nullable": true, "pattern": "^[0-9]+$" }, "downloadable": { "type": "boolean" } }, "required": [ "key", "name", "productId", "productName", "category", "mimeType", "size", "downloadable" ], "additionalProperties": false, "description": "A current selection key and availability metadata. No original URL, signed URL or preview URL is exposed; availability does not guarantee future transfer." }, "ProductDownloadCreate": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assets", "export" ] }, "productIds": { "type": "array", "items": { "$ref": "#/components/schemas/PositiveId" }, "minItems": 1, "maxItems": 100 }, "assetKeys": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "minItems": 1, "maxItems": 200 }, "format": { "type": "string", "enum": [ "xlsx", "csv", "json" ], "default": "xlsx" }, "includeAssetUrls": { "type": "boolean", "default": true }, "locale": { "type": "string", "enum": [ "zh-CN", "en-US", "zh-TW", "ja-JP", "ko-KR", "pt-BR", "ru-RU", "id-ID", "fr-FR", "it-IT", "pl-PL", "vi-VN", "tr-TR", "th-TH", "de-DE", "es-ES", "hi-IN" ], "default": "zh-CN" } }, "required": [ "kind", "productIds" ], "additionalProperties": false, "not": { "properties": { "kind": { "enum": [ "export" ] } }, "required": [ "assetKeys" ] }, "description": "assets selects all originals when assetKeys is omitted, or only the supplied current keys. export rejects assetKeys and produces a localized business table. format, includeAssetUrls and locale apply only to exports; asset downloads accept but ignore them for delivery. Export links default on, require Bearer authentication, and never contain API-key secrets. locale changes system labels/status, not user-authored labels or values." }, "ProductShareResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ProductShare" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "ProductShareListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductShare" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "RevokedProductShareResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/RevokedProductShare" }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "ProductDownloadListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductDownloadRecord" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" }, "pagination": { "$ref": "#/components/schemas/Page" } }, "required": [ "success", "data", "code", "message", "requestId", "pagination" ], "additionalProperties": false }, "ProductDownloadCandidateListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductDownloadCandidate" } }, "code": { "type": "string", "nullable": true, "enum": [ null ] }, "message": { "type": "string", "nullable": true, "enum": [ null ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false }, "AttachmentError": { "type": "object", "description": "Attachment errors preserve the specific error code. mutationOutcome is present after a business record was committed or replayed, even if no bytes were delivered. Reuse the original idempotency key within its retention window for the same logical retry.", "properties": { "success": { "$ref": "#/components/schemas/Error/properties/success" }, "data": { "$ref": "#/components/schemas/Error/properties/data" }, "code": { "$ref": "#/components/schemas/Error/properties/code" }, "message": { "$ref": "#/components/schemas/Error/properties/message" }, "requestId": { "$ref": "#/components/schemas/Error/properties/requestId" }, "details": { "$ref": "#/components/schemas/Error/properties/details" }, "mutationOutcome": { "type": "string", "enum": [ "committed", "replayed" ], "description": "Present after business-record acceptance or reuse, independently of transfer success." } }, "required": [ "success", "data", "code", "message", "requestId" ], "additionalProperties": false } }, "responses": { "Error401_invalid_credentials_key_inactive": { "description": "invalid_credentials: Missing, malformed or unknown bearer credential. Never reveals key existence.; key_inactive: A verified key is disabled, revoked or expired.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_credentials": { "value": { "success": false, "data": null, "code": "invalid_credentials", "message": "Missing, malformed or unknown bearer credential. Never reveals key existence.", "requestId": "11111111-1111-4111-8111-111111111111" } }, "key_inactive": { "value": { "success": false, "data": null, "code": "key_inactive", "message": "A verified key is disabled, revoked or expired.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error403_forbidden": { "description": "forbidden: The current key role/grants do not authorize the action; published mutations may need products:publish.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "value": { "success": false, "data": null, "code": "forbidden", "message": "The current key role/grants do not authorize the action; published mutations may need products:publish.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error404_not_found": { "description": "not_found: The resource is absent, deleted, outside this library or invisible to the key.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "success": false, "data": null, "code": "not_found", "message": "The resource is absent, deleted, outside this library or invisible to the key.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error413_payload_too_large": { "description": "payload_too_large: The request body exceeds 1048576 bytes (1 MiB).", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "value": { "success": false, "data": null, "code": "payload_too_large", "message": "The request body exceeds 1048576 bytes (1 MiB).", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error422_validation_failed": { "description": "validation_failed: Malformed JSON/IDs/query/body, invalid relationships or pinned-field/config/publish rules. Optional details identify fields.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "success": false, "data": null, "code": "validation_failed", "message": "Malformed JSON/IDs/query/body, invalid relationships or pinned-field/config/publish rules. Optional details identify fields.", "requestId": "11111111-1111-4111-8111-111111111111", "details": [ { "field": "templateFields.field_color", "message": "Invalid field value" } ] } } } } } }, "Error500_internal_server_error": { "description": "internal_server_error: Unexpected server failure; report requestId without credentials. The public message does not expose internal details.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "success": false, "data": null, "code": "internal_server_error", "message": "Unexpected server failure; report requestId without credentials. The public message does not expose internal details.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_code_in_use_idempotency_key_reused": { "description": "code_in_use: A generated brand code conflicts; retry with a fresh create request.; idempotency_key_reused: This key and operation already used the idempotency key with a different canonical request.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "code_in_use": { "value": { "success": false, "data": null, "code": "code_in_use", "message": "A generated brand code conflicts; retry with a fresh create request.", "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "value": { "success": false, "data": null, "code": "idempotency_key_reused", "message": "This key and operation already used the idempotency key with a different canonical request.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error412_precondition_failed": { "description": "precondition_failed: If-Match does not match the locked current resource; refetch and reconcile before retry.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "precondition_failed": { "value": { "success": false, "data": null, "code": "precondition_failed", "message": "If-Match does not match the locked current resource; refetch and reconcile before retry.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_brand_has_dependents": { "description": "brand_has_dependents: The brand still has live categories or products; no cascading deletion.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "brand_has_dependents": { "value": { "success": false, "data": null, "code": "brand_has_dependents", "message": "The brand still has live categories or products; no cascading deletion.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_name_in_use_idempotency_key_reused": { "description": "name_in_use: A unique template name or category sibling name conflicts.; idempotency_key_reused: This key and operation already used the idempotency key with a different canonical request.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "name_in_use": { "value": { "success": false, "data": null, "code": "name_in_use", "message": "A unique template name or category sibling name conflicts.", "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "value": { "success": false, "data": null, "code": "idempotency_key_reused", "message": "This key and operation already used the idempotency key with a different canonical request.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_name_in_use": { "description": "name_in_use: A unique template name or category sibling name conflicts.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "name_in_use": { "value": { "success": false, "data": null, "code": "name_in_use", "message": "A unique template name or category sibling name conflicts.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_category_has_products": { "description": "category_has_products: The category subtree still contains live products; no cascading product deletion.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "category_has_products": { "value": { "success": false, "data": null, "code": "category_has_products", "message": "The category subtree still contains live products; no cascading product deletion.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_default_template_replacement_required": { "description": "default_template_replacement_required: Deleting the library default requires replacementForLibraryDefault, including explicit null to clear.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default_template_replacement_required": { "value": { "success": false, "data": null, "code": "default_template_replacement_required", "message": "Deleting the library default requires replacementForLibraryDefault, including explicit null to clear.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_sku_in_use_idempotency_key_reused": { "description": "sku_in_use: The resulting nonempty product spu conflicts with a product in this library, including soft-deleted products.; idempotency_key_reused: This key and operation already used the idempotency key with a different canonical request.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sku_in_use": { "value": { "success": false, "data": null, "code": "sku_in_use", "message": "The resulting nonempty product spu conflicts with a product in this library, including soft-deleted products.", "requestId": "11111111-1111-4111-8111-111111111111" } }, "idempotency_key_reused": { "value": { "success": false, "data": null, "code": "idempotency_key_reused", "message": "This key and operation already used the idempotency key with a different canonical request.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error409_sku_in_use": { "description": "sku_in_use: The resulting nonempty product spu conflicts with a product in this library, including soft-deleted products.; mutation_response_unavailable: Mutation completed but representation is unavailable; mutationOutcome is required and data is null. Do not repeat blindly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "sku_in_use": { "value": { "success": false, "data": null, "code": "sku_in_use", "message": "The resulting nonempty product spu conflicts with a product in this library, including soft-deleted products.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error503_write_conflict": { "description": "The write rolled back due to a deadlock, serialization failure, or lock timeout. Retry after one second using the same create idempotency key.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "schema": { "type": "string", "enum": [ "1" ] }, "description": "Minimum retry delay in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409_mutation_response_unavailable": { "description": "Mutation committed or was replayed, but an authorized representation is unavailable. Reconcile before another mutation.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponseUnavailable" } } } }, "Error409ShareReplay": { "description": "Share creation input differs from the retained idempotent operation.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_reused": { "value": { "success": false, "data": null, "code": "idempotency_key_reused", "message": "This key and operation already used the idempotency key with a different canonical request.", "requestId": "11111111-1111-4111-8111-111111111111" } } } } } }, "Error401_invalid_credentials_key_inactiveAttachment": { "description": "invalid_credentials: Missing, malformed or unknown bearer credential. Never reveals key existence.; key_inactive: A verified key is disabled, revoked or expired.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error403_forbiddenAttachment": { "description": "forbidden: The current key role/grants do not authorize the action; published mutations may need products:publish.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error404_not_foundAttachment": { "description": "not_found: The resource is absent, deleted, outside this library or invisible to the key.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error413ProductDownloadAttachment": { "description": "The request body, file count or combined original size exceeds its limit.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error422_validation_failedAttachment": { "description": "validation_failed: Malformed JSON/IDs/query/body, invalid relationships or pinned-field/config/publish rules. Optional details identify fields.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error500_internal_server_errorAttachment": { "description": "internal_server_error: Unexpected server failure; report requestId without credentials. The public message does not expose internal details.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } }, "Error409ProductDownloadAttachment": { "description": "The original is unavailable or the idempotency key was reused with different input.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" }, "examples": { "recordedFailure": { "value": { "success": false, "data": null, "code": "download_unavailable", "message": "The original download could not be prepared.", "requestId": "11111111-1111-4111-8111-111111111111", "mutationOutcome": "committed" } } } } } }, "Error503_write_conflictAttachment": { "description": "The write rolled back due to a deadlock, serialization failure, or lock timeout. Retry after one second using the same create idempotency key.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "schema": { "type": "string", "enum": [ "1" ] }, "description": "Minimum retry delay in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentError" } } } } } }, "x-error-catalog": { "authentication_unavailable": { "status": 503, "description": "Fresh MuseDAM caller validation is unavailable, timed out, or returned an unusable response. No protected operation executes. Applies to every authenticated endpoint." }, "invalid_credentials": { "status": 401, "description": "Missing, malformed or unknown bearer credential. Never reveals key existence." }, "key_inactive": { "status": 401, "description": "A verified key is disabled, revoked or expired." }, "forbidden": { "status": 403, "description": "The current key role/grants do not authorize the action; published mutations may need products:publish." }, "not_found": { "status": 404, "description": "The resource is absent, deleted, outside this library or invisible to the key." }, "sku_in_use": { "status": 409, "description": "The resulting nonempty product spu conflicts with a product in this library, including soft-deleted products." }, "code_in_use": { "status": 409, "description": "A generated brand code conflicts; retry with a fresh create request." }, "name_in_use": { "status": 409, "description": "A unique template name or category sibling name conflicts." }, "brand_has_dependents": { "status": 409, "description": "The brand still has live categories or products; no cascading deletion." }, "category_has_products": { "status": 409, "description": "The category subtree still contains live products; no cascading product deletion." }, "default_template_replacement_required": { "status": 409, "description": "Deleting the library default requires replacementForLibraryDefault, including explicit null to clear." }, "idempotency_key_reused": { "status": 409, "description": "This key and operation already used the idempotency key with a different canonical request." }, "precondition_failed": { "status": 412, "description": "If-Match does not match the locked current resource; refetch and reconcile before retry." }, "payload_too_large": { "status": 413, "description": "The request body exceeds 1048576 bytes (1 MiB)." }, "validation_failed": { "status": 422, "description": "Malformed JSON/IDs/query/body, invalid relationships or pinned-field/config/publish rules. Optional details identify fields." }, "internal_server_error": { "status": 500, "description": "Unexpected server failure; report requestId without credentials. The public message does not expose internal details." }, "write_conflict": { "status": 503, "description": "The write rolled back after a lock conflict. Retry after Retry-After using the original idempotency key." }, "mutation_response_unavailable": { "status": 409, "description": "The mutation committed or was replayed but its authorized representation is unavailable. mutationOutcome is required; data is null. Do not repeat blindly." }, "download_unavailable": { "status": 409, "description": "The original download could not be prepared; missing originals are not replaced by previews." }, "download_too_large": { "status": 413, "description": "The original download exceeds 200 files or 500 MiB combined." } }, "x-limits": { "requestBodyBytes": 1048576, "pageSizeMaximum": 100, "assetReferencesPerProductWrite": 100, "templateFields": 200, "visibilityIds": 100, "categoryDepth": 10, "categoryNodesPerBrand": 5000, "idempotencyHours": 24, "syncSafetyWindowSeconds": 30 } }