{ "openapi": "3.1.0", "info": { "title": "Seekmodo MCP Gateway — REST API", "version": "1.1.0", "summary": "REST shim over the Seekmodo tool surface", "description": "Authenticated REST endpoints exposed by `mcp.seekmodo.com`.\n\nEvery authenticated request must carry `X-Seekmodo-Tenant`, `X-Seekmodo-Timestamp` (Unix seconds), and `X-Seekmodo-Signature` (HMAC-SHA256 of the raw request body with the tenant shared secret; ±5 minute replay window).\n\n**Convention:** almost every MCP tool is also `POST /v1/` with a JSON body matching that tool's `inputSchema` (see `GET /v1/tools`).\n\nJSON-RPC MCP lives at `POST /` — see https://seekmodo.com/docs/mcp.\n\nImplementer guides: https://seekmodo.com/docs/connectors/custom (custom connectors) and https://seekmodo.com/docs/fitment (vehicle / YMM).\n\nThis OpenAPI document is generated from `ToolCatalog` via `services/mcp-gateway/tools/generate_openapi.php` — re-run after adding tools.", "contact": { "name": "Seekmodo", "email": "support@seekmodo.com", "url": "https://seekmodo.com/contact" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://mcp.seekmodo.com", "description": "Production gateway" }, { "url": "https://dev-mcp.seekmodo.com", "description": "Staging / development gateway" } ], "security": [ { "SeekmodoHmac": [] } ], "tags": [ { "name": "A/B testing" }, { "name": "Analytics" }, { "name": "Bot defence" }, { "name": "Catalog" }, { "name": "Catalog & telemetry" }, { "name": "Commerce" }, { "name": "ESP integrations" }, { "name": "Fitment & vehicles" }, { "name": "Health" }, { "name": "Learning-to-rank" }, { "name": "Merchandising" }, { "name": "Recommendations" }, { "name": "Search" }, { "name": "Shopper UX" } ], "paths": { "/v1/ab.archive": { "post": { "tags": [ "A/B testing" ], "summary": "ab.archive", "description": "Archive an experiment without promoting any variant. Mutating.", "operationId": "call_ab_archive", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment_id": { "type": "string", "pattern": "^exp_[a-f0-9]{1,16}$" } }, "required": [ "experiment_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ab.create": { "post": { "tags": [ "A/B testing" ], "summary": "ab.create", "description": "Create a new A/B experiment with at least two variants. Mutating.", "operationId": "call_ab_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 128 }, "hypothesis": { "type": [ "string", "null" ], "maxLength": 1024 }, "metric": { "type": "string", "enum": [ "ctr", "conversion", "zero_results" ], "default": "ctr" }, "variants": { "type": "array", "minItems": 2, "maxItems": 8, "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,31}$" }, "label": { "type": "string", "maxLength": 64 }, "weight": { "type": "integer", "minimum": 1, "maximum": 99 }, "params": { "type": "object" } }, "required": [ "id", "weight" ] } }, "start": { "type": "boolean", "default": false }, "auto_manage": { "type": "boolean", "default": true } }, "required": [ "name", "variants" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ab.list": { "post": { "tags": [ "A/B testing" ], "summary": "ab.list", "description": "List A/B experiments for the tenant.", "operationId": "call_ab_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "running", "promoted", "archived" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ab.promote": { "post": { "tags": [ "A/B testing" ], "summary": "ab.promote", "description": "Promote a winning variant of a running A/B experiment. Mutating.", "operationId": "call_ab_promote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment_id": { "type": "string", "pattern": "^exp_[a-f0-9]{1,16}$" }, "variant_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,31}$" } }, "required": [ "experiment_id", "variant_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ab.results": { "post": { "tags": [ "A/B testing" ], "summary": "ab.results", "description": "Per-variant impression / click / CTR rollup for an experiment.", "operationId": "call_ab_results", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment_id": { "type": "string", "pattern": "^exp_[a-f0-9]{1,16}$" }, "window": { "type": "string", "enum": [ "24h", "7d", "14d", "30d" ], "default": "14d" } }, "required": [ "experiment_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.click_pain": { "post": { "tags": [ "Analytics" ], "summary": "analytics.click_pain", "description": "High-volume queries with deep average click position (>=5). Highest-leverage pin / reranker candidates.", "operationId": "call_analytics_click_pain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "pain_threshold": { "type": "number", "minimum": 1, "maximum": 50 }, "min_volume": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.conversion_funnel": { "post": { "tags": [ "Analytics" ], "summary": "analytics.conversion_funnel", "description": "Daily funnel (searches -> clicks -> add_to_carts -> purchases) plus session-scoped conversion rates.", "operationId": "call_analytics_conversion_funnel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "currency": { "type": "string", "maxLength": 3 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.ctr_trend": { "post": { "tags": [ "Analytics" ], "summary": "analytics.ctr_trend", "description": "Daily CTR over a rolling window — aggregate (default) or per top-N keyword.", "operationId": "call_analytics_ctr_trend", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "top_n": { "type": "integer", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.latency": { "post": { "tags": [ "Analytics" ], "summary": "analytics.latency", "description": "Per-tenant search latency (p50, p95) and fallback rate over a rolling window for the operator health card.", "operationId": "call_analytics_latency", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "1h", "6h", "24h", "7d" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.revenue_by_query": { "post": { "tags": [ "Analytics" ], "summary": "analytics.revenue_by_query", "description": "Per-keyword revenue + order count for a rolling window, under a chosen attribution model.", "operationId": "call_analytics_revenue_by_query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "attribution": { "type": "string", "enum": [ "last_touch", "first_touch", "linear" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "currency": { "type": "string", "maxLength": 3 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.search_types": { "post": { "tags": [ "Analytics" ], "summary": "analytics.search_types", "description": "Search volume breakdown by type (keyword, vehicle/YMM, hybrid) for a rolling window.", "operationId": "call_analytics_search_types", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.top_clicked_products": { "post": { "tags": [ "Analytics" ], "summary": "analytics.top_clicked_products", "description": "Most-clicked products with click counts and top driving keywords for a rolling window.", "operationId": "call_analytics_top_clicked_products", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.top_queries": { "post": { "tags": [ "Analytics" ], "summary": "analytics.top_queries", "description": "Most-searched keywords with CTR and avg result count for a rolling window.", "operationId": "call_analytics_top_queries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "search_type": { "type": "string", "enum": [ "all", "keyword", "vehicle", "hybrid" ], "description": "Filter by search intent. Default keyword (text SERP only)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.weekly_digest": { "post": { "tags": [ "Analytics" ], "summary": "analytics.weekly_digest", "description": "Weekly search digest JSON for email reports (KPIs, keywords, products, zero-results, funnel, latency).", "operationId": "call_analytics_weekly_digest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "week_start": { "type": "string", "description": "ISO date YYYY-MM-DD (UTC Monday). Defaults to last complete week." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/analytics.zero_results": { "post": { "tags": [ "Analytics" ], "summary": "analytics.zero_results", "description": "Search queries that returned zero results.", "operationId": "call_analytics_zero_results", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "7d", "30d", "90d", "180d", "365d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "search_type": { "type": "string", "enum": [ "all", "keyword", "vehicle", "hybrid" ], "description": "Filter by search intent. Default keyword (text SERP only)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ask": { "post": { "tags": [ "Search" ], "summary": "ask", "description": "Single-turn Ask AI over the tenant catalog and policy docs. Bounded search + catalog.get loop with cited answers.", "operationId": "call_ask", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Shopper question." }, "context": { "type": "object", "properties": { "page_url": { "type": "string" }, "product_id": { "type": "string" } }, "additionalProperties": true }, "max_tool_calls": { "type": "integer", "minimum": 1, "maximum": 10 }, "session_id": { "type": "string" }, "shopper_context": { "type": "object" } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/banners.list": { "post": { "tags": [ "Merchandising" ], "summary": "banners.list", "description": "List banner merchandising rules for the tenant.", "operationId": "call_banners_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ], "description": "Optional status filter; defaults to all." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/banners.remove": { "post": { "tags": [ "Merchandising" ], "summary": "banners.remove", "description": "Delete a banner merchandising rule by id. Mutating.", "operationId": "call_banners_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/banners.set": { "post": { "tags": [ "Merchandising" ], "summary": "banners.set", "description": "Create or update a banner merchandising rule. Mutating.", "operationId": "call_banners_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "html": { "type": "string", "minLength": 1 }, "position": { "type": "string", "enum": [ "top", "inline_after_n", "sidebar" ] }, "n": { "type": "integer", "minimum": 1, "maximum": 100 }, "scope": { "type": "string", "enum": [ "query", "category", "global" ] }, "scope_value": { "type": "string" }, "match_mode": { "type": "string", "enum": [ "exact", "contains" ] }, "audience_segment_id": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ] }, "region_id": { "type": "string", "description": "Sprint 9 — banner only fires when the resolved region matches this id. Omit to apply to all regions." } }, "required": [ "html", "position", "scope" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/bot.classify": { "post": { "tags": [ "Bot defence" ], "summary": "bot.classify", "description": "Classify a request triple (UA + IP + session) as bot or human; returns bot_score 0..100 + reasons + signal breakdown.", "operationId": "call_bot_classify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ua": { "type": "string" }, "ip": { "type": "string" }, "session_id": { "type": "string" }, "event": { "type": "string", "enum": [ "impression", "click" ] }, "product_id": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/bot.health": { "post": { "tags": [ "Bot defence" ], "summary": "bot.health", "description": "Bot-check inline classifier health: 5-min classify volume (inline vs http), nonce issue/verify rates, 24h shadow AGREE-rate.", "operationId": "call_bot_health", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/bot_check.status": { "post": { "tags": [ "Bot defence" ], "summary": "bot_check.status", "description": "Per-tenant bot-check status: enrollment, last activity, and 24-hour bot-blocked counts.", "operationId": "call_bot_check_status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/bundle.suggest": { "post": { "tags": [ "Recommendations" ], "summary": "bundle.suggest", "description": "Anchor-based \"complete the kit\" bundle composer using co_purchase + diversity bias.", "operationId": "call_bundle_suggest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anchor_doc_id": { "type": "string", "description": "Anchor product id to compose bundles around." }, "bundle_size": { "type": "integer", "minimum": 2, "maximum": 5, "description": "Items per bundle (including anchor)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" } }, "required": [ "anchor_doc_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/catalog.get": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "catalog.get", "description": "Fetch a single indexed catalog document by id or sku with rich default fields.", "operationId": "call_catalog_get", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Typesense document id." }, "sku": { "type": "string", "description": "SKU lookup via filter_by." }, "include_fields": { "type": "string", "description": "Optional Typesense include_fields override." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/catalog.prune": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "catalog.prune", "description": "Delete commerce catalog documents whose last_indexed_at is strictly older than the supplied cutoff. Called after a successful full index run so hard-deleted or otherwise absent products stop appearing in suggest/typeahead. Mutating.", "operationId": "call_catalog_prune", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cutoff_epoch": { "type": "integer", "minimum": 1, "description": "Unix epoch seconds captured at the start of the connector full index run. Docs with last_indexed_at < cutoff_epoch are evicted." }, "cutoff_utc": { "type": "string", "minLength": 10, "maxLength": 40, "description": "UTC cutoff as YYYY-MM-DD HH:MM:SS or ISO-8601. Alternative to cutoff_epoch." }, "max_deletes": { "type": "integer", "minimum": 1, "maximum": 2000, "description": "Cap deletes per call; resume with page when has_more=true." }, "page": { "type": "integer", "minimum": 1, "description": "Typesense search page when resuming a capped run." }, "active_count": { "type": "integer", "minimum": 0, "description": "Optional connector-reported active product count for drift logging." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/catalog.stats": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "catalog.stats", "description": "Corpus size, schema fingerprint, top-K category breadcrumbs. Read-mostly catalog metadata.", "operationId": "call_catalog_stats", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "top_categories": { "type": "integer", "minimum": 0, "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/chat": { "post": { "tags": [ "Shopper UX" ], "summary": "chat", "description": "Conversational shopper assistant. Runs an LLM-driven loop that issues sub-tool calls (search, suggest, recommend) and returns a cited natural-language answer.", "operationId": "call_chat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "chat", "quiz" ], "description": "Runtime mode. \"chat\" runs the LLM agent loop (default). \"quiz\" runs the deterministic shopping-quiz scorer." }, "quiz_id": { "type": "string" }, "quiz_slug": { "type": "string" }, "answers": { "type": "object", "description": "Map of question_id -> selected option value (single-type) or list of values (multi-type). Required when mode=quiz." }, "messages": { "type": "array", "description": "Conversation so far. Each item is { role: \"user\" | \"assistant\", content: string }.", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } }, "required": [ "role", "content" ] } }, "shopper_context": { "type": "object", "description": "Optional shopper-context envelope (customer_id, country, currency, …). Passed through to sub-tool calls verbatim." }, "max_tool_calls": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Per-turn ceiling on sub-tool calls. Gateway clamps to its own ceiling." }, "session_id": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/commerce.boost_by_stock": { "post": { "tags": [ "Commerce" ], "summary": "commerce.boost_by_stock", "description": "Set stock_ranking_policy=demote_all_oos via tenant.config.set. Mutating.", "operationId": "call_commerce_boost_by_stock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/commerce.exclude_out_of_stock": { "post": { "tags": [ "Commerce" ], "summary": "commerce.exclude_out_of_stock", "description": "Set stock_ranking_policy=exclude_all_oos via tenant.config.set. Mutating.", "operationId": "call_commerce_exclude_out_of_stock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/commerce.promotions.list": { "post": { "tags": [ "Commerce" ], "summary": "commerce.promotions.list", "description": "List active commerce promotions. Unavailable on commerce/Growth representative plan (plan or vertical gated). Stub — returns 501 until implemented.", "operationId": "call_commerce_promotions_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/deboosts.list": { "post": { "tags": [ "Merchandising" ], "summary": "deboosts.list", "description": "List deboost merchandising rules for the tenant.", "operationId": "call_deboosts_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ], "description": "Optional status filter; defaults to all." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/deboosts.remove": { "post": { "tags": [ "Merchandising" ], "summary": "deboosts.remove", "description": "Delete a deboost merchandising rule by id. Mutating.", "operationId": "call_deboosts_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/deboosts.set": { "post": { "tags": [ "Merchandising" ], "summary": "deboosts.set", "description": "Create or update a deboost merchandising rule. Mutating.", "operationId": "call_deboosts_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "doc_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 100 }, "factor": { "type": "number", "minimum": 0, "maximum": 1 }, "scope": { "type": "string", "enum": [ "query", "category", "global" ] }, "scope_value": { "type": "string" }, "match_mode": { "type": "string", "enum": [ "exact", "contains" ] }, "audience_segment_id": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ] }, "region_id": { "type": "string", "description": "Sprint 9 — deboost only fires when the resolved region matches this id. Omit to apply to all regions." } }, "required": [ "doc_ids", "factor", "scope" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/esp.dlq_recent": { "post": { "tags": [ "ESP integrations" ], "summary": "esp.dlq_recent", "description": "Recent ESP DLQ rows for the admin failure-visibility surface.", "operationId": "call_esp_dlq_recent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/esp.test_event": { "post": { "tags": [ "ESP integrations" ], "summary": "esp.test_event", "description": "Fire a synthetic event at the configured ESP and return the provider verdict synchronously. Mutating.", "operationId": "call_esp_test_event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "test_email": { "type": "string", "description": "Email to attach to the test event (e.g. operator@tenant.com). Required for Mailchimp / Klaviyo identification." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/events": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "events", "description": "Record search / click / impression events for analytics, LTR training, and bot-check verdict tagging. Mutating.", "operationId": "call_events", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "search", "click", "impression", "add_to_cart", "purchase" ] }, "session_id": { "type": "string" }, "keyword": { "type": "string" }, "product_id": { "type": "integer" }, "position": { "type": "integer" }, "result_count": { "type": "integer" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "referer": { "type": "string" }, "nonce": { "type": "string" }, "search_event_id": { "type": "integer" }, "filter_by": { "type": "string" }, "filters": { "type": "object" }, "latency_ms": { "type": "integer" }, "fallback_used": { "type": "boolean" }, "qty": { "type": "integer", "minimum": 0 }, "price_cents": { "type": "integer" }, "currency": { "type": "string", "maxLength": 3 }, "order_id": { "type": "string", "maxLength": 128 }, "extra": { "type": "object" }, "shopper_context": { "type": "object" } }, "required": [ "event_type" ] }, "maxItems": 200 }, "shopper_context": { "type": "object" } }, "required": [ "events" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.assignments.bulk_upsert": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.assignments.bulk_upsert", "description": "Bulk-upsert per-tenant product fitment assignments against central seekmodo_vehicle_id values. Mutating.", "operationId": "call_fitment_assignments_bulk_upsert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "maxItems": 1000, "items": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1 }, "seekmodo_vehicle_id": { "type": "integer", "minimum": 1 }, "engine_trans_code": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "product_id", "seekmodo_vehicle_id" ] } } }, "required": [ "rows" ] } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.assignments.changes": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.assignments.changes", "description": "Return per-tenant fitment assignment rows changed since updated_since (ISO-8601).", "operationId": "call_fitment_assignments_changes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated_since": { "type": "string" }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "updated_since" ] } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.coverage": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.coverage", "description": "Coverage aggregates over numinix_mcp_vehicle_taxonomy for the tenant.", "operationId": "call_fitment_coverage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stale_hours": { "type": "integer", "minimum": 1, "maximum": 720 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.import.csv": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.import.csv", "description": "Import fitment assignments from CSV text. Resolves YMM to central catalog (auto-creates merchant_import vehicles when missing). Mutating.", "operationId": "call_fitment_import_csv", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "Raw CSV body with header row." }, "product_id_map": { "type": "object", "description": "Map of sku => platform product_id (resolved by connector/admin).", "additionalProperties": { "type": "integer" } }, "default_source": { "type": "string" } }, "required": [ "csv", "product_id_map" ] } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.orphans": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.orphans", "description": "Vehicles with zero fitted products (product_count=0) for the tenant.", "operationId": "call_fitment_orphans", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "freshness_floor_hours": { "type": "integer", "minimum": 0, "maximum": 720 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.overrides.list": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.overrides.list", "description": "Paginated list of per-tenant fitment overrides (operator-set add/remove rules layered on top of the AutoPro fitment graph).", "operationId": "call_fitment_overrides_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 500 }, "product_id": { "type": "integer", "minimum": 1, "description": "Optional product_id filter for the connector pull path." }, "since": { "type": "string", "description": "Optional ISO-8601 lower bound on created_at (>=). Used by the connector for incremental pulls." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/fitment.resolve": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "fitment.resolve", "description": "Resolve a (year, make, model) triple against the per-tenant vehicle taxonomy projection into a concrete vehicle_id + canonical label. Returns null when no row matches.", "operationId": "call_fitment_resolve", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Four-digit model year, e.g. 2019." }, "make": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Make name, case-insensitive (\"honda\" matches \"Honda\")." }, "model": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Model name, case-insensitive." } }, "required": [ "year", "make", "model" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Build info + liveness", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/v1/index": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "index", "description": "Bulk upsert documents into the tenant's Typesense collection. Mirrors the documents/import wire shape. Mutating.", "operationId": "call_index", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "product", "policy" ], "default": "product" }, "action": { "type": "string", "enum": [ "create", "upsert", "emplace", "update" ], "default": "upsert" }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 1000 }, "docs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 1000 }, "collection": { "type": "string", "description": "Informational; gateway routes by tenant.vertical regardless. Accepted for connector back-compat." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.config.set": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.config.set", "description": "Patch per-tenant LTR settings (management, mode, ab_ramp_pct, etc). Mutating.", "operationId": "call_ltr_config_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "management": { "type": "string", "enum": [ "off", "auto", "shadow" ], "description": "LTR posture: off | auto (HealthMonitor) | shadow (sticky park)" }, "mode": { "type": "string", "enum": [ "off", "shadow", "ab", "on" ] }, "ab_ramp_pct": { "type": "integer", "minimum": 0, "maximum": 95 }, "ndcg_floor_pct": { "type": "integer", "minimum": 0, "maximum": 100 }, "min_clicks": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "vertical_extractor": { "type": [ "string", "null" ], "enum": [ null, "commerce", "content" ] }, "ips_correction": { "type": "boolean" }, "accept_binary_labels": { "type": "boolean", "description": "Allow training when max grade is click-only (1); for low-volume tenants" }, "training_labels_after": { "type": [ "string", "null" ], "description": "Only harvest engagement rows on/after this UTC datetime (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS). Null clears." }, "training_clicks_only": { "type": "boolean" }, "commerce_feature_version": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 99 }, "lambdamart_min_linked_clicks": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 100000 }, "shadow_pinned_until": { "type": [ "string", "null" ] }, "last_promoted_at_reason": { "type": [ "string", "null" ], "maxLength": 40 }, "personalization_enabled": { "type": "boolean" }, "personalization_retention_days": { "type": "integer", "minimum": 30, "maximum": 365 }, "lambdamart_train_params": { "type": [ "object", "null" ], "description": "Optional LightGBM overrides: num_rounds, max_depth, eta, holdout_ratio." }, "optimizer_enabled": { "type": "boolean", "description": "Allow LTR AI optimizer propose/apply for this tenant." }, "optimizer_auto_apply": { "type": "boolean", "description": "Fleet cron may auto-apply allowlisted proposals (Growth+ after online win)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.diagnostics": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.diagnostics", "description": "Snapshot of LTR pipeline health: scorer reachability, linked-click coverage, filter diversity, AGREE-rate, arm CTR.", "operationId": "call_ltr_diagnostics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lookback_hours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 336 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.model.rollback": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.model.rollback", "description": "Operator action: roll the tenant back to a previously trained LTR model. Requires a free-text reason. Mutating.", "operationId": "call_ltr_model_rollback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "maxLength": 32 }, "reason": { "type": "string", "minLength": 4, "maxLength": 512 } }, "required": [ "model_id", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.retrain": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.retrain", "description": "Force-retrain the LTR model now. Returns the new model summary. Mutating.", "operationId": "call_ltr_retrain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.shadow_deltas": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.shadow_deltas", "description": "List recent shadow-mode disagreements between LambdaMART and the served top-1 for operator gut-check.", "operationId": "call_ltr_shadow_deltas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "lookback_hours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 168 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.shadow_feedback": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.shadow_feedback", "description": "Record operator gut-check (thumbs up/down) on a shadow-mode LambdaMART disagreement. Mutating.", "operationId": "call_ltr_shadow_feedback", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "search_event_id", "judgement" ], "properties": { "search_event_id": { "type": "integer", "minimum": 1 }, "judgement": { "type": "integer", "enum": [ -1, 0, 1 ] }, "reranker_top_pid": { "type": [ "integer", "null" ] }, "lambdamart_top_pid": { "type": [ "integer", "null" ] }, "operator_id": { "type": [ "string", "null" ], "maxLength": 64 }, "operator_note": { "type": [ "string", "null" ], "maxLength": 512 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.status": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.status", "description": "Read LTR settings, the active model summary, and recent training runs.", "operationId": "call_ltr_status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "history_limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "history_offset": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/ltr.toggle": { "post": { "tags": [ "Learning-to-rank" ], "summary": "ltr.toggle", "description": "Toggle Learning-to-Rank on or off for the tenant. Mutating.", "operationId": "call_ltr_toggle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/nonce.issue": { "post": { "tags": [ "Bot defence" ], "summary": "nonce.issue", "description": "Issue an HMAC nonce for the SERP click-beacon flow.", "operationId": "call_nonce_issue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "keyword" ], "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "keyword": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/nonce.verify": { "post": { "tags": [ "Bot defence" ], "summary": "nonce.verify", "description": "Verify an HMAC nonce for the SERP click-beacon flow; returns valid bool + age + reason.", "operationId": "call_nonce_verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "keyword", "nonce" ], "properties": { "session_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "keyword": { "type": "string", "minLength": 1, "maxLength": 256 }, "nonce": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/pins.landscape": { "post": { "tags": [ "Merchandising" ], "summary": "pins.landscape", "description": "Snapshot of active pin rules with priority, schedule, audience, and metadata.", "operationId": "call_pins_landscape", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_inactive": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/pins.list": { "post": { "tags": [ "Merchandising" ], "summary": "pins.list", "description": "Read editorial pins for the tenant.", "operationId": "call_pins_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/pins.remove": { "post": { "tags": [ "Merchandising" ], "summary": "pins.remove", "description": "Delete a pin entry by id. Mutating.", "operationId": "call_pins_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "dry_run": { "type": "boolean", "description": "If true, validate + preview the change without applying. Default false. The response contains a `would_*` key with the planned shape; re-call without dry_run to apply." } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/pins.set": { "post": { "tags": [ "Merchandising" ], "summary": "pins.set", "description": "Pin or exclude documents for a specific query. Mutating.", "operationId": "call_pins_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional stable id. Defaults to rule_<16 hex>." }, "query": { "type": "string", "minLength": 1, "maxLength": 128 }, "pinned_doc_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 0, "maxItems": 50 }, "excluded_doc_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "match": { "type": "string", "enum": [ "exact", "contains" ], "description": "How the query should be matched. Defaults to exact." }, "region_id": { "type": "string", "description": "Sprint 9 — pin only fires when the resolved region matches this id. Omit to apply to all regions." }, "dry_run": { "type": "boolean", "description": "If true, validate + preview the change without applying. Default false. The response contains a `would_*` key with the planned shape; re-call without dry_run to apply." } }, "required": [ "query" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/recommend.also_bought": { "post": { "tags": [ "Recommendations" ], "summary": "recommend.also_bought", "description": "Anchor-anchored frequently-bought-together recommendations from co-purchase signal with lexical fallback.", "operationId": "call_recommend_also_bought", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anchor_doc_id": { "type": "string", "description": "Source product id to base recommendations on." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "shopper_context": { "type": "object" }, "filter_by": { "type": "string", "maxLength": 512, "description": "Typesense filter_by clause AND-ed onto the doc-id hydrate predicate." } }, "required": [ "anchor_doc_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/recommend.also_viewed": { "post": { "tags": [ "Recommendations" ], "summary": "recommend.also_viewed", "description": "Anchor-anchored also-viewed recommendations from broad same-session signal with lexical fallback.", "operationId": "call_recommend_also_viewed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anchor_doc_id": { "type": "string", "description": "Source product id to base recommendations on." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "shopper_context": { "type": "object" }, "filter_by": { "type": "string", "maxLength": 512, "description": "Typesense filter_by clause AND-ed onto the doc-id hydrate predicate." } }, "required": [ "anchor_doc_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/recommend.related": { "post": { "tags": [ "Recommendations" ], "summary": "recommend.related", "description": "Anchor-anchored related-products recommendations from co-view signal with lexical fallback.", "operationId": "call_recommend_related", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anchor_doc_id": { "type": "string", "description": "Source product id to base recommendations on." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "shopper_context": { "type": "object" }, "filter_by": { "type": "string", "maxLength": 512, "description": "Typesense filter_by clause AND-ed onto the doc-id hydrate predicate." } }, "required": [ "anchor_doc_id" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/recommend.trending": { "post": { "tags": [ "Recommendations" ], "summary": "recommend.trending", "description": "Non-anchored trending products recommendation (last-30-day co-occurrence aggregation).", "operationId": "call_recommend_trending", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "filter_by": { "type": "string", "maxLength": 512, "description": "Typesense filter_by clause AND-ed onto the doc-id hydrate predicate." } }, "required": [], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/redirects.list": { "post": { "tags": [ "Merchandising" ], "summary": "redirects.list", "description": "List keyword redirect merchandising rules for the tenant.", "operationId": "call_redirects_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/redirects.propose": { "post": { "tags": [ "Merchandising" ], "summary": "redirects.propose", "description": "Propose keyword redirect rules from search telemetry (dry-run only).", "operationId": "call_redirects_propose", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/redirects.remove": { "post": { "tags": [ "Merchandising" ], "summary": "redirects.remove", "description": "Delete a keyword redirect merchandising rule by id. Mutating.", "operationId": "call_redirects_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/redirects.set": { "post": { "tags": [ "Merchandising" ], "summary": "redirects.set", "description": "Create or update a keyword redirect merchandising rule. Mutating.", "operationId": "call_redirects_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "target_url": { "type": "string", "minLength": 1 }, "terms": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "label": { "type": "string" }, "scope": { "type": "string", "enum": [ "query", "global" ] }, "scope_value": { "type": "string" }, "match_mode": { "type": "string", "enum": [ "exact", "contains" ] }, "audience_segment_id": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 }, "status": { "type": "string", "enum": [ "draft", "active", "expired", "disabled" ] }, "region_id": { "type": "string" } }, "required": [ "target_url", "terms" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/resolve_redirect": { "post": { "tags": [ "Merchandising" ], "summary": "resolve_redirect", "description": "Resolve a shopper query to a merchandising redirect URL, if any.", "operationId": "call_resolve_redirect", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "shopper_context": { "type": "object" } }, "required": [ "q" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/search": { "post": { "tags": [ "Search" ], "summary": "search", "description": "Read-only corpus search. Body params are passthrough to the per-tenant Typesense collection.", "operationId": "call_search", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query string" }, "query_by": { "type": "string", "description": "Comma-separated field list to search" }, "filter_by": { "type": "string" }, "sort_by": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 250 }, "facet_by": { "type": "string" }, "session_id": { "type": "string", "description": "Originating shopper session id; required for bot-check classification." }, "ua": { "type": "string", "description": "Originating shopper User-Agent; required for bot-check classification." }, "ip": { "type": "string", "description": "Originating shopper IP; required for bot-check classification. Connector should resolve through CF-Connecting-IP / X-Forwarded-For." }, "referer": { "type": "string", "description": "Originating shopper Referer header; recorded in telemetry for analytics." }, "lang": { "type": "string", "description": "ISO 639-1 / BCP-47 storefront language (de, en-US). When the collection has a lang facet, hits are scoped to that language." }, "skip_merchandising_redirect": { "type": "boolean", "description": "When true, skip keyword-redirect short-circuit and return ranked product hits (view-all / explicit SERP intent)." }, "filters": { "type": "object", "description": "Structured filter map: field => scalar | list | { op, value }. Normalized for telemetry / LTR attribution." }, "price_from": { "type": "number", "description": "Inclusive minimum price (vanilla Zen Cart pfrom)." }, "price_to": { "type": "number", "description": "Inclusive maximum price (vanilla Zen Cart pto)." }, "shopper_context": { "type": "object", "description": "Connector-reported shopper facts (customer_group, country, logged_in, ...) used to match audience segments for merchandising rules." }, "parse_nl": { "type": "boolean", "description": "Run the query through the NL intent parser before search. Fails open to lexical on any LLM error." }, "image_b64": { "type": "string", "description": "Base64-encoded query image for hybrid mode. Max ~2 MB encoded. Requires image_search entitlement." }, "image_url": { "type": "string", "description": "URL the embed worker should fetch for hybrid mode. Mutually exclusive with image_b64." }, "image_blend_weight": { "type": "number", "minimum": 0, "maximum": 1, "description": "Per-request override of the tenant default for the vector vs text blend (0=text-only, 1=image-only, 0.5=even)." } }, "required": [ "q" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/search.byImage": { "post": { "tags": [ "Search" ], "summary": "search.byImage", "description": "Image-as-query corpus search. Accepts one of {image_b64, image_url, doc_id} and returns SKUs visually similar to the query via CLIP ViT-B/32 + Typesense vector_query.", "operationId": "call_search_byImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_b64": { "type": "string", "description": "Base64-encoded image (no data: prefix). Max ~2 MB encoded. Mutually exclusive with image_url and doc_id." }, "image_url": { "type": "string", "description": "Publicly fetchable URL the embed worker will GET. Mutually exclusive with image_b64 and doc_id." }, "doc_id": { "type": "string", "description": "\"More like this\" mode — read the existing image_embedding vector off the indexed doc. Skips the embed worker call entirely. Mutually exclusive with image_b64 and image_url." }, "filter_by": { "type": "string", "description": "Optional Typesense filter_by clause; ANDed with the vendor default for the vertical (e.g. products_status gate)." }, "sort_by": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100 }, "facet_by": { "type": "string" }, "include_fields": { "type": "string" }, "exclude_fields": { "type": "string" }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "referer": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/search.by_vehicle": { "post": { "tags": [ "Search" ], "summary": "search.by_vehicle", "description": "Vehicle-id-scoped corpus search. Returns products whose `fits_vehicles` int[] contains the requested vehicle_id.", "operationId": "call_search_by_vehicle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vehicle_id": { "type": "integer", "minimum": 1, "description": "Concrete vehicle id from the fitment graph. Mutually optional with (year, make, model)." }, "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Model year (e.g. 2019). Used with `make` + `model` when vehicle_id is omitted." }, "make": { "type": "string", "description": "Vehicle make (e.g. \"Honda\"). Case-insensitive." }, "model": { "type": "string", "description": "Vehicle model (e.g. \"Civic\"). Case-insensitive." }, "q": { "type": "string", "description": "Optional free-text query to refine within the vehicle (e.g. \"door handle\"). Defaults to \"*\" (match everything that fits)." }, "filter_by": { "type": "string", "description": "Optional additional filter_by clause; ANDed with the vehicle filter." }, "sort_by": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 250 }, "facet_by": { "type": "string" }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "referer": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/segments.list": { "post": { "tags": [ "Merchandising" ], "summary": "segments.list", "description": "List customer segments for the tenant.", "operationId": "call_segments_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled_only": { "type": "boolean", "description": "When true, filters out disabled segments." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/segments.remove": { "post": { "tags": [ "Merchandising" ], "summary": "segments.remove", "description": "Delete a customer segment by id. Mutating.", "operationId": "call_segments_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/segments.set": { "post": { "tags": [ "Merchandising" ], "summary": "segments.set", "description": "Create or update a customer segment. Mutating.", "operationId": "call_segments_set", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional stable id. Defaults to seg_<12 hex>." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "match_rule": { "type": "object", "description": "DSL: {all|any|: value-or-list}" }, "enabled": { "type": "boolean", "description": "Defaults to true." }, "region_id": { "type": "string", "description": "Sprint 9 — segment only matches when the resolved region matches this id. Omit to apply to all regions." } }, "required": [ "display_name", "match_rule" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/suggest": { "post": { "tags": [ "Search" ], "summary": "suggest", "description": "Typeahead suggestions: prior-search keywords, prefix-matched products, and matching categories.", "operationId": "call_suggest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Prefix the shopper has typed so far." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "lang": { "type": "string" }, "complete": { "type": "boolean" }, "include_products": { "type": "boolean" }, "include_keywords": { "type": "boolean" }, "include_recent": { "type": "boolean" }, "include_trending": { "type": "boolean" } }, "required": [ "q" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/synonyms.add": { "post": { "tags": [ "Merchandising" ], "summary": "synonyms.add", "description": "Add or replace a synonym entry. id is optional; we generate one if omitted. Mutating.", "operationId": "call_synonyms_add", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional stable id. Defaults to syn_<8 hex>." }, "root": { "type": [ "string", "null" ], "description": "Optional root term (one-way). Null for symmetric synonyms." }, "synonyms": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 32 }, "dry_run": { "type": "boolean", "description": "If true, validate + preview the change without applying. Default false." } }, "required": [ "synonyms" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/synonyms.list": { "post": { "tags": [ "Merchandising" ], "summary": "synonyms.list", "description": "Read the per-tenant synonym list. Returns Typesense-native synonym entries.", "operationId": "call_synonyms_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/synonyms.remove": { "post": { "tags": [ "Merchandising" ], "summary": "synonyms.remove", "description": "Delete a synonym entry by id. Mutating.", "operationId": "call_synonyms_remove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "dry_run": { "type": "boolean", "description": "If true, validate + preview the change without applying. Default false. The response contains a `would_*` key with the planned shape; re-call without dry_run to apply." } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tenant.catalog_preview": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "tenant.catalog_preview", "description": "Return a small sample of indexed documents (admin only). With `q`, runs a prefix-match autocomplete used by the admin doc picker.", "operationId": "call_tenant_catalog_preview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "q": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tenant.domain.promote": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "tenant.domain.promote", "description": "Self-service swap of the tenant's canonical storefront host. Used by connectors to flip from dev -> prod without an operator round-trip. Mutating.", "operationId": "call_tenant_domain_promote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_host": { "type": "string", "maxLength": 253, "description": "The hostname to promote to (no scheme, no path). Must already appear in observed_domains_json for this tenant." }, "previous_host": { "type": [ "string", "null" ] }, "platform": { "type": "string" }, "connector_version": { "type": "string" } }, "required": [ "new_host" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tenant.handshake": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "tenant.handshake", "description": "Verify connector configuration and discover the tenant's tool surface, vertical, and rate limits.", "operationId": "call_tenant_handshake", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_version": { "type": "string", "maxLength": 16 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tenant.region.list": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "tenant.region.list", "description": "Read tenant-level multi-region flags + every numinix_mcp_tenant_regions row.", "operationId": "call_tenant_region_list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tenant.snapshot": { "post": { "tags": [ "Catalog & telemetry" ], "summary": "tenant.snapshot", "description": "Read (or push to) the full tenant runtime config snapshot.", "operationId": "call_tenant_snapshot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "description": "Optional connector-side FSM snapshot to record.", "properties": { "auto_state": { "type": [ "string", "null" ] }, "auto_state_since": { "type": [ "string", "null" ] }, "auto_history": { "type": [ "array", "string" ], "description": "Last 16 transitions; array preferred." }, "observed_count": { "type": "integer", "minimum": 0 }, "errors_count": { "type": "integer", "minimum": 0 }, "env": { "type": "object", "description": "PHP environment snapshot from the connector host (v1.0.19+).", "properties": { "php_version": { "type": "string", "description": "PHP_VERSION on the connector host (e.g. 8.1.34)." }, "php_sapi": { "type": "string" }, "sodium_loaded": { "type": "boolean" }, "apcu_loaded": { "type": "boolean", "description": "extension loaded AND apc.enabled=1." }, "apcu_extension": { "type": "boolean", "description": "extension loaded regardless of apc.enabled." }, "opcache_enabled": { "type": "boolean" }, "curl_loaded": { "type": "boolean" }, "openssl_loaded": { "type": "boolean" }, "mysqli_loaded": { "type": "boolean" }, "intl_loaded": { "type": "boolean" }, "json_loaded": { "type": "boolean" }, "server_time_unix": { "type": "integer", "description": "Connector wall-clock at push time; gateway computes clock skew from this." } }, "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/tools": { "get": { "tags": [ "Catalog" ], "summary": "List tools available to your tenant (includes inputSchema)", "operationId": "listTools", "responses": { "200": { "description": "Tool descriptors", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDescriptor" } } }, "required": [ "tools" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/tools/public": { "get": { "tags": [ "Catalog" ], "summary": "Unauthenticated public tool catalog (no inputSchema; feeds /docs/mcp)", "operationId": "listToolsPublic", "security": [], "responses": { "200": { "description": "Public tool list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "available": { "type": "boolean" }, "mutates": { "type": "boolean" }, "category": { "type": "string" } }, "required": [ "name", "available", "mutates" ] } }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "tools" ] } } } } } } }, "/v1/typeahead": { "post": { "tags": [ "Search" ], "summary": "typeahead", "description": "Flat-row typeahead for storefront connectors. Returns N prefix-matched docs from the tenant Typesense collection in the legacy {rows} shape WP / Zen Cart connectors expect.", "operationId": "call_typeahead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Prefix the shopper has typed so far." }, "max": { "type": "integer", "minimum": 1, "maximum": 25 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "vertical": { "type": "string", "enum": [ "commerce", "content", "kb", "community" ] }, "session_id": { "type": "string" }, "ua": { "type": "string" }, "ip": { "type": "string" }, "complete": { "type": "boolean" } }, "required": [ "q" ], "additionalProperties": true } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicle.taxonomy.lookup": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicle.taxonomy.lookup", "description": "Resolve a per-tenant vehicle taxonomy row by VLP slug (e.g. \"keys-for-2019-honda-civic\") or by vehicle_id. Returns the canonical row used by the BC Worker VLP renderer.", "operationId": "call_vehicle_taxonomy_lookup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 200, "description": "VLP slug as the connector stored it (canonicalised, lowercase, hyphen-separated). Mutually exclusive with vehicle_id." }, "vehicle_id": { "type": "integer", "minimum": 1, "description": "Numeric vehicle_id from a prior fitment.resolve / search.byVehicle round-trip. Mutually exclusive with slug." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicle.taxonomy.neighbours": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicle.taxonomy.neighbours", "description": "Return the two AKS-canonical neighbour lanes (same make+model different year; same year+make different model) for a given vehicle_id in the per-tenant projection.", "operationId": "call_vehicle_taxonomy_neighbours", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vehicle_id": { "type": "integer", "minimum": 1, "description": "Anchor vehicle_id (typically from a prior vehicle.taxonomy.lookup or fitment.resolve call)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Per-lane cap on returned rows. Defaults to 12 (matches AKS VlpInternalLinkRenderer)." } }, "required": [ "vehicle_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicle_taxonomy.bulk_upsert": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicle_taxonomy.bulk_upsert", "description": "Bulk-upsert vehicle taxonomy rows (year/make/model + pre-computed VLP slug + product_count) into the per-tenant projection. Up to 1000 rows per call. Called by the connector's seekmodo:vlp-project artisan command. Mutating.", "operationId": "call_vehicle_taxonomy_bulk_upsert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "vehicle_id": { "type": "integer", "minimum": 1 }, "year_start": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 2100 }, "year_end": { "type": [ "integer", "null" ], "minimum": 1900, "maximum": 2100 }, "make_id": { "type": [ "integer", "null" ], "minimum": 1 }, "make_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "model_id": { "type": [ "integer", "null" ], "minimum": 1 }, "model_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180 }, "product_count": { "type": "integer", "minimum": 0 } }, "required": [ "vehicle_id", "make_name", "model_name", "slug", "product_count" ], "additionalProperties": false } } }, "required": [ "rows" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicle_taxonomy.prune": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicle_taxonomy.prune", "description": "Delete vehicle taxonomy rows whose last_seen_at is older than the supplied UTC cutoff (ISO 8601). Called after a successful seekmodo:vlp-project run so vehicles that disappear from the connector's projection stop appearing in the gateway sitemap. Mutating.", "operationId": "call_vehicle_taxonomy_prune", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cutoff_utc": { "type": "string", "minLength": 10, "maxLength": 40, "description": "UTC cutoff in YYYY-MM-DD HH:MM:SS or ISO-8601 form. Rows with last_seen_at strictly older are deleted." } }, "required": [ "cutoff_utc" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicles.catalog.changes": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicles.catalog.changes", "description": "Return central vehicle catalog rows changed since updated_since (ISO-8601). Supports cursor pagination.", "operationId": "call_vehicles_catalog_changes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated_since": { "type": "string", "description": "ISO-8601 lower bound on updated_at (>=)." }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "updated_since" ] } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicles.catalog.lookup": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicles.catalog.lookup", "description": "Resolve year/make/model (and optional engine_trans_code) against the central Seekmodo vehicle catalog.", "operationId": "call_vehicles_catalog_lookup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "make": { "type": "string" }, "model": { "type": "string" }, "engine_trans_code": { "type": "string" }, "provider": { "type": "string" }, "provider_vehicle_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } }, "/v1/vehicles.picker.options": { "post": { "tags": [ "Fitment & vehicles" ], "summary": "vehicles.picker.options", "description": "Return cascading YMM picker options for vehicles that have at least one product assignment for this tenant.", "operationId": "call_vehicles_picker_options", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "make": { "type": "string" }, "model": { "type": "string" } } } } } }, "responses": { "200": { "description": "Tool result (shape varies by tool)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Accepted (async tools such as events may return 202)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "description": "Tool unavailable for this plan/vertical, or stub" } } } } }, "components": { "securitySchemes": { "SeekmodoHmac": { "type": "apiKey", "in": "header", "name": "X-Seekmodo-Signature", "description": "HMAC-SHA256 hex digest of the **raw HTTP request body** using the tenant shared secret (`hash_hmac('sha256', $rawBody, $sharedSecret)`). Also send `X-Seekmodo-Tenant` and `X-Seekmodo-Timestamp` (Unix seconds; ±5 minute replay window). Nonce headers are ignored by the gateway." } }, "responses": { "Unauthorized": { "description": "HMAC verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded for tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid JSON body or tool arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "version": { "type": "string" }, "build_sha": { "type": "string" }, "tenant_count": { "type": "integer" }, "uptime_s": { "type": "integer" } }, "required": [ "status", "version" ] }, "ToolDescriptor": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true }, "available": { "type": "boolean" }, "mutates": { "type": "boolean" }, "supports_streaming": { "type": "boolean" } }, "required": [ "name", "available", "mutates" ] }, "Error": { "type": "object", "properties": { "error": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } ] } } } } } }