{ "openapi": "3.1.0", "info": { "title": "İncele External API", "version": "1.0.0", "description": "Authenticated account and workspace management. All operations require a scoped account API key. Workspace permissions are checked on every request.", "contact": { "name": "İncele support", "email": "info@incele.ai" } }, "externalDocs": { "url": "https://docs.incele.ai/developers/" }, "servers": [ { "url": "https://api.incele.ai" } ], "components": { "schemas": { "Product": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "information": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "sales": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "link": { "type": "string", "minLength": 1 } }, "required": [ "name", "link" ], "additionalProperties": false } }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "stock": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "brand", "slug", "description", "information", "images", "tags", "sales", "sku", "barcode", "stock", "status", "createdAt", "updatedAt" ], "additionalProperties": false }, "ProductList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "information": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "sales": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "link": { "type": "string", "minLength": 1 } }, "required": [ "name", "link" ], "additionalProperties": false } }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "stock": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "brand", "slug", "description", "information", "images", "tags", "sales", "sku", "barcode", "stock", "status", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "active": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inactive": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outOfStock": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "active", "inactive", "outOfStock" ], "additionalProperties": false } }, "required": [ "products", "pagination", "summary" ], "additionalProperties": false }, "Collection": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "imageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false }, { "type": "null" } ] }, "workspaceId": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "slug": { "type": "string" }, "sku": { "type": "string" }, "stock": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "brand", "slug", "sku", "stock", "status", "images", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "description", "imageId", "image", "workspaceId", "productIds", "tags", "products", "createdAt", "updatedAt" ], "additionalProperties": false }, "CollectionList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "imageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false }, { "type": "null" } ] }, "workspaceId": { "type": "string" }, "productIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "slug": { "type": "string" }, "sku": { "type": "string" }, "stock": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "brand", "slug", "sku", "stock", "status", "images", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "description", "imageId", "image", "workspaceId", "productIds", "tags", "products", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false } }, "required": [ "collections", "pagination" ], "additionalProperties": false }, "Tag": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "TagList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false } }, "required": [ "tags", "pagination" ], "additionalProperties": false }, "MediaList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "key": { "type": "string" }, "createdAt": { "type": "string" }, "usageCount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "url": { "default": "", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "size", "kind", "key", "createdAt", "usageCount", "url" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unused": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "multiLinked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "unused", "linked", "multiLinked" ], "additionalProperties": false } }, "required": [ "media", "pagination", "summary" ], "additionalProperties": false }, "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string" }, "message": { "type": "string" }, "fieldErrors": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "status", "code", "message" ], "additionalProperties": false }, "ProductQuestion": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "text" ], "additionalProperties": false }, "ProductQuestionSet": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "text" ], "additionalProperties": false } }, "usesDefaults": { "type": "boolean" } }, "required": [ "questions", "usesDefaults" ], "additionalProperties": false }, "QuestionLibrary": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "text" ], "additionalProperties": false } } }, "required": [ "questions" ], "additionalProperties": false }, "AiSettings": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fastEnabled": { "type": "boolean" }, "comprehensiveEnabled": { "type": "boolean" }, "sector": { "type": "string", "enum": [ "AUTO", "GENERAL", "BEAUTY", "TEXTILE" ] } }, "required": [ "fastEnabled", "comprehensiveEnabled", "sector" ], "additionalProperties": false }, "FeedbackList": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "feedbacks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" }, "createdAt": { "type": "string" }, "workspaceName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "userId", "message", "createdAt", "workspaceName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false } }, "required": [ "feedbacks", "pagination" ], "additionalProperties": false }, "UsageReport": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "usage": { "type": "array", "items": { "type": "object", "properties": { "actorType": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "lastUsedAt": { "type": "string" }, "events": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productRequests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "routineRequests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "faceAnalyses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comprehensiveRequests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productViews": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "visits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "actorType", "userId", "name", "lastUsedAt", "events", "requests", "credits", "productRequests", "routineRequests", "faceAnalyses", "comprehensiveRequests", "productViews", "visits" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "events": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "events", "requests", "credits" ], "additionalProperties": false }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "usage", "pagination", "totals", "from", "to" ], "additionalProperties": false }, "UsageEvents": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actorType": { "type": "string" }, "eventName": { "type": "string" }, "endpoint": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": "string" }, "creditDelta": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "modelKey": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "userId", "actorType", "eventName", "endpoint", "resourceType", "resourceId", "creditDelta", "modelKey", "status", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ], "additionalProperties": false } }, "required": [ "events", "pagination" ], "additionalProperties": false } }, "securitySchemes": { "integrationToken": { "type": "http", "scheme": "bearer", "description": "Create a scoped account API key in Home → Integrations. Keep write keys on your backend." } } }, "paths": { "/v1/workspaces/{workspaceId}/products": { "get": { "operationId": "list_products", "summary": "List all products, including inactive products, with pagination, search, and status filters.", "tags": [ "products" ], "x-required-scope": "products:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_product", "summary": "Create a product. Data: name, brand, sku, barcode, stock, status (ACTIVE/INACTIVE/DELETED), description, information, imageIds, tagIds, sales. Existing business validation applies.", "tags": [ "products" ], "x-required-scope": "products:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "brand": { "type": "string", "minLength": 1, "maxLength": 300 }, "sku": { "type": "string", "minLength": 1, "maxLength": 300 }, "barcode": { "type": "string", "minLength": 1, "maxLength": 300 }, "stock": { "type": "integer", "minimum": 0, "maximum": 999999 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "description": { "default": "", "type": "string", "maxLength": 100000 }, "information": { "type": "string", "maxLength": 500000 }, "imageIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "tagIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "sales": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "link": { "type": "string", "minLength": 1 } }, "required": [ "name", "link" ], "additionalProperties": false } } }, "required": [ "name", "brand", "sku", "barcode", "stock", "status", "description", "information", "imageIds", "tagIds", "sales" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/products/{id}": { "get": { "operationId": "get_product", "summary": "Fetch one product owned by this workspace, including inactive products.", "tags": [ "products" ], "x-required-scope": "products:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update_product", "summary": "Update a product using its current full editable values; read it first. Same data fields as create_product.", "tags": [ "products" ], "x-required-scope": "products:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "brand": { "type": "string", "minLength": 1, "maxLength": 300 }, "sku": { "type": "string", "minLength": 1, "maxLength": 300 }, "barcode": { "type": "string", "minLength": 1, "maxLength": 300 }, "stock": { "type": "integer", "minimum": 0, "maximum": 999999 }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "description": { "default": "", "type": "string", "maxLength": 100000 }, "information": { "type": "string", "maxLength": 500000 }, "imageIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "tagIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "sales": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "link": { "type": "string", "minLength": 1 } }, "required": [ "name", "link" ], "additionalProperties": false } } }, "required": [ "name", "brand", "sku", "barcode", "stock", "status", "description", "information", "imageIds", "tagIds", "sales" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_product", "summary": "Permanently delete a product and its associations.", "tags": [ "products" ], "x-required-scope": "products:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/collections": { "get": { "operationId": "list_collections", "summary": "List collections with pagination and search.", "tags": [ "collections" ], "x-required-scope": "collections:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionList" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_collection", "summary": "Create collection. Data: name, description, tagIds, imageId. Add products with add_collection_product.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "default": "", "type": "string", "maxLength": 100000 }, "imageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "tagIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "required": [ "name", "description", "tagIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/collections/{id}": { "put": { "operationId": "update_collection", "summary": "Update collection with its full editable values.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "default": "", "type": "string", "maxLength": 100000 }, "imageId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "tagIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "required": [ "name", "description", "tagIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_collection", "summary": "Permanently delete collection.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "get_collection", "summary": "Fetch one collection including its product and tag associations.", "tags": [ "collections" ], "x-required-scope": "collections:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/tags": { "get": { "operationId": "list_tags", "summary": "List tags with pagination and search.", "tags": [ "tags" ], "x-required-scope": "tags:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_tag", "summary": "Create tag. Data: name.", "tags": [ "tags" ], "x-required-scope": "tags:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/tags/{id}": { "put": { "operationId": "update_tag", "summary": "Update tag with its full editable values.", "tags": [ "tags" ], "x-required-scope": "tags:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_tag", "summary": "Permanently delete tag.", "tags": [ "tags" ], "x-required-scope": "tags:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "get_tag", "summary": "Fetch one tag.", "tags": [ "tags" ], "x-required-scope": "tags:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates": { "get": { "operationId": "list_templates", "summary": "List supported website template keys.", "tags": [ "Account" ], "x-required-scope": "website:read", "security": [ { "integrationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/collections/{id}/products": { "get": { "operationId": "list_collection_products", "summary": "List products in a collection.", "tags": [ "collections" ], "x-required-scope": "collections:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/collections/{id}/products/{productId}": { "post": { "operationId": "add_collection_product", "summary": "add a workspace product in a workspace collection.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "remove_collection_product", "summary": "remove a workspace product in a workspace collection.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/products/{id}/tags/{tagId}": { "post": { "operationId": "add_product_tag", "summary": "add a workspace tag on a workspace product.", "tags": [ "products" ], "x-required-scope": "products:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "remove_product_tag", "summary": "remove a workspace tag on a workspace product.", "tags": [ "products" ], "x-required-scope": "products:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/collections/{id}/tags/{tagId}": { "post": { "operationId": "add_collection_tag", "summary": "add a workspace tag on a workspace collection.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "remove_collection_tag", "summary": "remove a workspace tag on a workspace collection.", "tags": [ "collections" ], "x-required-scope": "collections:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/media": { "get": { "operationId": "list_media", "summary": "List uploaded images with pagination, usage, and search.", "tags": [ "media" ], "x-required-scope": "media:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaList" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "upload_media", "summary": "Upload an image as base64 (maximum 3 MiB decoded). Returns media id for imageIds fields. REST also supports multipart upload at /v1/media/upload.", "tags": [ "media" ], "x-required-scope": "media:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 200 }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif", "image/avif" ] }, "base64": { "type": "string", "minLength": 4, "maxLength": 4194304 } }, "required": [ "fileName", "mimeType", "base64" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/media/{id}": { "get": { "operationId": "get_media", "summary": "Fetch uploaded media metadata.", "tags": [ "media" ], "x-required-scope": "media:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replace_media", "summary": "Replace an uploaded image while retaining its media id.", "tags": [ "media" ], "x-required-scope": "media:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 200 }, "mimeType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif", "image/avif" ] }, "base64": { "type": "string", "minLength": 4, "maxLength": 4194304 } }, "required": [ "fileName", "mimeType", "base64" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_media", "summary": "Delete uploaded media and remove its references.", "tags": [ "media" ], "x-required-scope": "media:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceId}/workspace": { "get": { "operationId": "get_workspace", "summary": "Read the selected workspace profile, business contact information and agent instructions.", "tags": [ "workspace" ], "x-required-scope": "workspace:read", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation; resource or paginated resource list." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicting resource or duplicate identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected service failure. Internal details are hidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update_workspace", "summary": "Update workspace profile fields: name, subDomain, billingEmail, billingPhone, billingGsmCountryCode, isVisible and mainAgentPrompt. Billing email changes require an existing verification code; subdomain validation/cooldowns apply. Ownership, wallet and access policy are not delegated.", "tags": [ "workspace" ], "x-required-scope": "workspace:write", "security": [ { "integrationToken": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "subDomain": { "type": "string", "minLength": 3, "maxLength": 32, "pattern": "^(?!-)[a-z0-9-]+(?