{ "openapi": "3.1.0", "info": { "title": "Savanto API", "version": "2.0.0", "description": "The Savanto REST API gives you programmatic access to AI-powered search, chat, recommendations, and content management.\n\n## Authentication\nAll endpoints require a valid API key passed via the `Authorization` header:\n```\nAuthorization: Bearer \n```\n\nKey types:\n- **Secret keys** (`if_sk_...`) — Full API access. Use server-side only.\n- **Publishable keys** (`if_pk_...`) — Limited to search, chat, and feedback. Safe for client-side." }, "servers": [ { "url": "https://api.savanto.ai", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (secret or publishable) passed as Bearer token" } }, "schemas": { "ChatResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": {} }, "required": ["object", "requestId"] }, "ChatStreamChunk": { "type": "object", "properties": { "type": { "type": "string" }, "data": {} }, "required": ["type"] }, "ErrorResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": ["error"] }, "requestId": { "type": "string" }, "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "authorization_error", "rate_limit_error", "api_error" ] }, "message": { "type": "string" }, "code": { "type": "string" }, "param": { "type": ["string", "null"] } }, "required": ["type", "message", "code", "param"] } }, "required": ["object", "requestId", "error"] }, "ChatRequest": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "stream": { "type": "boolean" }, "userJwt": { "type": "string" }, "productFilter": { "type": "object", "additionalProperties": {} }, "postFilter": { "type": "object", "additionalProperties": {} }, "promptId": { "type": "string" }, "offerResponse": {}, "visitorId": { "type": "string" }, "source": { "type": "string", "maxLength": 64 } }, "required": ["message", "threadId"] }, "StartCrawlRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "example": "https://example.com" }, "workspaceId": { "type": "string" }, "maxPages": { "type": "integer", "exclusiveMinimum": 0 }, "isOnboarding": { "type": "boolean" }, "strategy": { "type": "string", "enum": ["full", "smart"] }, "trigger": { "type": "string", "enum": ["manual", "scheduled"] } }, "required": ["url"] }, "SingleScrapeRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "example": "https://example.com/page" }, "workspaceId": { "type": "string" } }, "required": ["url"] }, "UpdateCrawlConfigRequest": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "strategy": { "type": "string", "enum": ["full", "smart"] }, "schedule": { "type": "string", "enum": ["none", "daily", "weekly", "monthly"] }, "preferredHour": { "type": "integer", "minimum": 0, "maximum": 23 }, "maxPages": { "type": "integer", "exclusiveMinimum": 0 }, "excludePatterns": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 }, "includePatterns": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 }, "overagesEnabled": { "type": "boolean" } } }, "EnrollCrawlNotificationRequest": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email", "example": "merchant@example.com", "description": "Recipient for the crawl-complete email. Caller is responsible for validating the signed-in user owns this address." } }, "required": ["email"] }, "ScrapeRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "example": "https://example.com/page" }, "action": { "type": "string", "enum": ["scrape", "delete"], "example": "scrape" }, "source": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": ["url"] }, "ProductInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "maxLength": 200000 }, "searchableText": { "type": "string", "maxLength": 200000 }, "excerpt": { "type": "string", "maxLength": 1000 }, "price": { "type": ["number", "null"], "minimum": 0 }, "salePrice": { "type": ["number", "null"], "minimum": 0 }, "regularPrice": { "type": ["number", "null"], "minimum": 0 }, "onSale": { "type": "boolean" }, "priceMin": { "type": ["number", "null"], "minimum": 0 }, "priceMax": { "type": ["number", "null"], "minimum": 0 }, "stockQuantity": { "type": ["number", "null"], "minimum": 0 }, "stockStatus": { "type": "string", "enum": ["instock", "outofstock", "onbackorder"] }, "sku": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": ["simple", "variable", "grouped", "external"] }, "weight": { "type": ["number", "null"], "minimum": 0 }, "dimensions": { "type": ["object", "null"], "properties": { "length": { "type": ["number", "null"], "minimum": 0 }, "width": { "type": ["number", "null"], "minimum": 0 }, "height": { "type": ["number", "null"], "minimum": 0 } } }, "rating": { "type": ["number", "null"], "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "number", "minimum": 0 }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "brands": { "type": "array", "items": { "type": "string" } }, "image": { "type": ["string", "null"] }, "url": { "type": "string" }, "status": { "type": "string", "maxLength": 50 }, "visibility": { "type": "string", "maxLength": 50 }, "featured": { "type": "boolean" }, "virtual": { "type": "boolean" }, "downloadable": { "type": "boolean" }, "attributes": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 50 } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 50 } ] } }, "source": { "type": "string", "maxLength": 50 }, "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] } }, "required": ["id", "name"] }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content": { "type": "string" }, "excerpt": { "type": "string" }, "searchableText": { "type": "string" }, "price": { "type": ["number", "null"] }, "salePrice": { "type": ["number", "null"] }, "regularPrice": { "type": ["number", "null"] }, "onSale": { "type": "boolean" }, "priceMin": { "type": ["number", "null"] }, "priceMax": { "type": ["number", "null"] }, "stockQuantity": { "type": ["number", "null"] }, "stockStatus": { "type": "string", "enum": ["instock", "outofstock", "onbackorder"] }, "sku": { "type": "string" }, "type": { "type": "string", "enum": ["simple", "variable", "grouped", "external"] }, "weight": { "type": ["number", "null"] }, "dimensions": { "type": ["object", "null"], "properties": { "length": { "type": ["number", "null"] }, "width": { "type": ["number", "null"] }, "height": { "type": ["number", "null"] } } }, "rating": { "type": ["number", "null"] }, "reviewCount": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "brands": { "type": "array", "items": { "type": "string" } }, "image": { "type": ["string", "null"] }, "url": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string" }, "featured": { "type": "boolean" }, "virtual": { "type": "boolean" }, "downloadable": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "attributes": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "source": { "type": "string" }, "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] }, "score": { "type": "number" }, "matchingChunks": { "type": "array", "items": { "type": "object", "properties": { "chunkText": { "type": "string" }, "order": { "type": "number" } }, "required": ["chunkText", "order"] } } }, "required": ["id", "name"] }, "Pagination": { "type": "object", "properties": { "total": { "type": ["number", "null"] }, "limit": { "type": "number" }, "hasMore": { "type": "boolean" }, "offset": { "type": "number" }, "cursor": { "type": ["string", "null"] } }, "required": ["total", "limit", "hasMore"] }, "ProductSearchRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 200000 }, "filters": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": {}, "additionalProperties": {} } ] } }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "useAgent": { "type": "boolean" }, "facetFields": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": ["categories", "brands", "tags", "stockStatus", "onSale", "featured", "type", "priceRanges"] }, { "type": "string", "pattern": "^(attributes|metadata)\\..+$", "maxLength": 128 } ] }, "maxItems": 20, "description": "Fields to return aggregate counts for. Valid values: categories, brands, tags, stockStatus, onSale, featured, type, priceRanges, attributes.{key}, metadata.{key}. Facet keys in the response match the requested field names." }, "searchContext": { "type": "string", "enum": ["widget", "native", "chat", "api", "internal", "unknown"] }, "trackAnalytics": { "type": "boolean" } }, "required": ["text"] }, "BulkOperation": { "type": "object", "properties": { "object": { "type": "string", "enum": ["bulk_operation"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": ["error"] } } }, "required": ["processed", "succeeded", "failed"] } }, "required": ["object", "requestId", "data"] }, "DeleteResponse": { "type": "object", "properties": { "object": { "type": "string" }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["id", "deleted"] } }, "required": ["object", "requestId", "data"] }, "PostInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "maxLength": 200000 }, "searchableText": { "type": "string", "maxLength": 200000 }, "excerpt": { "type": "string", "maxLength": 1000 }, "postType": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": ["publish", "draft", "private", "pending"] }, "authorId": { "type": "string", "maxLength": 100 }, "authorName": { "type": "string", "maxLength": 200 }, "publishedAt": { "type": ["string", "null"] }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "featuredImage": { "type": ["string", "null"] }, "source": { "type": "string", "maxLength": 50 }, "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string", "maxLength": 5000 }, "maxItems": 500 } ] } }, "attributes": { "type": ["object", "null"], "additionalProperties": {} } }, "required": ["id", "title"] }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "excerpt": { "type": "string" }, "searchableText": { "type": "string" }, "postType": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "wordCount": { "type": "number" }, "readingTime": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" }, "featuredImage": { "type": ["string", "null"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "publishedAt": { "type": ["string", "null"] }, "attributes": { "type": ["object", "null"], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "source": { "type": "string" }, "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] }, "score": { "type": "number" }, "matchingChunks": { "type": "array", "items": { "type": "object", "properties": { "chunkText": { "type": "string" }, "order": { "type": "number" } }, "required": ["chunkText", "order"] } } }, "required": ["id", "title"] }, "PostSearchRequest": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 200000 }, "filters": { "type": "object", "properties": { "postType": { "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "enum": ["publish", "draft", "private", "pending"] }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": {} }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "searchContext": { "type": "string", "enum": ["widget", "native", "chat", "api", "internal", "unknown"] }, "trackAnalytics": { "type": "boolean" } }, "required": ["text"] }, "ThreadSearchRequest": { "type": "object", "properties": { "query": { "type": "string" }, "userId": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "default": 0 }, "minMessages": { "type": "integer", "minimum": 0 }, "maxMessages": { "type": "integer", "minimum": 0 }, "minTokens": { "type": "integer", "minimum": 0 }, "maxTokens": { "type": "integer", "minimum": 0 }, "hasUnresolvedQueries": { "type": "boolean" }, "sortBy": { "type": "string", "enum": ["timestamp", "messageCount", "tokenCount"], "default": "timestamp" }, "sortOrder": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } } }, "ThreadExportRequest": { "type": "object", "properties": { "format": { "type": "string", "enum": ["json", "csv"], "default": "json" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "userId": { "type": "string" }, "includeContent": { "type": "boolean", "default": false } } }, "ThreadBulkDeleteRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": ["ids"] }, "FeedbackSubmission": { "type": "object", "properties": { "rating": { "type": "string", "enum": ["positive", "negative"] }, "source": { "type": "string", "enum": ["chat_response", "recommendation", "search_result", "content"] }, "threadId": { "type": "string" }, "contentId": { "type": "string" }, "contentType": { "type": "string", "enum": ["product", "post", "prompt", "message", "general"] }, "comment": { "type": "string" }, "category": { "type": "string" }, "queryText": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "userJwt": { "type": "string" }, "messageId": { "type": "string" } }, "required": ["rating"] }, "PromptInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 1000 }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "cannedResponse": { "type": "string", "maxLength": 5000 }, "responseFormat": { "type": "string", "enum": ["markdown", "text", "html"] }, "overrideMode": { "type": "string", "enum": ["override", "fallback"] }, "postIds": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50 }, "productIds": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 50 }, "followUpIds": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 20 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 20 }, "categories": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10 }, "status": { "type": "string", "maxLength": 50 }, "priority": { "type": "integer", "minimum": 0, "maximum": 9999 }, "icon": { "type": "string", "maxLength": 10 }, "activeFrom": { "type": "string", "maxLength": 50 }, "activeTo": { "type": "string", "maxLength": 50 }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["prompt"], "additionalProperties": false }, "Prompt": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "prompt": { "type": "string" }, "description": { "type": "string" }, "cannedResponse": { "type": "string" }, "responseFormat": { "type": "string" }, "overrideMode": { "type": "string" }, "postIds": { "type": "array", "items": { "type": "string" } }, "productIds": { "type": "array", "items": { "type": "string" } }, "followUpIds": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "priority": { "type": "number" }, "icon": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "activeFrom": { "type": "string" }, "activeTo": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["prompt"] }, "BulkWebhookStatusInput": { "type": "object", "properties": { "webhookIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "status": { "type": "string", "enum": ["active", "inactive", "suspended"] } }, "required": ["webhookIds", "status"] }, "CreateWebhookInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "minLength": 1, "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": { "type": "string", "maxLength": 1000 }, "method": { "type": "string", "enum": ["POST", "PUT", "PATCH"] }, "secret": { "type": "string" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "eventFilters": { "type": "object", "additionalProperties": {} }, "payloadTemplate": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive"] }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "backoffStrategy": { "type": "string", "enum": ["linear", "exponential"] }, "initialDelayMs": { "type": "integer", "minimum": 100 }, "maxDelayMs": { "type": "integer", "minimum": 1000 } } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "authType": { "type": "string", "enum": ["none", "bearer", "basic", "custom", "apiKey"] }, "authConfig": { "type": "object", "properties": { "bearerToken": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "headerName": { "type": "string" }, "headerValue": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyHeader": { "type": "string" } } }, "schedule": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" } }, "required": ["enabled", "cronExpression", "timezone"] }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["name", "url", "events"] }, "UpdateWebhookInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": { "type": "string", "maxLength": 1000 }, "method": { "type": "string", "enum": ["POST", "PUT", "PATCH"] }, "secret": { "type": "string" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "eventFilters": { "type": "object", "additionalProperties": {} }, "payloadTemplate": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive", "suspended"] }, "retryPolicy": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "backoffStrategy": { "type": "string", "enum": ["linear", "exponential"] }, "initialDelayMs": { "type": "integer", "minimum": 100 }, "maxDelayMs": { "type": "integer", "minimum": 1000 } } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "authType": { "type": "string", "enum": ["none", "bearer", "basic", "custom", "apiKey"] }, "authConfig": { "type": "object", "properties": { "bearerToken": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "headerName": { "type": "string" }, "headerValue": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyHeader": { "type": "string" } } }, "schedule": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" } }, "required": ["enabled", "cronExpression", "timezone"] }, "metadata": { "type": "object", "additionalProperties": {} } } }, "TaxonomyInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "minLength": 1, "maxLength": 200 }, "taxonomyName": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_-]+$" }, "description": { "type": "string", "maxLength": 1000 }, "count": { "type": "integer", "minimum": 0 }, "parent": { "type": "integer", "minimum": 0 }, "meta": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "source": { "type": "string" }, "termId": { "type": "integer" }, "taxonomyLabel": { "type": "string" }, "hierarchy": { "type": "array", "items": { "type": "string" } }, "thumbnailUrl": { "type": "string" }, "displayType": { "type": "string" }, "isProductAttribute": { "type": "boolean" }, "attributeType": { "type": "string" }, "swatch": {}, "type": { "type": "string" } }, "required": ["id", "name", "slug", "taxonomyName"] }, "Taxonomy": { "type": "object", "properties": { "id": { "type": "string" }, "taxonomyName": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "count": { "type": "number" }, "parent": { "type": "number" }, "meta": { "type": "object", "additionalProperties": {} }, "hierarchyPath": { "type": "string" }, "hierarchyLevel": { "type": "number" }, "isHierarchical": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "syncVersion": { "type": "number" }, "source": { "type": "string" } }, "required": ["id", "taxonomyName", "name", "slug"] }, "RecommendationRequest": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "basketAffinity": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "frequency": { "type": "number", "exclusiveMinimum": 0 } }, "required": ["productId", "frequency"] } }, "complimentaryProducts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "userId": { "type": "string", "minLength": 1 }, "weights": { "type": "object", "properties": { "similarProducts": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 }, "basketAffinity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 }, "memoryBased": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 } } }, "maxRecommendations": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "excludeProductIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "productFilter": { "type": "object", "additionalProperties": {} } }, "required": ["productId"] }, "TenantStatus": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive", "suspended"] }, "publishableKey": { "type": ["string", "null"] }, "jwtSecret": { "type": "string" } }, "additionalProperties": {} }, "TenantWhoami": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "apiKeyId": { "type": "string" }, "keyType": { "type": "string", "enum": ["secret", "publishable"] }, "workspaceId": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [] }, "label": { "type": "string" } }, "required": ["tenantId", "tier", "apiKeyId", "keyType", "workspaceId"] }, "UpdateTenantFeaturesRequest": { "type": "object", "properties": { "overagesEnabled": { "type": "boolean" } }, "required": ["overagesEnabled"] }, "WorkspaceSummary": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "platform": { "type": "string", "enum": ["wordpress", "shopify", "custom"] }, "status": { "type": "string", "enum": ["active", "deleting"] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["workspaceId"], "additionalProperties": {} }, "CreateWorkspaceRequest": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 3, "maxLength": 50, "pattern": "^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$" }, "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" }, "siteUrl": { "type": "string" } }, "required": ["workspaceId"] }, "UpdateWorkspaceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "domain": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "GetUploadUrlRequest": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255 }, "fileSize": { "type": "integer", "exclusiveMinimum": 0 } }, "required": ["fileName", "contentType", "fileSize"] }, "UpdateMcpConfigRequest": { "type": "object", "properties": { "ordersUri": { "type": "string", "format": "uri" }, "inventoryUri": { "type": "string", "format": "uri" }, "shippingUri": { "type": "string", "format": "uri" }, "supportUri": { "type": "string", "format": "uri" }, "accountUri": { "type": "string", "format": "uri" }, "analyticsUri": { "type": "string", "format": "uri" } }, "additionalProperties": { "type": "string", "maxLength": 2048, "format": "uri" } }, "StoreLiveAgentCredentialsRequest": { "type": "object", "properties": { "provider": { "type": "string", "enum": ["zendesk", "intercom", "drift", "slack"] }, "apiToken": { "type": "string" }, "webhookSecret": { "type": "string" }, "subdomain": { "type": "string" }, "integrationId": { "type": "string" }, "botToken": { "type": "string" }, "channelId": { "type": "string" }, "signingSecret": { "type": "string" }, "availabilitySchedule": { "type": ["string", "null"] } }, "required": ["provider"] }, "UpdateLiveAgentScheduleRequest": { "type": "object", "properties": { "schedule": { "type": ["string", "null"], "maxLength": 500 } }, "required": ["schedule"] }, "DeprovisionResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "purge": { "type": "object", "properties": { "success": { "type": "boolean" }, "openSearchDeleted": { "type": "number" }, "dynamoDbDeleted": { "type": "number" } } } }, "required": ["success"] }, "DeprovisionRequest": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Required when authenticated as admin. Ignored when authenticated with a tenant API key (tenant:admin required) — the tenant is derived from the auth context." }, "siteUrl": { "type": "string", "description": "If provided, only this workspace is removed. Omit to fully deprovision the tenant (used by the Shopify app on uninstall)." }, "purgeData": { "type": "boolean", "description": "When true, hard-deletes indexed data for the tenant/workspace." } } }, "CreateKeyRequest": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "keyType": { "type": "string", "enum": ["secret", "publishable"] } }, "required": ["label"] }, "RotateKeyRequest": { "type": "object", "properties": { "label": { "type": "string" } } }, "ProvisionResult": { "type": "object", "properties": { "tenantId": { "type": "string" }, "workspaceId": { "type": "string" }, "isNew": { "type": "boolean" }, "tier": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyId": { "type": "string" }, "publishableKey": { "type": "string" }, "publishableKeyId": { "type": "string" } }, "required": ["tenantId", "workspaceId", "isNew", "tier"] }, "ShopifyProvisionRequest": { "type": "object", "properties": { "shop": { "type": "string", "minLength": 1, "example": "mystore.myshopify.com", "description": "Shopify shop domain." }, "tier": { "type": "string", "example": "personal", "description": "Billing tier chosen during install." }, "shopName": { "type": "string", "description": "Human-readable shop name." }, "ownerEmail": { "type": "string", "format": "email", "description": "Shop owner email (used for billing + outreach)." }, "existingTenantId": { "type": "string", "description": "If set, link the new workspace to this existing tenant." } }, "required": ["shop"] }, "AdminClaimTenantRequest": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 }, "ownerEmail": { "type": "string", "format": "email" } }, "required": ["ownerId"] }, "AdminUpdateOwnerEmailRequest": { "type": "object", "properties": { "ownerEmail": { "type": "string", "format": "email" } }, "required": ["ownerEmail"] }, "AdminUpdateSubscriptionRequest": { "type": "object", "properties": { "status": { "type": "string" }, "tier": { "type": "string" }, "providerCustomerId": { "type": "string" } } }, "ComplianceAuditResponse": { "type": "object", "properties": { "requestId": { "type": "string", "example": "cmpl_01HZX1VQJ3..." }, "status": { "type": "string", "enum": ["queued", "completed", "failed"], "example": "queued" }, "requestType": { "type": "string", "enum": ["customer_redact", "customer_data_request"] }, "requestedAt": { "type": "string", "format": "date-time", "example": "2026-04-16T14:22:03.000Z" }, "threadTaskId": { "type": "string", "description": "OpenSearch _tasks id for thread-doc deletion (reconciler polls this)." }, "memoryTaskId": { "type": "string" }, "summary": { "type": "string" } }, "required": ["requestId", "status", "requestType", "requestedAt"] }, "CustomerRedactRequest": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/ComplianceCustomerId" }, "caller": { "$ref": "#/components/schemas/ComplianceCaller" }, "workspaceId": { "type": "string", "example": "ws_abc123", "description": "If provided, limit redaction to a single workspace. Defaults to tenant scope." } }, "required": ["customer", "caller"] }, "ComplianceCustomerId": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "[email protected]", "description": "Customer email (case-insensitive match)." }, "phone": { "type": "string", "minLength": 1, "example": "+15551234567", "description": "Customer phone in E.164 format." }, "customerId": { "type": "string", "minLength": 1, "example": "12345", "description": "Platform-specific customer identifier (e.g. Shopify customer.id)." } } }, "ComplianceCaller": { "type": "object", "properties": { "source": { "type": "string", "enum": ["shopify", "wordpress", "dashboard", "sdk"], "example": "shopify", "description": "Which integration fired the request." }, "shopDomain": { "type": "string", "example": "acme.myshopify.com", "description": "Merchant shop domain (Shopify webhooks only)." }, "externalId": { "type": "string", "example": "99988877", "description": "Upstream request id used to make this call idempotent on retry." } }, "required": ["source"] }, "CustomerDataRequest": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/ComplianceCustomerId" }, "caller": { "$ref": "#/components/schemas/ComplianceCaller" }, "workspaceId": { "type": "string", "example": "ws_abc123" } }, "required": ["customer", "caller"] } }, "parameters": {} }, "paths": { "/chat": { "post": { "tags": ["Chat"], "summary": "Send a chat message", "description": "Send a visitor message through the full multi-agent pipeline: triage classifies intent, query agents retrieve grounded context from the product / post indexes (plus any custom domain agents), and response agents synthesise a grounded answer with product cards or cited content. The response is streamed as NDJSON when `stream: true` (each line is one of `{ type: \"token\", ... }`, `{ type: \"product\", ... }`, `{ type: \"done\" }`), or returned as a single JSON object when `stream: false`. Pass `threadId` to continue a conversation (memories and prior turns are loaded); omit it for a fresh one. Respects the workspace's active persona / system-prompt configuration.", "operationId": "chat", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "200": { "description": "Chat response (JSON or NDJSON stream)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ChatStreamChunk" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl": { "post": { "tags": ["Crawl"], "summary": "Start a website crawl", "description": "Enqueue a crawl of the given root URL for the workspace in `X-Workspace-ID`. The crawler discovers pages via sitemap + link graph, classifies each page (product, product listing, or general content), and indexes products into `savanto-products` and content into `savanto-posts`. This call is asynchronous and returns immediately with a `crawlId`; poll `GET /crawl/{crawlId}/status` to track progress or subscribe to the email notification endpoint to be pinged when it completes. Starting a new crawl while one is already running for the same workspace will be rejected with 409 — cancel the running one first.", "operationId": "startCrawl", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCrawlRequest" } } } }, "responses": { "200": { "description": "Crawl started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "crawlId": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": ["crawlId", "workspaceId"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/scrape": { "post": { "tags": ["Crawl"], "summary": "Scrape a single page", "description": "Scrape and index a single page via the crawl queue.", "operationId": "scrapeSinglePage", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleScrapeRequest" } } } }, "responses": { "200": { "description": "Scrape started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scrapeId": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": ["scrapeId", "workspaceId"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/config": { "get": { "tags": ["Crawl"], "summary": "Get crawl configuration", "description": "Return the persisted crawl configuration for the workspace (strategy, schedule, include / exclude URL patterns, max-pages budget, user-agent override). Use before a crawl to verify the active rules, or before an `update_crawl_config` call to preserve fields you are not changing.", "operationId": "getCrawlConfig", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Crawl config", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "config": {} } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": ["Crawl"], "summary": "Update crawl configuration", "description": "Replace the crawl configuration for the workspace. Common fields: `strategy` (`full` reindexes everything, `smart` skips pages whose content hash matches the previous crawl), `schedule` (cron-like), `includePatterns` / `excludePatterns` (glob URL filters), `maxPages` (safety cap). Omitted fields are set to their defaults — if you only want to tweak one setting, `GET /crawl/config` first and merge. Changes take effect on the next crawl run.", "operationId": "updateCrawlConfig", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCrawlConfigRequest" } } } }, "responses": { "200": { "description": "Updated crawl config", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "config": {} } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/history": { "get": { "tags": ["Crawl"], "summary": "Get crawl history", "description": "Return a list of recent crawls for the tenant (or the workspace when `X-Workspace-ID` is set), newest first. Each entry has its final status (`completed`, `failed`, `cancelled`), page counts, duration, and any error summary — useful for diagnosing why a site's content is stale.", "operationId": "getCrawlHistory", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Crawl history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "crawls": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": ["crawls"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/{id}/status": { "get": { "tags": ["Crawl"], "summary": "Get crawl status", "description": "Return live status for a specific crawl id: `status` (`running`, `completed`, `failed`, `cancelled`), pages discovered / indexed / skipped / failed, elapsed time, and the current URL being processed. Poll every 3–10 seconds while `running`; stop polling once status is terminal. Returns 404 if the crawl id does not belong to the caller's tenant.", "operationId": "getCrawlStatus", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "crawl-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Crawl progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/{id}/cancel": { "post": { "tags": ["Crawl"], "summary": "Cancel a running crawl", "description": "Cancel a crawl that is currently in progress.", "operationId": "cancelCrawl", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "crawl-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Crawl cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" } }, "required": ["cancelled"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/crawl/{id}/notifications": { "post": { "tags": ["Crawl"], "summary": "Enroll for a crawl-complete email", "description": "Requests an email notification when this crawl reaches a terminal state (completed or failed). Intended for the dashboard \"continue onboarding, email me when done\" CTA. Rejects crawls that have already finished. **Admin-only endpoint.** The `email` in the body is treated as opaque and persisted verbatim; the cloud API does NOT authenticate ownership of that address. Callers holding the admin bearer are trusted to have derived the recipient from an authoritative source (e.g. the signed-in user session on the Next.js proxy). Do NOT expose this route via license-key / public scopes.", "operationId": "enrollCrawlNotification", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "crawl-abc123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollCrawlNotificationRequest" } } } }, "responses": { "200": { "description": "Enrolled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enrolled": { "type": "boolean", "enum": [true] } }, "required": ["enrolled"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/scrape": { "post": { "tags": ["Scrape"], "summary": "Scrape or delete a single page", "description": "Scrape a URL and index it into the knowledge base, or delete a previously scraped page.", "operationId": "scrapePage", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" } } } }, "responses": { "200": { "description": "Scrape result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "pageId": { "type": "string" } }, "required": ["action", "url"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products": { "post": { "tags": ["Products"], "summary": "Upsert a product", "description": "Create a new product or update the existing one whose `externalId` matches the body. Embeddings for the product's searchable text are generated and persisted as part of the call, so the product becomes searchable immediately after a successful response. Required fields: `externalId`, `name`. Optional: `description`, `price` (in cents), `priceMin` / `priceMax`, `stockStatus` (`in_stock` | `out_of_stock` | `limited`), `images` (array of URLs), `brand`, `category`, `attributes` (key/value). Workspaces with native Shopify / WooCommerce sync should normally rely on the plugin rather than calling this endpoint directly. Idempotent on `externalId`.", "operationId": "upsertProduct", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "Product upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["product"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Products"], "summary": "List products", "description": "List products with optional filters. Supports pagination, category/tag/status filters, and metadata queries.", "operationId": "listProducts", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Product list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/bulk": { "post": { "tags": ["Products"], "summary": "Bulk upsert products", "description": "Create or update up to 100 products in a single request.", "operationId": "bulkUpsertProducts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/ProductInput" }, "minItems": 1, "maxItems": 100 }, "refresh": { "type": "string", "enum": ["true", "false", "wait_for"] } }, "required": ["entities"] } } } }, "responses": { "200": { "description": "Bulk upsert completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["bulk_operation"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": ["error"] } }, "skipped": { "type": "number" }, "indexingLimitReached": { "type": "boolean" } }, "required": ["processed", "succeeded", "failed"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Products"], "summary": "Bulk delete products", "description": "Delete multiple products by their external IDs.", "operationId": "bulkDeleteProducts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "minItems": 1, "maxItems": 100 } }, "required": ["ids"] } } } }, "responses": { "200": { "description": "Bulk delete completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/search": { "post": { "tags": ["Products"], "summary": "Search products", "description": "Hybrid (BM25 + k-NN vector) search across the workspace's product catalog. Pass a natural-language `query` — the backend expands and filters it with an agent when that improves recall. Optional `filters` support `priceMin` / `priceMax`, `stockStatus`, `brand`, `category`, and arbitrary `attributes` equality. Optional `facetFields` returns aggregate counts for the requested fields. Use for \"find X\" style requests; use the chat endpoint instead if you want a conversational answer that cites the products.", "operationId": "searchProducts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["search_result"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "query": { "type": "object", "properties": { "text": { "type": "string" }, "truncated": { "type": "boolean" }, "originalLength": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": {} }, "limit": { "type": "number" } }, "required": ["text"] }, "facets": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "classification": {}, "enhanced": { "type": "boolean" }, "originalText": { "type": "string" }, "agentUsed": { "type": "boolean" }, "usageMultiplier": { "type": "number" }, "fallbackUsed": { "type": "boolean" } } } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/delete-by-query": { "post": { "tags": ["Products"], "summary": "Delete products by query", "description": "Delete all products matching the given filter criteria.", "operationId": "deleteProductsByQuery", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1 } }, "required": ["filters"] } } } }, "responses": { "200": { "description": "Delete completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "deleted": { "type": "number" } }, "required": ["processed", "deleted"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/ids": { "get": { "tags": ["Products"], "summary": "List product IDs", "description": "Retrieve external IDs of indexed products with optional filters. Supports large offsets for sync.", "operationId": "listProductIds", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Product IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/{id}": { "get": { "tags": ["Products"], "summary": "Get a product", "description": "Retrieve a single product by external ID.", "operationId": "getProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "product-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["product"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Products"], "summary": "Patch a product", "description": "Partially update a product (e.g. change indexStatus).", "operationId": "patchProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "product-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] } } } } } }, "responses": { "200": { "description": "Updated product", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["product"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Product" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Products"], "summary": "Delete a product", "description": "Delete a single product by external ID.", "operationId": "deleteProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "product-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts": { "post": { "tags": ["Posts"], "summary": "Upsert a post", "description": "Create a new post / knowledge article or update the existing one whose `externalId` matches the body. Embeddings are generated synchronously so the post is immediately retrievable by chat and search. Required: `externalId`, `title`, `content` (markdown or plain text). Optional: `author`, `publishedAt` (ISO 8601), `url`, `tags`, `category`. Use this for help-center articles, FAQ entries, or arbitrary brand content that should be answerable via chat. For bulk backfills prefer `POST /posts/bulk`. Idempotent on `externalId`.", "operationId": "upsertPost", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "responses": { "200": { "description": "Post upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["post"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts/bulk": { "post": { "tags": ["Posts"], "summary": "Bulk upsert posts", "description": "Create or update up to 100 posts in a single request.", "operationId": "bulkUpsertPosts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/PostInput" }, "minItems": 1, "maxItems": 100 }, "refresh": { "type": "string", "enum": ["true", "false", "wait_for"] } }, "required": ["entities"] } } } }, "responses": { "200": { "description": "Bulk upsert completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["bulk_operation"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": ["error"] } }, "skipped": { "type": "number" }, "indexingLimitReached": { "type": "boolean" } }, "required": ["processed", "succeeded", "failed"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Posts"], "summary": "Bulk delete posts", "description": "Delete multiple posts by their external IDs.", "operationId": "bulkDeletePosts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "minItems": 1, "maxItems": 100 } }, "required": ["ids"] } } } }, "responses": { "200": { "description": "Bulk delete completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts/search": { "post": { "tags": ["Posts"], "summary": "Search posts", "description": "Hybrid semantic + lexical search across the workspace's indexed posts / knowledge articles. Pass a natural-language `query`; the response returns the top-matching posts with excerpts, scores, and URLs. Use when you need raw passages to feed another agent; use the chat endpoint when you want a cited, synthesised answer rather than a list of hits.", "operationId": "searchPosts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["search_result"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "query": { "type": "object", "properties": { "text": { "type": "string" }, "truncated": { "type": "boolean" }, "originalLength": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": {} }, "limit": { "type": "number" } }, "required": ["text"] }, "meta": { "type": "object", "properties": { "classification": {}, "enhanced": { "type": "boolean" }, "originalText": { "type": "string" }, "agentUsed": { "type": "boolean" }, "usageMultiplier": { "type": "number" }, "fallbackUsed": { "type": "boolean" } } } }, "required": ["items", "pagination", "query"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts/delete-by-query": { "post": { "tags": ["Posts"], "summary": "Delete posts by query", "description": "Delete all posts matching the given filter criteria.", "operationId": "deletePostsByQuery", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1 } }, "required": ["filters"] } } } }, "responses": { "200": { "description": "Delete completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "deleted": { "type": "number" } }, "required": ["processed", "deleted"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts/ids": { "get": { "tags": ["Posts"], "summary": "List post IDs", "description": "Retrieve external IDs of indexed posts with optional filters. Supports large offsets for sync.", "operationId": "listPostIds", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Post IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/posts/{id}": { "get": { "tags": ["Posts"], "summary": "Get a post", "description": "Retrieve a single post by external ID.", "operationId": "getPost", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "post-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Post details", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["post"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Post" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Posts"], "summary": "Patch a post", "description": "Partially update a post (e.g. change indexStatus).", "operationId": "patchPost", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "post-123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "indexStatus": { "type": "string", "enum": ["active", "hidden", "disabled"] } } } } } }, "responses": { "200": { "description": "Updated post", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["post"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Post" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Posts"], "summary": "Delete a post", "description": "Delete a single post by external ID.", "operationId": "deletePost", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "post-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Post deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/search": { "post": { "tags": ["Threads"], "summary": "Search threads", "description": "Search and filter conversation threads with pagination, date ranges, and sorting.", "operationId": "searchThreads", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadSearchRequest" } } } }, "responses": { "200": { "description": "Thread search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["search_result"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"], "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/export": { "post": { "tags": ["Threads"], "summary": "Export threads", "description": "Export conversation threads in JSON or CSV format with optional date and user filtering.", "operationId": "exportThreads", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadExportRequest" } } } }, "responses": { "200": { "description": "Exported thread data", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/analytics": { "get": { "tags": ["Threads"], "summary": "Get thread analytics", "description": "Retrieve aggregate analytics and statistics about conversation threads.", "operationId": "getThreadAnalytics", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Thread analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/{id}/messages": { "get": { "tags": ["Threads"], "summary": "Get thread messages", "description": "Retrieve all messages for a specific conversation thread. Requires admin:threads or chat scope.", "operationId": "getThreadMessages", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "thread-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Thread messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["thread"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "threadId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": ["user", "assistant"] }, "content": { "type": "string" }, "timestamp": { "type": "string" }, "source": { "type": "string" }, "agentInfo": {} }, "required": ["id", "role", "content", "timestamp"] } }, "count": { "type": "number" } }, "required": ["threadId", "messages", "count"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/{id}/handoff/end": { "post": { "tags": ["Threads"], "summary": "End live agent handoff", "description": "End a live agent handoff session for a thread. Requires admin:threads or chat scope.", "operationId": "endHandoff", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "thread-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Handoff ended", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/{id}": { "get": { "tags": ["Threads"], "summary": "Get thread by ID", "description": "Retrieve a single conversation thread by its ID, optionally including feedback data.", "operationId": "getThread", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "thread-abc123" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "example": "true" }, "required": false, "name": "include_feedback", "in": "query" } ], "responses": { "200": { "description": "Thread detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["thread"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Threads"], "summary": "Delete a thread", "description": "Permanently delete a conversation thread by its ID.", "operationId": "deleteThread", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "thread-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Thread deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads": { "delete": { "tags": ["Threads"], "summary": "Bulk delete threads", "description": "Delete multiple conversation threads by their IDs in a single request.", "operationId": "bulkDeleteThreads", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadBulkDeleteRequest" } } } }, "responses": { "200": { "description": "Bulk delete results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/feedback": { "post": { "tags": ["Feedback"], "summary": "Submit feedback", "description": "Submit user feedback for a piece of content or chat message.", "operationId": "submitFeedback", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmission" } } } }, "responses": { "200": { "description": "Feedback submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Feedback"], "summary": "Search feedback", "description": "Search and filter feedback entries with pagination.", "operationId": "listFeedback", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Feedback search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/feedback/analytics": { "get": { "tags": ["Feedback"], "summary": "Get feedback analytics", "description": "Retrieve aggregated feedback analytics for a date range.", "operationId": "getFeedbackAnalytics", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Feedback analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/feedback/thread/{threadId}": { "get": { "tags": ["Feedback"], "summary": "Get feedback for a thread", "description": "Retrieve all feedback entries associated with a specific thread.", "operationId": "getThreadFeedback", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "thread-abc" }, "required": true, "name": "threadId", "in": "path" } ], "responses": { "200": { "description": "Thread feedback", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "feedback": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": ["feedback"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/feedback/{id}": { "delete": { "tags": ["Feedback"], "summary": "Delete feedback", "description": "Delete a feedback entry by ID.", "operationId": "deleteFeedback", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "fb-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Feedback deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/prompts": { "post": { "tags": ["Prompts"], "summary": "Upsert a prompt", "description": "Create or update a prompt by external ID.", "operationId": "upsertPrompt", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptInput" } } } }, "responses": { "200": { "description": "Prompt upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["prompt"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Prompts"], "summary": "List prompts", "description": "List prompts with optional pagination and metadata filters.", "operationId": "listPrompts", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Prompt list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/prompts/search": { "post": { "tags": ["Prompts"], "summary": "Search prompts", "description": "Semantic search across prompts with optional filters.", "operationId": "searchPrompts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 200000 }, "filters": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": ["text"] } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["search_result"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "query": { "type": "object", "properties": { "text": { "type": "string" }, "filters": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "categories": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } }, "limit": { "type": "number" } }, "required": ["text"] } }, "required": ["items", "pagination", "query"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/prompts/bulk": { "post": { "tags": ["Prompts"], "summary": "Bulk upsert prompts", "description": "Create or update up to 100 prompts in a single request.", "operationId": "bulkUpsertPrompts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/PromptInput" }, "minItems": 1, "maxItems": 100 }, "refresh": { "type": "string", "enum": ["true", "false", "wait_for"] } }, "required": ["entities"] } } } }, "responses": { "200": { "description": "Bulk upsert completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["bulk_operation"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": ["error"] } }, "skipped": { "type": "number" }, "indexingLimitReached": { "type": "boolean" } }, "required": ["processed", "succeeded", "failed"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Prompts"], "summary": "Bulk delete prompts", "description": "Delete multiple prompts by their external IDs.", "operationId": "bulkDeletePrompts", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "minItems": 1, "maxItems": 100 } }, "required": ["ids"] } } } }, "responses": { "200": { "description": "Bulk delete completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/prompts/{id}": { "get": { "tags": ["Prompts"], "summary": "Get a prompt", "description": "Retrieve a single prompt by external ID.", "operationId": "getPrompt", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "prompt-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Prompt details", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["prompt"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Prompt" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Prompts"], "summary": "Delete a prompt", "description": "Delete a single prompt by external ID.", "operationId": "deletePrompt", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "prompt-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Prompt deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/bulk-status": { "post": { "tags": ["Webhooks"], "summary": "Bulk update webhook status", "description": "Update the status of multiple webhooks at once.", "operationId": "bulkUpdateWebhookStatus", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWebhookStatusInput" } } } }, "responses": { "200": { "description": "Bulk status update result", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"], "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks": { "post": { "tags": ["Webhooks"], "summary": "Create a webhook", "description": "Register a new webhook endpoint to receive event notifications.", "operationId": "createWebhook", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInput" } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"], "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Webhooks"], "summary": "List webhooks", "description": "List all webhooks with optional filters, pagination, and sorting.", "operationId": "listWebhooks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": ["active", "inactive", "suspended"] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "events", "in": "query" }, { "schema": { "type": "string", "maxLength": 200 }, "required": false, "name": "createdBy", "in": "query" }, { "schema": { "type": "string", "maxLength": 200 }, "required": false, "name": "nameContains", "in": "query" }, { "schema": { "type": "string", "maxLength": 200 }, "required": false, "name": "urlContains", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "createdAfter", "in": "query" }, { "schema": { "type": "string", "maxLength": 64 }, "required": false, "name": "createdBefore", "in": "query" }, { "schema": { "type": "string", "enum": ["name", "createdAt", "updatedAt", "lastDeliveryAt"] }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": ["asc", "desc"] }, "required": false, "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": ["Webhooks"], "summary": "Test a webhook", "description": "Send a test event to a webhook endpoint to verify connectivity.", "operationId": "testWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wh-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"], "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/stats": { "get": { "tags": ["Webhooks"], "summary": "Get webhook stats", "description": "Retrieve delivery statistics for a specific webhook.", "operationId": "getWebhookStats", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wh-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook delivery statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}": { "get": { "tags": ["Webhooks"], "summary": "Get a webhook", "description": "Retrieve a single webhook by ID. Sensitive fields are redacted.", "operationId": "getWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wh-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": ["Webhooks"], "summary": "Update a webhook", "description": "Update an existing webhook configuration.", "operationId": "updateWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wh-abc123" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInput" } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"], "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook", "description": "Permanently delete a webhook by ID.", "operationId": "deleteWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "wh-abc123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/taxonomies": { "post": { "tags": ["Taxonomies"], "summary": "Upsert a taxonomy term", "description": "Create or update a taxonomy term by external ID.", "operationId": "upsertTaxonomy", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyInput" } } } }, "responses": { "200": { "description": "Taxonomy term upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["taxonomy"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Taxonomies"], "summary": "List taxonomy terms", "description": "List taxonomy terms with optional filters and pagination.", "operationId": "listTaxonomies", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Taxonomy list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/taxonomies/bulk": { "post": { "tags": ["Taxonomies"], "summary": "Bulk upsert taxonomy terms", "description": "Create or update up to 100 taxonomy terms in a single request.", "operationId": "bulkUpsertTaxonomies", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyInput" }, "minItems": 1, "maxItems": 100 }, "refresh": { "type": "string", "enum": ["true", "false", "wait_for"] } }, "required": ["entities"] } } } }, "responses": { "200": { "description": "Bulk upsert completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["bulk_operation"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": ["error"] } }, "skipped": { "type": "number" }, "indexingLimitReached": { "type": "boolean" } }, "required": ["processed", "succeeded", "failed"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Taxonomies"], "summary": "Bulk delete taxonomy terms", "description": "Delete multiple taxonomy terms by their external IDs.", "operationId": "bulkDeleteTaxonomies", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 } }, "required": ["ids"] } } } }, "responses": { "200": { "description": "Bulk delete completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOperation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/taxonomies/delete-by-query": { "post": { "tags": ["Taxonomies"], "summary": "Delete taxonomy terms by query", "description": "Delete all taxonomy terms matching the given filter criteria.", "operationId": "deleteTaxonomiesByQuery", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1 } }, "required": ["filters"] } } } }, "responses": { "200": { "description": "Delete completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "processed": { "type": "number" }, "deleted": { "type": "number" } }, "required": ["processed", "deleted"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/taxonomies/ids": { "get": { "tags": ["Taxonomies"], "summary": "List taxonomy term IDs", "description": "Retrieve external IDs of indexed taxonomy terms with optional filters.", "operationId": "listTaxonomyIds", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Taxonomy IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/taxonomies/{id}": { "get": { "tags": ["Taxonomies"], "summary": "Get a taxonomy term", "description": "Retrieve a single taxonomy term by external ID.", "operationId": "getTaxonomy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "taxonomy-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Taxonomy details", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["taxonomy"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/Taxonomy" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Taxonomies"], "summary": "Delete a taxonomy term", "description": "Delete a single taxonomy term by external ID.", "operationId": "deleteTaxonomy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "taxonomy-123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Taxonomy term deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/analytics/search": { "get": { "tags": ["Analytics"], "summary": "Get search analytics", "description": "Retrieve search analytics data including top queries, zero-result queries, and volume over time.", "operationId": "getSearchAnalytics", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "30" }, "required": false, "name": "days", "in": "query" }, { "schema": { "type": "string", "example": "10" }, "required": false, "name": "topN", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "workspaceId", "in": "query" }, { "schema": { "type": "string", "example": "widget,native" }, "required": false, "name": "source", "in": "query" } ], "responses": { "200": { "description": "Search analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/analytics/searches/search": { "post": { "tags": ["Analytics"], "summary": "Search through search logs", "description": "Query and filter recorded search logs with pagination and sorting.", "operationId": "searchSearches", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "workspaceId": { "type": "string" }, "query": { "type": "string" }, "zeroResultsOnly": { "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "type": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string", "enum": ["asc", "desc"] } } } } } }, "responses": { "200": { "description": "Search log results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/analytics/searches/commit": { "post": { "tags": ["Analytics"], "summary": "Commit a search event", "description": "Record a search event for analytics tracking. Requires search scope.", "operationId": "commitSearch", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "source": { "type": "string" }, "type": { "type": "string" }, "resultsCount": { "type": "number" }, "topScore": { "type": "number" }, "avgScore": { "type": "number" } }, "required": ["query"] } } } }, "responses": { "200": { "description": "Search event committed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "committed": { "type": "boolean" } }, "required": ["committed"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/analytics/chat": { "get": { "tags": ["Analytics"], "summary": "Get chat analytics", "description": "Retrieve chat/thread analytics data over a configurable time window.", "operationId": "getChatAnalytics", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "30" }, "required": false, "name": "days", "in": "query" } ], "responses": { "200": { "description": "Chat analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/analytics/feedback": { "get": { "tags": ["Analytics"], "summary": "Get feedback analytics", "description": "Retrieve feedback analytics data with optional date range filtering.", "operationId": "getAnalyticsFeedback", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "dateFrom", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "dateTo", "in": "query" } ], "responses": { "200": { "description": "Feedback analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/recommendations/products": { "post": { "tags": ["Recommendations"], "summary": "Get product recommendations", "description": "Retrieve AI-powered product recommendations based on a source product, basket affinity, and optional filters.", "operationId": "getProductRecommendations", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationRequest" } } } }, "responses": { "200": { "description": "Product recommendations", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["recommendations"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/{tenantId}": { "delete": { "tags": ["Tenant"], "summary": "Self-delete tenant", "operationId": "deleteTenant", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Tenant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "207": { "description": "Tenant deleted with partial cleanup failures — inspect data.results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/status": { "get": { "tags": ["Tenant"], "summary": "Get tenant status", "description": "Validate API key and retrieve tenant account information including tier, publishable key, and JWT secret.", "operationId": "getTenantStatus", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tenant status", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/TenantStatus" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/whoami": { "get": { "tags": ["Tenant"], "summary": "Identity probe (tenant, scopes, key type)", "description": "Return the tenant ID, tier, API key ID, key type, and scope list for the current caller. Designed for agent / MCP bootstrapping so clients can decide which operations are available before issuing them. Does NOT return any secret material.", "operationId": "getTenantWhoami", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current caller identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/TenantWhoami" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/features": { "patch": { "tags": ["Tenant"], "summary": "Update tenant feature flags", "operationId": "updateTenantFeatures", "x-internal": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantFeaturesRequest" } } } }, "responses": { "200": { "description": "Updated features", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/usage": { "get": { "tags": ["Tenant"], "summary": "Get usage summary", "description": "Return the authenticated tenant's current-period usage against plan limits: chat messages sent, products indexed, posts indexed, crawl pages processed, and the dates of the billing window. Use for quota-aware UX or to warn a user that the next operation would trip an overage.", "operationId": "getTenantUsage", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["usage"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/usage/history": { "get": { "tags": ["Tenant"], "summary": "Get daily usage history", "operationId": "getTenantUsageHistory", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Usage history", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["usage"] }, "requestId": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/workspaces": { "get": { "tags": ["Tenant"], "summary": "List workspaces", "description": "Return every workspace owned by the authenticated tenant, with each workspace's id, name, platform (wordpress | shopify | custom | none), and domain. Use this before calling any workspace-scoped endpoint (crawl, products, posts, chat) to discover the correct `workspaceId` to pass via the `X-Workspace-ID` header. Always cheap and safe to call repeatedly.", "operationId": "listTenantWorkspaces", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Workspace list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["Tenant"], "summary": "Create a workspace", "description": "Create a new workspace (a distinct site / storefront) under the authenticated tenant. Returns the workspace id you will pass as `X-Workspace-ID` on every subsequent content, crawl, and chat request. Typical onboarding flow: create → (optionally set platform) → start crawl → ingest products/posts. Creation does NOT enqueue a crawl — call `POST /crawl` separately.", "operationId": "createTenantWorkspace", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } } }, "responses": { "201": { "description": "Workspace created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/WorkspaceSummary" }, "message": { "type": "string" } }, "required": ["workspace", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/workspaces/{workspaceId}": { "put": { "tags": ["Tenant"], "summary": "Update a workspace", "description": "Patch name, platform, or metadata on an existing workspace. Accepts a partial body; omitted fields are left untouched. Changing `platform` from `none` to `wordpress` / `shopify` signals the ingestion pipeline to prefer native sync over crawl-derived content on subsequent operations.", "operationId": "updateWorkspace", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } } }, "responses": { "200": { "description": "Updated workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Tenant"], "summary": "Delete a workspace", "description": "Permanently delete a workspace and every document indexed under it (products, posts, taxonomies, chat threads, crawl history). This is NOT recoverable — prefer `POST /workspaces` to create a new one rather than delete + recreate for routine cleanup. Returns 404 if the id does not belong to the caller's tenant.", "operationId": "deleteWorkspace", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Workspace deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "207": { "description": "Workspace deleted with partial cleanup failures — inspect data.results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/knowledge": { "get": { "tags": ["Tenant"], "summary": "Get document statistics", "description": "Retrieve document counts and breakdown by type from the knowledge base.", "operationId": "getKnowledge", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Document statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/knowledge/search": { "get": { "tags": ["Tenant"], "summary": "Search knowledge base documents", "operationId": "searchKnowledge", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/upload-url": { "post": { "tags": ["Tenant"], "summary": "Get presigned upload URL", "operationId": "getUploadUrl", "x-internal": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUploadUrlRequest" } } } }, "responses": { "200": { "description": "Upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/mcp": { "get": { "tags": ["Tenant"], "summary": "Get MCP configuration", "operationId": "getMcpConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "MCP config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": ["Tenant"], "summary": "Update MCP configuration", "operationId": "updateMcpConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpConfigRequest" } } } }, "responses": { "200": { "description": "Updated MCP config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Tenant"], "summary": "Delete MCP configuration", "operationId": "deleteMcpConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "MCP config deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/live-agent/credentials/status": { "get": { "tags": ["Tenant"], "summary": "Check live agent credential status", "operationId": "getCredentialStatus", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Credential status", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/live-agent/credentials": { "post": { "tags": ["Tenant"], "summary": "Store live agent credentials", "operationId": "storeCredentials", "x-internal": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLiveAgentCredentialsRequest" } } } }, "responses": { "200": { "description": "Credentials stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Tenant"], "summary": "Delete live agent credentials", "operationId": "deleteCredentials", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Credentials deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tenant/live-agent/schedule": { "get": { "tags": ["Tenant"], "summary": "Get live agent schedule", "operationId": "getLiveAgentSchedule", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": ["Tenant"], "summary": "Update live agent schedule", "operationId": "updateLiveAgentSchedule", "x-internal": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveAgentScheduleRequest" } } } }, "responses": { "200": { "description": "Updated schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Tenant"], "summary": "Delete live agent schedule", "operationId": "deleteLiveAgentSchedule", "x-internal": true, "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schedule deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/settings": { "get": { "tags": ["Workspace"], "summary": "Get workspace settings", "description": "Retrieve settings for a workspace including live agent configuration and special instructions.", "operationId": "getWorkspaceSettings", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Workspace settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "settings": { "type": ["object", "null"], "additionalProperties": {} } }, "required": ["settings"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Workspace"], "summary": "Update workspace settings", "description": "Update workspace settings such as live agent configuration, description, and special instructions.", "operationId": "updateWorkspaceSettings", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "liveAgent": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": ["none", "slack", "whatsapp", "teams"] }, "autoHandoff": { "type": "boolean" }, "manualHandoff": { "type": "boolean" }, "escalationPrompt": { "type": "string", "maxLength": 1500 }, "inactivityTimeout": { "type": "integer", "minimum": 60, "maximum": 3600 }, "contactFormEnabled": { "type": "boolean" }, "businessHours": { "type": "string", "maxLength": 500 } } }, "workspaceDescription": { "type": "string", "maxLength": 500 }, "specialInstructions": { "type": "string", "maxLength": 5000 }, "triageProgressMessage": { "type": "string", "maxLength": 100 }, "composerProgressMessage": { "type": "string", "maxLength": 100 }, "builtinTools": { "type": "object", "properties": { "product": { "type": ["object", "null"], "properties": { "tools": { "type": ["array", "null"], "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] }, "maxItems": 2 }, "toolProgressMessages": { "type": ["object", "null"], "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } }, "maxTurns": { "type": ["integer", "null"], "minimum": 1, "maximum": 5 }, "usageHints": { "type": ["string", "null"], "maxLength": 1000 } } }, "post": { "type": ["object", "null"], "properties": { "tools": { "type": ["array", "null"], "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] }, "maxItems": 2 }, "toolProgressMessages": { "type": ["object", "null"], "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } }, "maxTurns": { "type": ["integer", "null"], "minimum": 1, "maximum": 5 }, "usageHints": { "type": ["string", "null"], "maxLength": 1000 } } } } } } } } } }, "responses": { "200": { "description": "Updated settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "settings": { "type": "object", "additionalProperties": {} } }, "required": ["settings"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/live-agent/status": { "get": { "tags": ["Workspace"], "summary": "Get live agent connection status", "operationId": "getLiveAgentStatus", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Live agent status", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/live-agent/slack/channels": { "get": { "tags": ["Workspace"], "summary": "List Slack channels for live agent", "operationId": "listSlackChannels", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Slack channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/chat": { "get": { "tags": ["Workspace"], "summary": "Get chat widget configuration", "operationId": "getChatWidgetConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Chat widget config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["widget_config"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} } }, "required": ["config"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["Workspace"], "summary": "Update chat widget configuration", "operationId": "updateChatWidgetConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "triggerPosition": { "type": "string", "enum": ["bottom-right", "bottom-left", "top-right", "top-left"] }, "triggerIconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [""] } ] }, "triggerShowBackground": { "type": "boolean" }, "triggerShowBorder": { "type": "boolean" }, "title": { "type": "string", "maxLength": 100 }, "subtitle": { "type": "string", "maxLength": 200 }, "avatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [""] } ] }, "headerAvatarShowBackground": { "type": "boolean" }, "headerAvatarShowBorder": { "type": "boolean" }, "greeting": { "type": "string", "maxLength": 500 }, "greetingSubtext": { "type": "string", "maxLength": 500 }, "greetingIconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [""] } ] }, "placeholder": { "type": "string", "maxLength": 200 }, "cardLayout": { "type": "string", "enum": ["carousel", "stack"] }, "promptStyle": { "type": "string", "enum": ["inline", "input", "both"] }, "productCardVariant": { "type": "string", "enum": ["default", "horizontal"] }, "productCardImageDisplay": { "type": "string", "enum": ["contain", "cover", "backdrop"] }, "productCardImageAspectRatio": { "type": "string", "enum": ["square", "landscape", "wide"] }, "postCardImageDisplay": { "type": "string", "enum": ["contain", "cover", "backdrop"] }, "postCardImageAspectRatio": { "type": "string", "enum": ["square", "landscape", "wide"] }, "showMessageActions": { "type": "boolean" }, "showUserCopyButton": { "type": "boolean" }, "showMessageTimestamps": { "type": "boolean" }, "showPostImage": { "type": "boolean" }, "showPostAuthor": { "type": "boolean" }, "showPostDate": { "type": "boolean" }, "showPostCategory": { "type": "boolean" }, "popoverEnabled": { "type": "boolean" }, "popoverMessage": { "type": "string", "maxLength": 200 }, "popoverDelay": { "type": "integer", "minimum": 0, "maximum": 30000 }, "popoverShowOnce": { "type": "boolean" }, "theme": { "type": "object", "properties": { "colorScheme": { "type": "string", "enum": ["light", "dark", "auto"] }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "primaryHover": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "linkColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "widgetBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "backgroundSecondary": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "assistantBubbleBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "focusBorderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "header": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "titleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "subtitleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "iconColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "triggerButton": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "referenceCard": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderRadius": { "type": "number" }, "titleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "metaColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "descriptionColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "promptChip": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "textColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBorderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "maxLength": 200 }, "fontSize": { "type": "string", "enum": ["small", "medium", "large"] } } }, "borderRadius": { "type": "number" }, "maxWidth": { "type": "number" }, "maxHeight": { "type": "number" } } }, "darkTheme": { "type": "object", "properties": { "colorScheme": { "type": "string", "enum": ["light", "dark", "auto"] }, "colors": { "type": "object", "properties": { "primaryColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "primaryHover": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "linkColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "widgetBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "backgroundSecondary": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "assistantBubbleBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "focusBorderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "header": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "titleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "subtitleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "iconColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "triggerButton": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "referenceCard": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderRadius": { "type": "number" }, "titleColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "metaColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "descriptionColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "promptChip": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "textColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "hoverBorderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" } } }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "maxLength": 200 }, "fontSize": { "type": "string", "enum": ["small", "medium", "large"] } } }, "borderRadius": { "type": "number" }, "maxWidth": { "type": "number" }, "maxHeight": { "type": "number" } } }, "customCSS": { "type": "string", "maxLength": 10000 }, "resetToDefaults": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Updated chat config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["widget_config"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} } }, "required": ["config"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/search": { "get": { "tags": ["Workspace"], "summary": "Get search widget configuration", "operationId": "getSearchWidgetConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Search widget config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["widget_config"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} } }, "required": ["config"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["Workspace"], "summary": "Update search widget configuration", "operationId": "updateSearchWidgetConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "showTrigger": { "type": "boolean" }, "triggerPosition": { "type": "string", "enum": ["bottom-right", "bottom-left", "top-right", "top-left"] }, "keyboardShortcut": { "type": "string", "maxLength": 10 }, "searchProducts": { "type": "boolean" }, "searchPosts": { "type": "boolean" }, "resultLayout": { "type": "string", "enum": ["stacked", "tabbed"] }, "searchOnSubmit": { "type": "boolean" }, "askAssistant": { "type": "boolean" }, "askAssistantLabel": { "type": "string", "maxLength": 50 }, "productTabLabel": { "type": "string", "maxLength": 50 }, "postTabLabel": { "type": "string", "maxLength": 50 }, "inputPlaceholder": { "type": "string", "maxLength": 200 }, "theme": { "type": "object", "properties": { "colorScheme": { "type": "string", "enum": ["light", "dark", "auto"] }, "primaryColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "darkPrimaryColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "trigger": { "type": "object", "properties": { "background": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "textColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "borderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "darkBackground": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "darkTextColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "darkBorderColor": { "type": "string", "pattern": "^(#[0-9A-Fa-f]{6}|rgba?\\(\\d{1,3},\\s*\\d{1,3},\\s*\\d{1,3}(,\\s*[\\d.]+)?\\))$" }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "enum": [""] } ] } } } } }, "customCSS": { "type": "string", "maxLength": 10000 } } } } } }, "responses": { "201": { "description": "Updated search config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["widget_config"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {} } }, "required": ["config"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain": { "get": { "tags": ["Workspace"], "summary": "List custom domains", "operationId": "listCustomDomains", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Custom domains list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["domains"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["Workspace"], "summary": "Create a custom domain", "description": "Register a custom domain (MCP server, API endpoints) for AI chat integration.", "operationId": "createCustomDomain", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "classifierPrompt": { "type": "string", "minLength": 10, "maxLength": 500 }, "agentPrompt": { "type": "string", "minLength": 20, "maxLength": 20000 }, "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "requiresAuth": { "type": "boolean" }, "staticAuth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic"] }, "headerName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] } }, "required": ["name", "url", "requiresAuth"] }, "maxItems": 5 }, "apiEndpoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] }, "maxItems": 3 }, "progressMessage": { "type": "string", "minLength": 5, "maxLength": 100 }, "enabled": { "type": "boolean", "default": false }, "toolStrategy": { "type": "string", "enum": ["required", "auto"] }, "maxToolTurns": { "type": "integer", "minimum": 1, "maximum": 5 }, "exclusive": { "type": "boolean" }, "composerRenderHint": { "type": "string", "enum": ["card", "inline", "prose-only", "gallery"] }, "composerVerbosity": { "type": "string", "enum": ["terse", "standard", "detailed"] }, "composerPrivacy": { "type": "string", "enum": ["public", "sensitive"] }, "digestTemplate": { "type": "string", "maxLength": 500 }, "composerStreamingFields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 5 }, "toolProgressMessages": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": ["name", "classifierPrompt", "agentPrompt", "mcpServers", "progressMessage"] } } } }, "responses": { "201": { "description": "Custom domain created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain/{domainId}": { "put": { "tags": ["Workspace"], "summary": "Update a custom domain", "operationId": "updateCustomDomain", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "order-support" }, "required": true, "name": "domainId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "classifierPrompt": { "type": "string", "minLength": 10, "maxLength": 500 }, "agentPrompt": { "type": "string", "minLength": 20, "maxLength": 20000 }, "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "requiresAuth": { "type": "boolean" }, "staticAuth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic"] }, "headerName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] } }, "required": ["name", "url", "requiresAuth"] }, "maxItems": 5 }, "apiEndpoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] }, "maxItems": 3 }, "progressMessage": { "type": "string", "minLength": 5, "maxLength": 100 }, "enabled": { "type": "boolean" }, "toolStrategy": { "type": "string", "enum": ["required", "auto"] }, "maxToolTurns": { "type": "integer", "minimum": 1, "maximum": 5 }, "exclusive": { "type": "boolean" }, "composerRenderHint": { "type": "string", "enum": ["card", "inline", "prose-only", "gallery"] }, "composerVerbosity": { "type": "string", "enum": ["terse", "standard", "detailed"] }, "composerPrivacy": { "type": "string", "enum": ["public", "sensitive"] }, "digestTemplate": { "type": "string", "maxLength": 500 }, "composerStreamingFields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 5 }, "toolProgressMessages": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } } }, "responses": { "200": { "description": "Updated domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "domain": { "type": "object", "additionalProperties": {} } }, "required": ["domain"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Workspace"], "summary": "Delete a custom domain", "description": "Remove a custom domain configuration from the workspace.", "operationId": "deleteCustomDomain", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "order-support" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "200": { "description": "Custom domain deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["id", "deleted"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain/error-summary": { "get": { "tags": ["Workspace"], "summary": "Get error counts across all domains", "operationId": "getDomainErrorSummary", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Error summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["errorSummary"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain/{domainId}/errors": { "get": { "tags": ["Workspace"], "summary": "Get error logs for a domain", "operationId": "getDomainErrors", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "order-support" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "200": { "description": "Domain errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["errors"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": ["errors"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Workspace"], "summary": "Clear error logs for a domain", "operationId": "clearDomainErrors", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "order-support" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "200": { "description": "Errors cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["id", "deleted"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain/validate": { "post": { "tags": ["Workspace"], "summary": "Validate a custom domain configuration", "operationId": "validateCustomDomain", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "classifierPrompt": { "type": "string" }, "agentPrompt": { "type": "string" }, "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "requiresAuth": { "type": "boolean" }, "staticAuth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic"] }, "headerName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] } }, "required": ["name", "url", "requiresAuth"] } }, "apiEndpoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] } }, "progressMessage": { "type": "string" }, "enabled": { "type": "boolean" }, "toolStrategy": { "type": "string", "enum": ["required", "auto"] }, "maxToolTurns": { "type": "integer" }, "exclusive": { "type": "boolean" }, "composerRenderHint": { "type": "string", "enum": ["card", "inline", "prose-only", "gallery"] }, "composerVerbosity": { "type": "string", "enum": ["terse", "standard", "detailed"] }, "composerPrivacy": { "type": "string", "enum": ["public", "sensitive"] }, "digestTemplate": { "type": "string" }, "composerStreamingFields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 5 }, "toolProgressMessages": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } }, "id": { "type": "string" }, "skipLlmValidation": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/test-connection": { "post": { "tags": ["Workspace"], "summary": "Test domain classification with sample queries", "operationId": "testDomainConnection", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "classifierPrompt": { "type": "string" }, "agentPrompt": { "type": "string" }, "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "requiresAuth": { "type": "boolean" }, "staticAuth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic"] }, "headerName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] } }, "required": ["name", "url", "requiresAuth"] } }, "apiEndpoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "responseFormat": { "type": "string", "enum": ["json", "xml"] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": ["bearer", "header", "basic", "query"] }, "headerName": { "type": "string", "maxLength": 100 }, "queryParamName": { "type": "string", "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": ["type", "value"] }, "requiresAuth": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$" }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": { "type": "string", "enum": ["query", "path", "body"] }, "required": { "type": "boolean" }, "description": { "type": "string", "maxLength": 500 }, "type": { "type": "string", "enum": ["string", "number", "boolean"] }, "defaultValue": { "type": "string", "maxLength": 500 } }, "required": ["name", "in", "required", "description", "type"] }, "maxItems": 10 }, "requestTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "dropPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 } }, "required": ["toolName", "description", "method", "path", "parameters"] }, "minItems": 1, "maxItems": 25 } }, "required": ["name", "baseUrl", "responseFormat", "endpoints"] } }, "progressMessage": { "type": "string" }, "enabled": { "type": "boolean" }, "toolStrategy": { "type": "string", "enum": ["required", "auto"] }, "maxToolTurns": { "type": "integer" }, "exclusive": { "type": "boolean" }, "composerRenderHint": { "type": "string", "enum": ["card", "inline", "prose-only", "gallery"] }, "composerVerbosity": { "type": "string", "enum": ["terse", "standard", "detailed"] }, "composerPrivacy": { "type": "string", "enum": ["public", "sensitive"] }, "digestTemplate": { "type": "string" }, "composerStreamingFields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 5 }, "toolProgressMessages": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": ["id", "name", "classifierPrompt", "agentPrompt", "mcpServers", "progressMessage"] }, "testQueries": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "minItems": 1, "maxItems": 5 } }, "required": ["domain", "testQueries"] } } } }, "responses": { "200": { "description": "Test results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/details": { "get": { "tags": ["Workspace"], "summary": "Get workspace details", "description": "Return the full configuration for a workspace: platform, domain, crawl config, widget settings, chat persona, live-agent handoff, custom domains, and document counts. Preferred read for agent bootstrap because it returns every knob in one call.", "operationId": "getWorkspaceDetails", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Workspace details", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["workspace"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/discover-tools": { "post": { "tags": ["Workspace"], "summary": "Discover available tools from MCP servers", "operationId": "discoverTools", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": ["name", "url"] }, "minItems": 1, "maxItems": 5 } }, "required": ["mcpServers"] } } } }, "responses": { "200": { "description": "Discovered tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/custom-domain/generate": { "post": { "tags": ["Workspace"], "summary": "AI-generate a custom domain configuration", "operationId": "generateDomainConfig", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "minLength": 10, "maxLength": 2000 }, "references": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["url", "text"] }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 }, "label": { "type": "string", "maxLength": 100 } }, "required": ["type", "value"] }, "maxItems": 5 } }, "required": ["description"] } } } }, "responses": { "200": { "description": "Generated config", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "requestId": { "type": "string" }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/workspace/{workspaceId}/templates": { "get": { "tags": ["Workspace"], "summary": "Get available domain templates", "operationId": "getDomainTemplates", "x-internal": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "my-workspace" }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "Domain templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["templates"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": ["templates"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/provision/deprovision": { "post": { "tags": ["Provisioning"], "summary": "Deprovision a tenant or workspace", "description": "Tear down a tenant or single workspace. Supports two auth modes: admin (set tenantId in the body to deprovision any tenant) or tenant self-deprovision (authenticate with a tenant API key carrying tenant:admin; tenantId is derived from the auth context). Requires tenant:admin. Used by the Shopify app on app uninstall.", "operationId": "deprovision", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprovisionRequest" } } } }, "responses": { "200": { "description": "Tenant deprovisioned", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["deprovision"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/DeprovisionResult" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/provision/keys": { "post": { "tags": ["API Keys"], "summary": "Create an API key", "description": "Create a new API key for the authenticated tenant. Requires tenant:admin.", "operationId": "createApiKey", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyRequest" } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["API Keys"], "summary": "List API keys", "description": "List all API keys for the authenticated tenant. Requires tenant:admin.", "operationId": "listApiKeys", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "API key list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "pagination": { "type": "object", "properties": { "total": { "type": ["number", "null"] }, "limit": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": ["total", "limit", "hasMore"] } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/provision/keys/{keyId}/revoke": { "post": { "tags": ["API Keys"], "summary": "Revoke an API key", "description": "Revoke an API key by ID. Requires tenant:admin.", "operationId": "revokeApiKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "key-123" }, "required": true, "name": "keyId", "in": "path" } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": ["revoked"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/provision/keys/{keyId}/rotate": { "post": { "tags": ["API Keys"], "summary": "Rotate an API key", "description": "Rotate an API key, generating a new key and revoking the old one. Requires tenant:admin.", "operationId": "rotateApiKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "key-123" }, "required": true, "name": "keyId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKeyRequest" } } } }, "responses": { "200": { "description": "Key rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/provision/shopify": { "post": { "tags": ["Provisioning"], "summary": "Provision a Shopify tenant", "description": "Called by the Savanto Shopify app after a merchant completes OAuth. Creates a new tenant + workspace, or reactivates and reissues keys if the shop was previously installed.", "operationId": "provisionShopify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopifyProvisionRequest" } } } }, "responses": { "200": { "description": "Existing tenant reactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProvisionResult" } }, "required": ["object", "requestId", "data"] } } } }, "201": { "description": "New tenant provisioned", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/ProvisionResult" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}": { "get": { "tags": ["Admin"], "summary": "Get tenant details", "operationId": "adminGetTenant", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Tenant details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": ["Admin"], "summary": "Delete a tenant and all associated data", "operationId": "adminDeleteTenant", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Tenant deleted — all critical steps succeeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] }, "permanent": { "type": "boolean" }, "totalDocumentsDeleted": { "type": "number" }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "success": { "type": "boolean" }, "details": { "type": "string" }, "error": { "type": "string" } }, "required": ["success"] } } }, "required": ["id", "deleted", "permanent", "totalDocumentsDeleted", "results"] } }, "required": ["object", "requestId", "data"] } } } }, "207": { "description": "Tenant deleted — some non-critical steps failed (inspect results for details)", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] }, "permanent": { "type": "boolean" }, "totalDocumentsDeleted": { "type": "number" }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "success": { "type": "boolean" }, "details": { "type": "string" }, "error": { "type": "string" } }, "required": ["success"] } } }, "required": ["id", "deleted", "permanent", "totalDocumentsDeleted", "results"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/by-email/{email}": { "get": { "tags": ["Admin"], "summary": "Find unclaimed tenants by email", "operationId": "adminFindByEmail", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "user%40example.com" }, "required": true, "name": "email", "in": "path" } ], "responses": { "200": { "description": "List of unclaimed tenants", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "provider": { "type": "string" }, "ownerEmail": { "type": "string" }, "createdAt": { "type": "string" }, "workspaceId": { "type": "string" }, "workspaceName": { "type": "string" }, "domain": { "type": "string" }, "platform": { "type": "string" } }, "required": ["tenantId", "tier", "provider", "createdAt"] } }, "pagination": { "type": "object", "properties": { "total": { "type": ["number", "null"] }, "limit": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": ["total", "limit", "hasMore"] } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/by-owner/{ownerId}": { "get": { "tags": ["Admin"], "summary": "Find tenants by owner ID", "operationId": "adminFindByOwner", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "usr_abc123" }, "required": true, "name": "ownerId", "in": "path" } ], "responses": { "200": { "description": "List of owned tenants", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "provider": { "type": "string" }, "ownerId": { "type": "string" }, "ownerEmail": { "type": "string" }, "createdAt": { "type": "string" } }, "required": ["tenantId", "tier", "provider", "createdAt"] } }, "pagination": { "type": "object", "properties": { "total": { "type": ["number", "null"] }, "limit": { "type": "number" }, "hasMore": { "type": "boolean" } }, "required": ["total", "limit", "hasMore"] } }, "required": ["items", "pagination"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/claim": { "post": { "tags": ["Admin"], "summary": "Claim an unclaimed tenant", "operationId": "adminClaimTenant", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminClaimTenantRequest" } } } }, "responses": { "200": { "description": "Tenant claimed", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "ownerId": { "type": "string" }, "ownerEmail": { "type": "string" }, "apiKeyId": { "type": "string" }, "publishableKeyId": { "type": "string" }, "hasApiKey": { "type": "boolean" }, "keysCreated": { "type": "boolean" }, "message": { "type": "string" } }, "required": ["tenantId", "tier", "ownerId", "hasApiKey", "keysCreated", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/owner-email": { "patch": { "tags": ["Admin"], "summary": "Update a tenant's owner email", "operationId": "adminUpdateOwnerEmail", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUpdateOwnerEmailRequest" } } } }, "responses": { "200": { "description": "Owner email updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "ownerEmail": { "type": "string" }, "message": { "type": "string" } }, "required": ["tenantId", "ownerEmail", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/subscription": { "patch": { "tags": ["Admin"], "summary": "Update a tenant's subscription", "operationId": "adminUpdateSubscription", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUpdateSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["subscription"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/reactivate": { "post": { "tags": ["Admin"], "summary": "Reactivate a soft-deleted tenant", "operationId": "adminReactivateTenant", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Tenant reactivated — all steps succeeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "tenantId": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyId": { "type": "string" }, "subscriptionReactivated": { "type": "boolean" }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "success": { "type": "boolean" }, "details": { "type": "string" }, "error": { "type": "string" } }, "required": ["success"] } }, "message": { "type": "string" } }, "required": ["success", "tenantId", "subscriptionReactivated", "results", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "207": { "description": "Tenant reactivated — some steps failed (inspect results for details)", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["tenant"] }, "requestId": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "tenantId": { "type": "string" }, "apiKey": { "type": "string" }, "apiKeyId": { "type": "string" }, "subscriptionReactivated": { "type": "boolean" }, "results": { "type": "object", "additionalProperties": { "type": "object", "properties": { "success": { "type": "boolean" }, "details": { "type": "string" }, "error": { "type": "string" } }, "required": ["success"] } }, "message": { "type": "string" } }, "required": ["success", "tenantId", "subscriptionReactivated", "results", "message"] } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/usage": { "get": { "tags": ["Admin"], "summary": "Get detailed usage for a tenant", "operationId": "adminGetUsage", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Usage details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tier": { "type": "string" }, "availableTiers": { "type": "array", "items": { "type": "string" } }, "period": { "type": "string" }, "hasTierOverrides": { "type": "boolean" }, "metrics": { "type": "object", "properties": { "chatMessages": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "searchQueries": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "recommendations": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "crawledPages": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "pagesIndexed": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "productsIndexed": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] }, "webhookDeliveries": { "type": "object", "properties": { "current": { "type": "number" }, "limit": { "type": "number" } }, "required": ["current", "limit"] } }, "required": [ "chatMessages", "searchQueries", "recommendations", "crawledPages", "pagesIndexed", "productsIndexed", "webhookDeliveries" ] } }, "required": ["tenantId", "tier", "availableTiers", "period", "hasTierOverrides", "metrics"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Admin"], "summary": "Set usage metric values", "operationId": "adminUpdateUsage", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "chatMessages": { "type": "integer", "minimum": 0 }, "searchQueries": { "type": "integer", "minimum": 0 }, "recommendations": { "type": "integer", "minimum": 0 }, "webhookDeliveries": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Usage updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "usage": { "type": "object", "additionalProperties": {} } }, "required": ["message", "usage"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/tier": { "patch": { "tags": ["Admin"], "summary": "Update a tenant's tier", "operationId": "adminUpdateTier", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1 } }, "required": ["tier"] } } } }, "responses": { "200": { "description": "Tier updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "tenantId": { "type": "string" }, "tier": { "type": "string" }, "limits": { "type": "object", "additionalProperties": {} } }, "required": ["message", "tenantId", "tier", "limits"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/tenant/{tenantId}/crawls/reset": { "post": { "tags": ["Admin"], "summary": "Reset a tenant's crawl records for the current month", "operationId": "adminResetCrawls", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "path" } ], "responses": { "200": { "description": "Crawl records reset", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" }, "tenantId": { "type": "string" }, "deletedRecords": { "type": "number" } }, "required": ["message", "tenantId", "deletedRecords"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects": { "get": { "tags": ["Admin"], "summary": "List all prospects", "operationId": "adminListProspects", "x-internal": true, "responses": { "200": { "description": "Prospects", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } } }, "required": ["items"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": ["Admin"], "summary": "Record newly discovered prospects", "operationId": "adminCreateProspects", "x-internal": true, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" } }, "required": ["domain"] }, "maxItems": 500 } }, "required": ["candidates"] } } } }, "responses": { "200": { "description": "Insert summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "created": { "type": "number" }, "skipped": { "type": "number" }, "failed": { "type": "number" } }, "required": ["created", "skipped", "failed"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/{domain}": { "patch": { "tags": ["Admin"], "summary": "Update a prospect status", "operationId": "adminPatchProspect", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Updated prospect", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/{domain}/demo": { "post": { "tags": ["Admin"], "summary": "Link a built demo workspace to a prospect", "operationId": "adminAttachProspectDemo", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": ["workspaceId"] } } } }, "responses": { "200": { "description": "Prospect with the demo attached", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/demos/{workspaceId}": { "delete": { "tags": ["Admin"], "summary": "Unlink a deleted demo workspace from whichever prospect points at it", "operationId": "adminDetachProspectDemo", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "workspaceId", "in": "path" } ], "responses": { "200": { "description": "The unlinked prospect, or null when no prospect pointed at that workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "prospect": { "type": ["object", "null"], "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } }, "required": ["prospect"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/{domain}/contact": { "post": { "tags": ["Admin"], "summary": "Set a prospect contact email by hand", "operationId": "adminSetProspectContact", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] } } } }, "responses": { "200": { "description": "Prospect with the contact set", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/{domain}/qualify": { "post": { "tags": ["Admin"], "summary": "Read a prospect site and record what it finds", "operationId": "adminQualifyProspect", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "Qualified prospect", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": ["new", "qualified", "rejected", "demoed", "contacted", "unsubscribed"] }, "niche": { "type": "string" }, "platform": { "type": "string", "enum": ["shopify", "woocommerce", "vertical", "content", "unknown"] }, "tier": { "type": "string", "enum": ["independent", "regional", "national", "unknown"] }, "sampleUrl": { "type": "string" }, "title": { "type": "string" }, "contactEmail": { "type": "string" }, "bouncedEmails": { "type": "array", "items": { "type": "string" } }, "suppressionReason": { "type": "string", "enum": ["unsubscribe", "complaint"] }, "pageCount": { "type": "number" }, "productCount": { "type": "number" }, "existingChatVendor": { "type": "string" }, "fitSummary": { "type": "string" }, "fitScore": { "type": "number" }, "demoWorkspaceId": { "type": "string" }, "discoveredAt": { "type": "string" }, "qualifiedAt": { "type": "string" }, "contactedAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["domain", "status", "discoveredAt", "updatedAt"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/prospects/{domain}/draft": { "post": { "tags": ["Admin"], "summary": "Draft an introduction email for a prospect (never sends)", "operationId": "adminDraftProspect", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "The prospect is not ready — nothing was written", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": ["started", "skipped"] }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "required": ["status"] } }, "required": ["data"] } } } }, "202": { "description": "Composition started; poll GET for the result", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": ["started", "skipped"] }, "detail": { "type": "string" }, "reason": { "type": "string" } }, "required": ["status"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": ["Admin"], "summary": "The most recent draft for a prospect, if one has been composed", "operationId": "adminGetProspectDraft", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "example.com" }, "required": true, "name": "domain", "in": "path" } ], "responses": { "200": { "description": "The latest draft, or null when none has been composed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "draft": { "type": ["object", "null"], "properties": { "correspondenceId": { "type": "string" }, "to": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": ["correspondenceId", "to", "subject", "body", "status", "createdAt"] } }, "required": ["draft"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/demo-qa": { "get": { "tags": ["Admin"], "summary": "List recorded demo QA verdicts for a tenant", "operationId": "adminListDemoQa", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "query" } ], "responses": { "200": { "description": "Demo QA verdicts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "verdict": { "type": "string", "enum": ["verified", "needs-review", "failed"] }, "checkedAt": { "type": "string" }, "note": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "outcome": { "type": "string", "enum": ["grounded", "no-sources", "degraded", "no-answer", "error"] }, "itemCount": { "type": "number" }, "excerpt": { "type": "string" } }, "required": ["question", "outcome", "itemCount"] } } }, "required": ["workspaceId", "verdict", "checkedAt", "checks"] } } }, "required": ["items"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/demo-qa/{workspaceId}": { "post": { "tags": ["Admin"], "summary": "Ask a demo its starter questions and record the verdict", "operationId": "adminRunDemoQa", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "demo-acme-4f2b1c" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "query" } ], "responses": { "202": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "started": { "type": "boolean" }, "workspaceId": { "type": "string" } }, "required": ["started", "workspaceId"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/demo-views": { "get": { "tags": ["Admin"], "summary": "Summarise demo page opens for a tenant", "operationId": "adminListDemoViews", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "query" } ], "responses": { "200": { "description": "Per-demo view summaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "viewCount": { "type": "number" }, "firstViewedAt": { "type": "string" }, "lastViewedAt": { "type": "string" }, "returned": { "type": "boolean" } }, "required": ["workspaceId", "viewCount", "firstViewedAt", "lastViewedAt", "returned"] } } }, "required": ["items"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/admin/demo-views/{workspaceId}": { "post": { "tags": ["Admin"], "summary": "Record one open of a demo page", "operationId": "adminRecordDemoView", "x-internal": true, "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "demo-acme-4f2b1c" }, "required": true, "name": "workspaceId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "tenant_abc123" }, "required": true, "name": "tenantId", "in": "query" } ], "responses": { "200": { "description": "Whether the view was stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean" } }, "required": ["recorded"] } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/customer-redact": { "post": { "tags": ["Compliance"], "summary": "Redact a customer across all stored PII", "description": "Hard-deletes every thread document and memory document within the caller tenant that matches the supplied customer identifiers. Runs as async OpenSearch tasks; the response contains task IDs for reconciliation. Idempotent when `caller.externalId` is supplied.", "operationId": "complianceCustomerRedact", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRedactRequest" } } } }, "responses": { "200": { "description": "Redaction queued (async task submitted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["compliance_request"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/ComplianceAuditResponse" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/compliance/customer-data-request": { "post": { "tags": ["Compliance"], "summary": "Record a customer data-export request", "description": "Queues a customer data-export request and notifies ops to fulfill it within Shopify's 30-day SLA. Idempotent when `caller.externalId` is supplied.", "operationId": "complianceCustomerDataRequest", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDataRequest" } } } }, "responses": { "200": { "description": "Data request recorded — ops team notified", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["compliance_request"] }, "requestId": { "type": "string" }, "data": { "$ref": "#/components/schemas/ComplianceAuditResponse" } }, "required": ["object", "requestId", "data"] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }