{"openapi": "3.1.0", "info": {"title": "SellerMate Public API", "version": "1.0.0", "description": "Programmatic access to your SellerMate data and actions \u2014 the same permission-checked,\npolicy-guarded, audit-logged engine that powers the SellerMate app and MCP server.\n\n## Authentication\n\nSend your API key on every request, either way:\n\n- `X-API-Key: sm_live_\u2026`\n- `Authorization: Bearer sm_live_\u2026`\n\nKeys are created by a workspace admin in the SellerMate web app (**Profile \u2192 API Keys**),\nshown once at creation, scoped to a single workspace, optionally restricted to specific\nAmazon accounts, and revocable at any time. Treat them like passwords \u2014 server-to-server\nuse only.\n\n## Scopes\n\n- `tools:read` \u2014 analytics, reports, and inventory tools.\n- `tools:write` \u2014 mutation tools (budgets, bids, campaign creation, \u2026). Write actions\n  also pass the workspace's policy guardrails: a blocked action returns `422` and is not\n  applied. There is no approval queue \u2014 a write that clears the guardrails is applied\n  immediately, so treat `422` as the only outcome that stops one.\n\n## Rate limits\n\nPer-key rate limit (default 120 requests/minute) and a per-IP failed-auth lockout both\nreturn `429` with a `Retry-After` header (seconds). Don't retry `401`s \u2014 a bad key won't\nstart working.\n\n## How arguments bind\n\n- `workspace_id` is **always** taken from your API key \u2014 never send it.\n- `amazon_account_id`: auto-filled if your key is restricted to exactly one account;\n  otherwise pass the account id from `get_user_context`.\n- Dates are `YYYY-MM-DD` strings unless a tool says otherwise.\n- Report tools paginate with `page` (0-indexed; the Amazon Marketing Cloud tools count\n  from 1 and say so) + `page_size` and return a `pagination` block; `summary` totals\n  always cover the full result set, not the page.\n\n## Response conventions\n\n- **Success**: the tool's raw result object (no wrapper). Where a tool declares a result\n  schema, its page shows the fields; otherwise the shape is described in the tool's text.\n- **Tool errors**: `{ \"error\": \"\u2026\" }` \u2014 policy violations add `rule` / `scope` / `message`.\n- **Auth / rate-limit errors**: `{ \"status\": <code>, \"message\": \"\u2026\" }`.\n"}, "servers": [{"url": "https://api.sellermate.ai"}], "security": [{"ApiKeyHeader": []}, {"BearerAuth": []}], "tags": [{"name": "Discovery", "description": "Find your workspaces, Amazon accounts, what SellerMate supports, and which report data has arrived."}, {"name": "Campaigns", "description": "Campaign and ad-group inventory, performance, budgets, and creation."}, {"name": "Targeting", "description": "Targets (keywords / product / auto): inventory, performance, and bids."}, {"name": "Negatives", "description": "Negative keywords and negative product targets."}, {"name": "Products & Reports", "description": "Catalog, inventory, retail + ads performance, and Amazon reports."}, {"name": "Tags", "description": "Tags on campaigns, products, targets, and search terms: inventory, create, update, delete."}, {"name": "Amazon DSP", "description": "Amazon DSP (programmatic display/video) campaigns and reports."}, {"name": "Amazon Marketing Cloud", "description": "AMC instances, audiences (templates, size estimates, creation), and AMC reports."}, {"name": "Vendor Central", "description": "Vendor Central sales, inventory, and catalog (vendor accounts)."}, {"name": "Knowledge Files", "description": "Knowledge-base / memory files uploaded to SellerMate."}, {"name": "Automation & Dayparting", "description": "Automations, dayparting schedules, and hourly performance."}, {"name": "Insights & Alerts", "description": "AI performance summary, recommendations, fired alerts, and the activity log."}, {"name": "Other", "description": "Everything else."}], "paths": {"/public/v1/tools": {"get": {"operationId": "listTools", "tags": ["Discovery"], "summary": "List the tools your key can use (with JSON Schemas)", "description": "Returns every tool this key's scopes cover, each with its JSON Schema. This is the machine-readable source of truth for discovery and codegen.", "responses": {"200": {"description": "Tool definitions.", "content": {"application/json": {"schema": {"type": "object", "properties": {"tools": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string"}, "description": {"type": "string"}, "inputSchema": {"type": "object", "additionalProperties": true}}}}}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/public/v1/tools/{tool_name}": {"get": {"operationId": "getToolSchema", "tags": ["Discovery"], "summary": "Get one tool's JSON Schema", "description": "Returns the live schema for a single tool. `404` if unknown or outside your key's scope.", "parameters": [{"name": "tool_name", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "The tool definition.", "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "description": {"type": "string"}, "inputSchema": {"type": "object", "additionalProperties": true}}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}}}}, "/public/v1/tools/check_data_coverage": {"post": {"operationId": "check_data_coverage", "tags": ["Discovery"], "summary": "Check Data Coverage", "description": "Tool name: `check_data_coverage` \u00b7 **Scope:** requires `tools:read`.\n\nWhich days of Amazon report data have actually arrived for an account, so a day that has not synced yet is not read as zero spend. Per feed (campaign, targeting, search-term and advertised-product ads feeds, plus Seller Central and Vendor Central product feeds): a status, the latest date with rows, and `datesWithNoRows`. Use `latestDateAllFeedsHaveRows` as the end date for any answer that mixes ads and retail (TACoS); `notMonitored` lists feeds with no coverage evidence here (placements, SQP, SCP, DSP, orders). `days` sets the window (default 17, max 60); `detail: \"daily\"` adds a row count per date. Read-only \u2014 never triggers a sync.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"days": {"type": "integer", "minimum": 2, "maximum": 60, "description": "Size of the window to inspect, counting back from today and including it. Defaults to 17, the same window the in-app sync dialog shows. Min 2, max 60."}, "detail": {"type": "string", "enum": ["summary", "daily"], "description": "'summary' (default) returns statuses plus the dates with no rows. 'daily' additionally returns 'counts', the row count for every date -- use it to see a gradual decline, which no status or anomaly flag will report."}, "amazon_account_id": {"type": "string", "description": "Amazon account to check. From get_user_context / resolve_account. Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"amazonAccountId": {"type": "string"}, "checkedAt": {"type": "string", "description": "UTC timestamp of this check."}, "dateBasis": {"type": "string", "description": "Which clock the window was built from. 'account-local' means the advertiser's own timezone (see 'timezone'); 'server-local' is the fallback when the account carries no usable timezone, and can differ by a day from the advertiser's calendar."}, "timezone": {"type": ["string", "null"], "description": "IANA zone the dates are in, or null when none is set on the account."}, "dateRange": {"type": "object", "properties": {"start": {"type": "string"}, "end": {"type": "string"}}}, "dates": {"type": "array", "items": {"type": "string"}, "description": "Every date in the inspected window, oldest first."}, "thresholds": {"type": "object", "description": "Anomaly thresholds the statuses were computed with."}, "reports": {"type": "array", "description": "One entry per monitored report feed.", "items": {"type": "object", "properties": {"reportType": {"type": "string"}, "kind": {"type": "string", "enum": ["ads", "seller", "vendor"]}, "monitoringMode": {"type": "string", "enum": ["arrival", "count-anomaly"], "description": "'arrival' checks only the latest date with rows. 'count-anomaly' also compares row volume between dates."}, "skipLastDays": {"type": "integer", "description": "Normal lag for this feed: its most recent N days routinely have no rows yet, so their absence is expected."}, "note": {"type": "string", "description": "Present when no sub-account of this kind is connected."}, "accounts": {"type": "array", "items": {"type": "object", "description": "One sub-account's coverage for this feed.", "properties": {"accountId": {"type": "string"}, "marketplaceId": {"type": "string"}, "sellingPartnerId": {"type": "string"}, "status": {"type": "string", "enum": ["healthy", "stale", "anomaly", "no-data"], "description": "'healthy' = the most recent date has rows (NOT that the window is complete); 'stale' = the latest date with rows is older than this feed's tolerance; 'anomaly' = a large row-volume drop was detected; 'no-data' = no rows anywhere in the window."}, "lastDataDate": {"type": ["string", "null"], "description": "Most recent date with rows, or null if none in this window. Searched only inside the window -- null does not mean the account never had data."}, "daysSinceLastData": {"type": ["integer", "null"]}, "datesWithNoRows": {"type": "array", "items": {"type": "string"}, "description": "Dates in the window with zero rows. Read this rather than 'status': a feed reports 'healthy' whenever its latest date has rows, even with earlier days missing. These dates have NOT arrived; they are not zeros."}, "rowCountTotal": {"type": "integer", "description": "Documents observed across the window."}, "anomalies": {"type": "object", "description": "Date -> detected row-volume drop. Marks the date a drop began, not every affected date. Empty is not proof of completeness.", "additionalProperties": {"type": "object"}}, "counts": {"type": "object", "description": "detail='daily' ONLY -- rows per date.", "additionalProperties": {"type": "integer"}}}, "required": ["accountId", "status", "datesWithNoRows", "rowCountTotal"]}}}, "required": ["reportType", "kind", "accounts"]}}, "datesWithNoRowsInAnyFeed": {"type": "array", "items": {"type": "string"}, "description": "Dates with no rows in ANY applicable feed. These cannot be analysed from any source yet -- not from hourly either. Say the day has not arrived."}, "latestDateWithAnyRows": {"type": ["string", "null"], "description": "MAX across feeds \u2014 the most recent date ANY feed has. Use it to offer a labelled alternative day, NOT as a window bound: on an account whose ads lead retail it names a date retail lacks."}, "lastDataDateBySource": {"type": "object", "description": "Last date each source has rows for; null when that source is not connected or has no rows in the window. End a window on the MINIMUM of the sources the answer actually needs.", "properties": {"ads": {"type": ["string", "null"]}, "seller": {"type": ["string", "null"]}, "vendor": {"type": ["string", "null"]}}}, "latestDateAllFeedsHaveRows": {"type": ["string", "null"], "description": "MIN across every applicable feed \u2014 the latest date on which EVERY source has data. The safe end date for a multi-source answer such as an account summary or any TACoS figure."}, "notFresherThanDaily": {"type": "object", "description": "Source -> why it is NOT a fallback for a missing date, even though it is absent from 'notMonitored'. Hourly data is here.", "additionalProperties": {"type": "string"}}, "notMonitored": {"type": "array", "items": {"type": "string"}, "description": "Data sources with NO coverage evidence here. Never infer their state."}, "howToRead": {"type": "string", "description": "How to interpret these fields correctly."}}, "required": ["amazonAccountId", "dateRange", "dates", "reports"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_sellermate_capabilities": {"post": {"operationId": "get_sellermate_capabilities", "tags": ["Discovery"], "summary": "Get Sellermate Capabilities", "description": "Tool name: `get_sellermate_capabilities` \u00b7 **Scope:** requires `tools:read`.\n\nWhat the SellerMate platform supports beyond these API tools, with deep links. Pass an optional `query` describing what you're trying to do.", "x-permission-level": "read", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "What the user is trying to do, e.g. 'dayparting', 'create campaigns', 'organic vs ads data', 'track competitor rankings'. Used to highlight the most relevant capabilities in the response."}, "amazon_account_id": {"type": "string", "description": "Optional Amazon account ID to build direct deep links. Auto-filled when your API key is restricted to a single Amazon account."}}}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Catalog of SellerMate platform capabilities grouped by category with deep links, the MCP write/knowledge/data-quality tool lists, and (when a query is given) the top matching features.", "properties": {"allCapabilities": {"type": "object", "description": "Feature catalog keyed by category name (e.g. \"AI & Intelligence\", \"Automation\", \"Campaign Management\").", "additionalProperties": {"type": "array", "description": "Features in this category.", "items": {"type": "object", "description": "One platform feature.", "properties": {"name": {"type": "string", "description": "Feature name."}, "description": {"type": "string", "description": "Feature description."}, "platformUrl": {"type": "string", "description": "Deep link to the feature on the platform."}}, "required": ["name", "description", "platformUrl"]}}}, "mcpWriteTools": {"type": "array", "description": "MCP write tools available with write permission.", "items": {"type": "object", "description": "Name and description of an MCP tool.", "properties": {"name": {"type": "string", "description": "Tool name."}, "description": {"type": "string", "description": "Tool description."}}, "required": ["name", "description"]}}, "mcpKnowledgeTools": {"type": "array", "description": "MCP knowledge and memory file tools.", "items": {"type": "object", "description": "Name and description of an MCP tool.", "properties": {"name": {"type": "string", "description": "Tool name."}, "description": {"type": "string", "description": "Tool description."}}, "required": ["name", "description"]}}, "mcpDataQualityTools": {"type": "array", "description": "MCP data-coverage tools (check_data_coverage).", "items": {"type": "object", "description": "Name and description of an MCP tool.", "properties": {"name": {"type": "string", "description": "Tool name."}, "description": {"type": "string", "description": "Tool description."}}, "required": ["name", "description"]}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant (with wid/aid when supplied)."}, "platformUrl": {"type": "string", "description": "SellerMate platform base URL."}, "note": {"type": "string", "description": "Long guidance text on how to route requests across MCP tools and the platform."}, "relevantFeatures": {"type": "array", "description": "Present only when query is given and matches: up to 5 features ranked by relevance.", "items": {"type": "object", "description": "A matching feature with its category.", "properties": {"name": {"type": "string", "description": "Feature name."}, "category": {"type": "string", "description": "Feature category."}, "description": {"type": "string", "description": "Feature description."}, "platformUrl": {"type": "string", "description": "Deep link to the feature on the platform."}}, "required": ["name", "category", "description", "platformUrl"]}}}, "required": ["allCapabilities", "mcpWriteTools", "mcpKnowledgeTools", "mcpDataQualityTools", "chatAssistantUrl", "platformUrl", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_user_context": {"post": {"operationId": "get_user_context", "tags": ["Discovery"], "summary": "Get User Context", "description": "Tool name: `get_user_context` \u00b7 **Scope:** requires `tools:read`.\n\nYour accessible workspaces and Amazon accounts \u2014 each account with `id`, `name`, `accountType` (`seller` / `vendor` / `agency`), country, currency, and marketplace, plus `hasDsp` (an active Amazon DSP advertiser is linked). Call this first to get the account IDs the other tools need. Pass `has_dsp: true` to return only DSP-enabled accounts.", "x-permission-level": "read", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"account_name_search": {"type": "string", "description": "Optional. Case-insensitive substring to filter accounts by name. Use this to resolve a named account (e.g. 'rolex') to its ids."}, "has_dsp": {"type": "boolean", "description": "Optional. true returns ONLY accounts with an active Amazon DSP advertiser linked; false returns only those without. Omit for all accounts. Use has_dsp=true to answer 'which of my accounts have DSP?' in one call, then pass those ids to get_dsp_performance."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 200, "description": "Accounts per page. Defaults to 50. Max 200."}}}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "The authenticated user's profile, a summary of accessible workspaces, and a filtered, paginated flat list of accessible Amazon accounts (each flagged with hasDsp).", "properties": {"user": {"type": "object", "description": "Small user header.", "properties": {"id": {"type": "string", "description": "User id."}, "name": {"type": "string", "description": "User display name; empty string when unset."}, "email": {"type": "string", "description": "User email; empty string when unset."}, "role": {"type": ["string", "null"], "description": "User persona, or null."}}, "required": ["id", "name", "email", "role"]}, "workspaces": {"type": "array", "description": "All accessible workspaces (optionally narrowed by workspace_id), sorted by name; accountCount ignores account_name_search.", "items": {"type": "object", "description": "Workspace summary.", "properties": {"id": {"type": "string", "description": "Workspace id."}, "name": {"type": "string", "description": "Workspace name; empty string when unset."}, "accountCount": {"type": "integer", "description": "Accessible Amazon accounts in the workspace (before name filter)."}}, "required": ["id", "name", "accountCount"]}}, "accounts": {"type": "array", "description": "This page of accessible accounts after account_name_search / workspace_id / has_dsp filters, sorted by name.", "items": {"type": "object", "description": "Flat account view.", "properties": {"id": {"type": "string", "description": "Amazon account id (amazon_account_id for other tools)."}, "name": {"type": "string", "description": "Account name; empty string when unset."}, "workspace_id": {"type": "string", "description": "Owning workspace id."}, "workspace_name": {"type": "string", "description": "Owning workspace name."}, "country": {"type": "string", "description": "Country code; empty string when unset."}, "currency": {"type": "string", "description": "Currency code; empty string when unset."}, "timezone": {"type": "string", "description": "Account timezone; empty string when unset."}, "marketplace": {"type": "string", "description": "Marketplace string id; empty string when unset."}, "advertiser_id": {"type": "string", "description": "Amazon Ads advertiser id; empty string when unset."}, "status": {"type": ["string", "null"], "description": "Account status as stored, or null."}, "accountType": {"type": ["string", "null"], "description": "seller, vendor or agency, or null."}, "hasDsp": {"type": ["boolean", "null"], "description": "Whether an active DSP advertiser is linked; null when the lookup failed and has_dsp was not requested."}}, "required": ["id", "name", "workspace_id", "workspace_name", "country", "currency", "timezone", "marketplace", "advertiser_id", "status", "accountType", "hasDsp"]}}, "pagination": {"type": "object", "description": "Page metadata over the filtered account list.", "properties": {"total": {"type": "integer", "description": "Total accounts after filters."}, "page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-200)."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}}, "required": ["total", "page", "pageSize", "totalPages", "hasMore"]}}, "required": ["user", "workspaces", "accounts", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/resolve_account": {"post": {"operationId": "resolve_account", "tags": ["Discovery"], "summary": "Resolve Account", "description": "Tool name: `resolve_account` \u00b7 **Scope:** requires `tools:read`.\n\nResolve an Amazon account by name to its `workspace_id` and `amazon_account_id`, so account-scoped tools can be called without listing everything via `get_user_context`.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "Account name (or part of it) to resolve, e.g. 'Rolex'."}}, "required": ["query"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "The name that was searched."}, "matchCount": {"type": "integer", "description": "Number of matching accounts."}, "matches": {"type": "array", "description": "Matching accounts with the ids needed for account-scoped tools.", "items": {"type": "object", "properties": {"workspace_id": {"type": "string"}, "workspace_name": {"type": "string"}, "amazon_account_id": {"type": "string"}, "name": {"type": "string"}, "marketplace": {"type": "string"}, "country": {"type": "string"}, "accountType": {"type": ["string", "null"]}}, "required": ["workspace_id", "amazon_account_id", "name"], "additionalProperties": true}}}, "required": ["query", "matchCount", "matches"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/add_products_to_ad_group": {"post": {"operationId": "add_products_to_ad_group", "tags": ["Campaigns"], "summary": "Add Products to Ad Group", "description": "Tool name: `add_products_to_ad_group` \u00b7 **Scope:** requires `tools:write`.\n\nAdd up to 50 products (ASIN product ads) to existing ad groups. Each item needs `campaign_id`, `ad_group_id` and `asin`; seller accounts also need `sku`, vendor accounts advertise by ASIN alone. `state` defaults to ENABLED. Resolve ASIN / SKU pairs with `list_product_catalog`.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "products": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Products to add to existing ad groups.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (from list_campaigns)."}, "ad_group_id": {"type": "string", "description": "Amazon ad group ID the product is added to (from list_ad_groups)."}, "asin": {"type": "string", "description": "Product ASIN. Required. Resolve via list_product_catalog."}, "sku": {"type": "string", "description": "Seller SKU. Required for seller accounts; omit for vendor accounts."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Defaults to ENABLED."}}, "required": ["campaign_id", "ad_group_id", "asin"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "products"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Per-product outcome of adding ASIN product ads to existing ad groups; `status` is success, partial_success, failed or policy_violation.", "properties": {"status": {"type": "string", "description": "success, partial_success, failed or policy_violation."}, "applied": {"type": "boolean", "description": "True when at least one product was added at Amazon."}, "message": {"type": "string", "description": "Natural-language summary of the outcome."}, "summary": {"type": "object", "description": "Counts over results; present only after the backend was called.", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "added": {"type": "integer", "description": "Rows with status added."}, "failed": {"type": "integer", "description": "Rows with status failed."}}, "required": ["total", "added", "failed"]}, "results": {"type": "array", "description": "One row per input product (validation failures first, then backend outcomes).", "items": {"type": "object", "properties": {"index": {"type": "integer", "description": "Position of the product in the request."}, "asin": {"type": ["string", "null"], "description": "Product ASIN (null when missing in the request)."}, "ad_group_id": {"type": "string", "description": "Amazon ad group id; present on backend outcome rows."}, "status": {"type": "string", "description": "added or failed."}, "error": {"type": "string", "description": "Failure reason; present on failed rows."}}, "required": ["index", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid) when at least one product was added; null otherwise. Absent on pre-flight/policy failures."}, "policy_checks": {"type": "array", "description": "Ad-group size policy violations; present only on policy_violation.", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category (adGroupCreate)."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message."}, "adGroupId": {"type": ["string", "null"], "description": "Ad group the check applies to."}}, "required": ["policyId", "scope", "category", "rule", "result", "message", "adGroupId"]}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "results", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_ad_group": {"post": {"operationId": "create_ad_group", "tags": ["Campaigns"], "summary": "Create Ad Group", "description": "Tool name: `create_ad_group` \u00b7 **Scope:** requires `tools:write`.\n\nCreate one or more ad groups inside an existing Sponsored Products campaign, each with a `name`, `default_bid` and at least one product; `keywords` / `product_targets` are accepted on MANUAL campaigns only. Names must be unique within the campaign. All-or-nothing: an invalid ad group, or a bid blocked by the workspace bid policy (`maxBid` / `minBid`), returns `422` and nothing is submitted to Amazon.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "campaign_id": {"type": "string", "description": "Amazon campaign ID of the EXISTING campaign to add to (from list_campaigns). Must be Sponsored Products and not archived."}, "ad_groups": {"type": "array", "minItems": 1, "maxItems": 10, "description": "Ad groups to create. Each needs a name, a default_bid and at least one product; keywords / product_targets are MANUAL-only.", "items": {"type": "object", "description": "Legacy single ad group (one ad group only). Prefer `ad_groups` (array) for one or more ad groups. Sponsored Products campaigns must have at least one ad group with at least one product.", "properties": {"name": {"type": "string"}, "default_bid": {"type": "number", "exclusiveMinimum": 0, "description": "Default bid for this ad group."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Ad group state. Defaults to ENABLED."}, "products": {"type": "array", "minItems": 1, "description": "Products to advertise. Every entry requires an asin. On SELLER accounts a sku is also required (the seller offer is identified by SKU); on VENDOR accounts sku is not needed (vendors advertise by ASIN). If a required field is missing, call list_product_catalog (Mode 1) or get_inventory to resolve before calling this tool.", "items": {"type": "object", "properties": {"asin": {"type": "string", "description": "Product ASIN. Always required. Resolve via list_product_catalog \u2014 do not invent."}, "sku": {"type": "string", "description": "Seller SKU paired with the ASIN. REQUIRED for seller accounts; omit for vendor accounts (they have no seller SKU). Resolve via list_product_catalog or get_inventory."}, "custom_text": {"type": "string"}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"]}}, "required": ["asin"]}}, "keywords": {"type": "array", "description": "MANUAL campaigns only. Each keyword targets a search term with a match type.", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["BROAD", "EXACT", "PHRASE"]}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "bid", "state"]}}, "product_targets": {"type": "array", "description": "MANUAL campaigns only. Product / category targets expressed as Amazon expressions.", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string"}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "bid", "state"]}}, "negative_keywords": {"type": "array", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["NEGATIVE_BROAD", "NEGATIVE_EXACT", "NEGATIVE_PHRASE"]}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "state"]}}, "negative_product_targets": {"type": "array", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["ASIN_BRAND_SAME_AS", "ASIN_SAME_AS"]}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "state"]}}}, "required": ["name", "default_bid", "products"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why the user wants these ad groups. Stored for audit and shown to admins in the activity log."}}, "required": ["amazon_account_id", "campaign_id", "ad_groups"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of creating ad groups in an existing Sponsored Products campaign; `status` is success, partial_success, failed or policy_violation (refusals before Amazon is called also use failed).", "properties": {"status": {"type": "string", "description": "success, partial_success, failed or policy_violation."}, "applied": {"type": "boolean", "description": "True when at least one ad group was created."}, "message": {"type": "string", "description": "Natural-language summary of the outcome."}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid) when at least one ad group was created; null otherwise."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}, "campaign_id": {"type": "string", "description": "Amazon campaign id the ad groups were added to; present once the pipeline ran."}, "results": {"type": "array", "description": "Created ad groups followed by Amazon errors; on validation refusal, one row per failed input ad group.", "items": {"type": "object", "properties": {"ad_group_id": {"type": "string", "description": "New Amazon ad group id (created rows)."}, "name": {"type": ["string", "null"], "description": "Ad group name (created rows and validation failures)."}, "index": {"type": "integer", "description": "Position in the request (validation-failure rows only)."}, "status": {"type": "string", "description": "created or failed."}, "error": {"type": "string", "description": "Failure reason (failed rows)."}}, "required": ["status"]}}, "policy_checks": {"type": "array", "description": "Bid and structure policy checks per ad group (violations only on policy_violation; all checks on success paths).", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category (bidChange or adGroupCreate)."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "passed or violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message."}, "adGroupName": {"type": ["string", "null"], "description": "Ad group the check applies to."}}, "required": ["policyId", "scope", "category", "rule", "result", "message", "adGroupName"]}}}, "required": ["status", "applied", "message", "rollback_token", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_campaign": {"post": {"operationId": "create_campaign", "tags": ["Campaigns"], "summary": "Create Campaign", "description": "Tool name: `create_campaign` \u00b7 **Scope:** requires `tools:write`.\n\nCreate one Sponsored Products campaign (one ad group, one or more products). Asynchronous: returns a `session_id` \u2014 poll `get_campaign_creation_status`. Subject to workspace campaign-creation policies (budget caps, targeting-type restrictions); a policy-blocked create returns `422` and is not submitted.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "name": {"type": "string", "description": "Campaign name. Must be unique within the account."}, "sponsored_type": {"type": "string", "enum": ["Product"], "description": "Amazon ad type. Only 'Product' (Sponsored Products) is supported today."}, "targeting_type": {"type": "string", "enum": ["AUTO", "MANUAL"], "description": "AUTO lets Amazon pick targets automatically (no keywords or product_targets allowed). MANUAL requires at least one keyword or product target."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Campaign state. Defaults to ENABLED."}, "daily_budget": {"type": "number", "exclusiveMinimum": 0, "description": "Daily budget (absolute number, in the account's currency). Subject to workspace `maxStartingBudget`."}, "start_date": {"type": "string", "description": "Optional campaign start date in YYYY-MM-DD format. Omit to start immediately. Must not be in the past."}, "end_date": {"type": "string", "description": "Optional campaign end date in YYYY-MM-DD format. Omit to run with no end date. Must not be before start_date."}, "ad_group": {"type": "object", "description": "Legacy single ad group (one ad group only). Prefer `ad_groups` (array) for one or more ad groups. Sponsored Products campaigns must have at least one ad group with at least one product.", "properties": {"name": {"type": "string"}, "default_bid": {"type": "number", "exclusiveMinimum": 0, "description": "Default bid for this ad group."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Ad group state. Defaults to ENABLED."}, "products": {"type": "array", "minItems": 1, "description": "Products to advertise. Every entry requires an asin. On SELLER accounts a sku is also required (the seller offer is identified by SKU); on VENDOR accounts sku is not needed (vendors advertise by ASIN). If a required field is missing, call list_product_catalog (Mode 1) or get_inventory to resolve before calling this tool.", "items": {"type": "object", "properties": {"asin": {"type": "string", "description": "Product ASIN. Always required. Resolve via list_product_catalog \u2014 do not invent."}, "sku": {"type": "string", "description": "Seller SKU paired with the ASIN. REQUIRED for seller accounts; omit for vendor accounts (they have no seller SKU). Resolve via list_product_catalog or get_inventory."}, "custom_text": {"type": "string"}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"]}}, "required": ["asin"]}}, "keywords": {"type": "array", "description": "MANUAL campaigns only. Each keyword targets a search term with a match type.", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["BROAD", "EXACT", "PHRASE"]}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "bid", "state"]}}, "product_targets": {"type": "array", "description": "MANUAL campaigns only. Product / category targets expressed as Amazon expressions.", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string"}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "bid", "state"]}}, "negative_keywords": {"type": "array", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["NEGATIVE_BROAD", "NEGATIVE_EXACT", "NEGATIVE_PHRASE"]}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "state"]}}, "negative_product_targets": {"type": "array", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["ASIN_BRAND_SAME_AS", "ASIN_SAME_AS"]}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "state"]}}}, "required": ["name", "default_bid", "products"]}, "dynamic_bidding": {"type": "object", "description": "Optional Sponsored Products bidding strategy + placement bid adjustments. Shape: {strategy, placementBidding: [{placement, percentage}]}. Provide `strategy` and/or `placementBidding`. Omit the whole object to use Amazon's defaults (LEGACY_FOR_SALES, no placement adjustments).", "properties": {"strategy": {"type": "string", "enum": ["LEGACY_FOR_SALES", "AUTO_FOR_SALES", "MANUAL", "RULE_BASED"], "description": "Bidding strategy. LEGACY_FOR_SALES = dynamic bids (down only); AUTO_FOR_SALES = dynamic bids (up and down); MANUAL = fixed bids; RULE_BASED = rule-based bidding."}, "placementBidding": {"type": "array", "description": "Per-placement bid adjustments. Each entry raises the bid for that placement by `percentage`%.", "items": {"type": "object", "properties": {"placement": {"type": "string", "enum": ["PLACEMENT_TOP", "PLACEMENT_PRODUCT_PAGE", "PLACEMENT_REST_OF_SEARCH", "SITE_AMAZON_BUSINESS"], "description": "Placement to adjust: PLACEMENT_TOP (top of search), PLACEMENT_PRODUCT_PAGE (product pages), PLACEMENT_REST_OF_SEARCH (rest of search), SITE_AMAZON_BUSINESS (Amazon Business)."}, "percentage": {"type": "number", "minimum": 0, "maximum": 900, "description": "Bid adjustment percent (0\u2013900)."}}, "required": ["placement", "percentage"]}}}}, "_reasoning": {"type": "string", "description": "Briefly explain why the user wants this campaign created. Stored for audit and shown to admins in the activity log."}, "confirm": {"type": "boolean", "description": "Must be true to queue campaign creation. Omit or set false on the first call to receive a preview (or an incomplete response if required fields are missing). Re-call with confirm=true only after the user explicitly approves the preview, and send the `confirmation_token` from that preview with it."}, "confirmation_token": {"type": "string", "description": "The `confirmation_token` returned by the preview call. Required with confirm=true. It is tied to the exact arguments that were previewed, so changing any argument after the preview invalidates it and a new preview is required."}, "ad_groups": {"type": "array", "minItems": 1, "description": "One or more ad groups. Preferred over the legacy single `ad_group`. Each ad group has its own name, default_bid, products, and (for MANUAL campaigns) keywords/product_targets. Each ad group requires at least one product. Every product needs an ASIN; SKU is required only for seller accounts (vendor accounts advertise by ASIN alone).", "items": {"type": "object", "description": "Legacy single ad group (one ad group only). Prefer `ad_groups` (array) for one or more ad groups. Sponsored Products campaigns must have at least one ad group with at least one product.", "properties": {"name": {"type": "string"}, "default_bid": {"type": "number", "exclusiveMinimum": 0, "description": "Default bid for this ad group."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Ad group state. Defaults to ENABLED."}, "products": {"type": "array", "minItems": 1, "description": "Products to advertise. Every entry requires an asin. On SELLER accounts a sku is also required (the seller offer is identified by SKU); on VENDOR accounts sku is not needed (vendors advertise by ASIN). If a required field is missing, call list_product_catalog (Mode 1) or get_inventory to resolve before calling this tool.", "items": {"type": "object", "properties": {"asin": {"type": "string", "description": "Product ASIN. Always required. Resolve via list_product_catalog \u2014 do not invent."}, "sku": {"type": "string", "description": "Seller SKU paired with the ASIN. REQUIRED for seller accounts; omit for vendor accounts (they have no seller SKU). Resolve via list_product_catalog or get_inventory."}, "custom_text": {"type": "string"}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"]}}, "required": ["asin"]}}, "keywords": {"type": "array", "description": "MANUAL campaigns only. Each keyword targets a search term with a match type.", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["BROAD", "EXACT", "PHRASE"]}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "bid", "state"]}}, "product_targets": {"type": "array", "description": "MANUAL campaigns only. Product / category targets expressed as Amazon expressions.", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string"}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "bid": {"type": "number", "exclusiveMinimum": 0}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "bid", "state"]}}, "negative_keywords": {"type": "array", "items": {"type": "object", "properties": {"keyword_text": {"type": "string"}, "match_type": {"type": "string", "enum": ["NEGATIVE_BROAD", "NEGATIVE_EXACT", "NEGATIVE_PHRASE"]}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["keyword_text", "match_type", "state"]}}, "negative_product_targets": {"type": "array", "items": {"type": "object", "properties": {"expression": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["ASIN_BRAND_SAME_AS", "ASIN_SAME_AS"]}, "value": {"type": "string"}}, "required": ["type", "value"]}}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "PROPOSED"]}}, "required": ["expression", "state"]}}}, "required": ["name", "default_bid", "products"]}}}, "required": ["amazon_account_id", "name", "sponsored_type", "targeting_type", "daily_budget"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of a create_campaign call; `status` selects the branch (incomplete, confirmation_required, policy_violation, pending_approval, failed, processing). The campaign is only queued when status is processing.", "properties": {"status": {"type": "string", "description": "One of incomplete, confirmation_required, policy_violation, pending_approval, failed, processing."}, "applied": {"type": "boolean", "description": "Always false: creation is asynchronous and Amazon has not been called yet."}, "message": {"type": "string", "description": "Natural-language explanation of the outcome and next step."}, "session_id": {"type": ["string", "null"], "description": "Campaign creation session id to poll with get_campaign_creation_status; only set when status is processing."}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid); set on processing and pending_approval."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}, "confirmation_token": {"type": "string", "description": "HMAC fingerprint of the previewed payload; present on confirmation_required, must be echoed with confirm=true."}, "preview": {"type": "object", "description": "Normalized campaign payload for user confirmation; present on incomplete, confirmation_required and policy_violation.", "properties": {"name": {"type": ["string", "null"], "description": "Campaign name (policy prefix applied if required)."}, "sponsored_type": {"type": ["string", "null"], "description": "Ad type; only Product is supported."}, "targeting_type": {"type": ["string", "null"], "description": "AUTO or MANUAL."}, "state": {"type": "string", "description": "ENABLED or PAUSED (default ENABLED)."}, "daily_budget": {"type": ["number", "null"], "description": "Daily budget in account currency."}, "ad_groups": {"type": "array", "description": "All ad groups in the request, normalized.", "items": {"type": "object", "properties": {"name": {"type": ["string", "null"], "description": "Ad group name."}, "default_bid": {"type": ["number", "null"], "description": "Ad group default bid."}, "state": {"type": "string", "description": "ENABLED or PAUSED (default ENABLED)."}, "products": {"type": "array", "description": "Products to advertise.", "items": {"type": "object", "properties": {"asin": {"type": ["string", "null"], "description": "Product ASIN."}, "sku": {"type": ["string", "null"], "description": "Seller SKU (null for vendor accounts)."}, "state": {"type": "string", "description": "ENABLED or PAUSED."}, "custom_text": {"type": "string", "description": "Optional custom text, only when supplied."}}, "required": ["asin", "sku", "state"]}}, "keywords": {"type": "array", "description": "Keyword targets as supplied (keyword_text, match_type, bid, state).", "items": {"type": "object", "description": "Keyword input object echoed back."}}, "product_targets": {"type": "array", "description": "Product targets as supplied (expression, bid, state).", "items": {"type": "object", "description": "Product target input object echoed back."}}, "negative_keywords": {"type": "array", "description": "Negative keywords as supplied.", "items": {"type": "object", "description": "Negative keyword input object echoed back."}}, "negative_product_targets": {"type": "array", "description": "Negative product targets as supplied.", "items": {"type": "object", "description": "Negative product target input object echoed back."}}}, "required": ["name", "default_bid", "state", "products", "keywords", "product_targets", "negative_keywords", "negative_product_targets"]}}, "ad_group": {"type": "object", "description": "First ad group (backward-compatible single view); same shape as ad_groups items."}, "start_date": {"type": "string", "description": "Campaign start date YYYY-MM-DD; only when supplied."}, "end_date": {"type": "string", "description": "Campaign end date YYYY-MM-DD; only when supplied."}, "dynamic_bidding": {"type": "object", "description": "SP bidding settings as supplied: {strategy, placementBidding:[{placement, percentage}]}.", "properties": {"strategy": {"type": "string", "description": "LEGACY_FOR_SALES, AUTO_FOR_SALES, MANUAL or RULE_BASED."}, "placementBidding": {"type": "array", "description": "Per-placement bid adjustments.", "items": {"type": "object", "properties": {"placement": {"type": "string", "description": "Amazon SP placement predicate."}, "percentage": {"type": "number", "description": "Adjustment percent 0-900."}}}}}}}, "required": ["name", "sponsored_type", "targeting_type", "state", "daily_budget", "ad_groups"]}, "missing_fields": {"type": "array", "description": "Required product fields that are missing; present only when status is incomplete.", "items": {"type": "object", "properties": {"field": {"type": "string", "description": "Path of the missing field, e.g. ad_groups[0].products[1].sku."}, "issue": {"type": "string", "description": "Human-readable description of the problem."}, "resolve_with": {"type": "array", "description": "Tool names that can resolve the value.", "items": {"type": "string"}}}, "required": ["field", "issue", "resolve_with"]}}, "policy_checks": {"type": "array", "description": "Policy evaluation results (violations only on policy_violation; all checks otherwise). Absent on incomplete.", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null for baseline."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category (e.g. campaignCreate)."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "passed or violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message naming the checked value."}}, "required": ["policyId", "scope", "category", "rule", "result", "message"]}}, "after": {"type": "object", "description": "Snapshot of the campaign to be created, used for the decision log; absent on incomplete.", "properties": {"name": {"type": ["string", "null"], "description": "Campaign name."}, "sponsoredType": {"type": ["string", "null"], "description": "Ad type."}, "targetingType": {"type": ["string", "null"], "description": "AUTO or MANUAL."}, "state": {"type": "string", "description": "Campaign state."}, "dailyBudget": {"type": ["number", "null"], "description": "Daily budget."}, "startDate": {"type": ["string", "null"], "description": "Start date YYYY-MM-DD or null."}, "endDate": {"type": ["string", "null"], "description": "End date YYYY-MM-DD or null."}, "adGroupCount": {"type": "integer", "description": "Number of ad groups."}, "adGroupName": {"type": ["string", "null"], "description": "First ad group's name (compat)."}, "defaultBid": {"type": ["number", "null"], "description": "First ad group's default bid (compat)."}, "productCount": {"type": "integer", "description": "Products across all ad groups."}, "keywordCount": {"type": "integer", "description": "Keywords across all ad groups."}, "productTargetCount": {"type": "integer", "description": "Product targets across all ad groups."}, "adGroups": {"type": "array", "description": "Per-ad-group counts.", "items": {"type": "object", "properties": {"name": {"type": ["string", "null"], "description": "Ad group name."}, "defaultBid": {"type": ["number", "null"], "description": "Default bid."}, "productCount": {"type": "integer", "description": "Products in this ad group."}, "keywordCount": {"type": "integer", "description": "Keywords in this ad group."}, "productTargetCount": {"type": "integer", "description": "Product targets in this ad group."}}, "required": ["name", "defaultBid", "productCount", "keywordCount", "productTargetCount"]}}}, "required": ["name", "sponsoredType", "targetingType", "state", "dailyBudget", "startDate", "endDate", "adGroupCount", "adGroupName", "defaultBid", "productCount", "keywordCount", "productTargetCount", "adGroups"]}, "policyAdminUrl": {"type": "string", "description": "Link to the MCP Admin policies page; present on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles allowed to edit policies; present on policy_violation.", "items": {"type": "string"}}, "errors": {"type": "array", "description": "Raw bulk-manager errors when nothing was queued (status failed).", "items": {"type": "object", "properties": {"index": {"type": "integer", "description": "Entity index (always 0)."}, "error": {"type": "object", "description": "Error detail.", "properties": {"message": {"type": "array", "description": "Error message strings.", "items": {"type": "string"}}}}}}}, "queue_warnings": {"type": "array", "description": "Soft errors reported while queuing even though a session exists (status processing).", "items": {"type": "object", "description": "Bulk-manager error object {index, error:{message:[...]}}."}}}, "required": ["status", "applied", "message", "session_id", "rollback_token", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_campaign_creation_status": {"post": {"operationId": "get_campaign_creation_status", "tags": ["Campaigns"], "summary": "Get Campaign Creation Status", "description": "Tool name: `get_campaign_creation_status` \u00b7 **Scope:** requires `tools:read`.\n\nPoll an asynchronous `create_campaign` job by `session_id`. Returns per-step status and the new `campaignId` once Amazon assigns it.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "session_id": {"type": "string", "description": "Session id returned by create_campaign. The session must belong to the same workspace + amazon_account."}}, "required": ["amazon_account_id", "session_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Normalized snapshot of an asynchronous campaign-creation session, with per-step outcomes.", "properties": {"session_id": {"type": "string", "description": "Campaign creation session id."}, "status": {"type": ["string", "null"], "description": "Overall session status (e.g. pending, in_progress, completed, failed)."}, "sponsored_type": {"type": ["string", "null"], "description": "Ad type of the campaign being created."}, "steps": {"type": "object", "description": "Per-step outcome keyed by step name (campaign_creation, ad_group_creation, keyword_creation, target_creation, ad_product_creation, negative_keyword_creation, negative_target_creation, tag_assignment).", "additionalProperties": {"type": "object", "description": "One creation step.", "properties": {"status": {"type": ["string", "null"], "description": "Step status (pending, in_progress, completed, failed)."}, "success_count": {"type": "integer", "description": "Entities the step created successfully."}, "error_count": {"type": "integer", "description": "Entities the step failed on."}, "errors": {"type": "array", "description": "Amazon/worker error entries for the step.", "items": {"description": "Error entry as written by the creation worker (see tool description)."}}, "campaign_ids": {"type": "array", "description": "New Amazon campaign ids (campaign_creation step only).", "items": {"type": "string"}}, "ad_group_ids": {"type": "array", "description": "New Amazon ad group ids (ad_group_creation step only).", "items": {"type": "string"}}, "keyword_ids": {"type": "array", "description": "New keyword ids (keyword_creation step only).", "items": {"type": "string"}}, "target_ids": {"type": "array", "description": "New product target ids (target_creation step only).", "items": {"type": "string"}}, "ad_product_ids": {"type": "array", "description": "New product ad ids (ad_product_creation step only).", "items": {"type": "string"}}, "negative_keyword_ids": {"type": "array", "description": "New negative keyword ids (negative_keyword_creation step only).", "items": {"type": "string"}}, "negative_target_ids": {"type": "array", "description": "New negative target ids (negative_target_creation step only).", "items": {"type": "string"}}}, "required": ["status", "success_count", "error_count", "errors"]}}, "results": {"type": "object", "description": "Session-level success and error lists written by the creation worker.", "properties": {"success": {"type": "array", "description": "Successful outcomes (see tool description).", "items": {"description": "Success entry as written by the creation worker."}}, "errors": {"type": "array", "description": "Error outcomes (see tool description).", "items": {"description": "Error entry as written by the creation worker."}}}, "required": ["success", "errors"]}, "retry_count": {"type": "integer", "description": "Number of worker attempts so far."}, "created_at": {"type": ["string", "null"], "description": "Session creation time, ISO 8601."}, "updated_at": {"type": ["string", "null"], "description": "Last session update time, ISO 8601."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}}, "required": ["session_id", "status", "sponsored_type", "steps", "results", "retry_count", "created_at", "updated_at", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_campaign_performance": {"post": {"operationId": "get_campaign_performance", "tags": ["Campaigns"], "summary": "Get Campaign Performance", "description": "Tool name: `get_campaign_performance` \u00b7 **Scope:** requires `tools:read`.\n\nAds metrics per campaign over a date range \u2014 spend, sales, ACOS, ROAS, CTR, CPC, orders, CVR \u2014 plus a full-set summary. Defaults to ENABLED campaigns; pass `campaign_ids` or `status` to include paused/archived. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional campaign IDs. When set, metrics are returned for these IDs regardless of campaign state."}, "campaign_name": {"type": "string", "description": "Filter by campaign name (partial match). Metrics are returned for matching campaigns regardless of state."}, "status": {"type": "array", "items": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"]}, "description": "Campaign states to include. Defaults to ENABLED only. Set explicitly when the user asks for paused or archived campaigns."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Optional ad-type filter. Pass [\"Product\"] for Sponsored Products (SP), [\"Brand\"] for Sponsored Brands (SB), [\"Display\"] for Sponsored Display (SD). Required whenever the user asks about SP-only, SB-only or SD-only numbers \u2014 without it the rows AND the summary totals mix all ad types together."}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["campaignName", "campaignId", "sponsoredType", "timeWindowStart", "week", "month", "year"]}, "description": "Dimensions to group rows by. Defaults to ['campaignName', 'campaignId'] \u2014 one row per campaign for the whole date range. Add exactly ONE time dimension for a trend: 'timeWindowStart' (daily), 'week', 'month' or 'year'. The bucket is returned on each row under that same key, and the date range still bounds the query \u2014 group_by only decides how rows are split inside it. Drop campaignName/campaignId for an account-level total per bucket (e.g. group_by=['month'] for monthly account spend). Add 'sponsoredType' for an SP/SB/SD split. Ignored when group_by_tag is true. The summary always covers the FULL result set across every bucket, so do not present it as one period's number."}, "tag_values": {"type": "array", "items": {"type": "string"}, "description": "Optional legacy tag labels. Only ENABLED campaigns with an active tag assignment are included unless status or campaign_name is specified."}, "group_by_tag": {"type": "boolean", "description": "When true, results are one row per tag (rollup metrics by tag). Each row includes `tagValue` instead of per-campaign breakdown."}, "sort_field": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"], "description": "Field to sort results by. Defaults to 'cost'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of campaign (or tag/time-bucket) performance rows plus a summary over the FULL result set.", "properties": {"data": {"type": "array", "description": "Performance rows for this page; one row per group_by bucket (default: per campaign).", "items": {"type": "object", "properties": {"spend": {"type": "number", "description": "Ad spend (cost), rounded to 2 decimals."}, "sales": {"type": "number", "description": "Attributed sales (14-day), rounded to 2 decimals."}, "impressions": {"type": "integer", "description": "Impressions."}, "clicks": {"type": "integer", "description": "Clicks."}, "orders": {"type": "integer", "description": "Attributed orders (purchases)."}, "acos": {"type": ["number", "null"], "description": "ACOS percent; null when undefined (divide-by-zero sentinel)."}, "roas": {"type": ["number", "null"], "description": "ROAS; null when undefined."}, "ctr": {"type": ["number", "null"], "description": "Click-through rate percent; null when undefined."}, "cpc": {"type": ["number", "null"], "description": "Cost per click; null when undefined."}, "cvr": {"type": ["number", "null"], "description": "Conversion rate percent; null when undefined."}, "campaignName": {"type": "string", "description": "Campaign name; present when campaignName is a group_by dimension."}, "campaignId": {"type": "string", "description": "Amazon campaign id; present when campaignId is a group_by dimension."}, "sponsoredType": {"type": "string", "description": "Ad type bucket (Product/Brand/Display); present when grouped by sponsoredType."}, "timeWindowStart": {"type": "string", "description": "Daily bucket start (datetime string); present when grouped by timeWindowStart."}, "week": {"type": "string", "description": "Week bucket start (datetime string); present when grouped by week."}, "month": {"type": "string", "description": "Month bucket start (datetime string); present when grouped by month."}, "year": {"type": "integer", "description": "Year bucket; present when grouped by year."}, "tagValue": {"type": "string", "description": "Tag label; present when group_by_tag is true (one row per tag)."}, "tags": {"type": "array", "description": "Tag assignments attached to the row when the facade returns them.", "items": {"type": "object", "description": "Legacy tag assignment (see tool description)."}}}, "required": ["spend", "sales", "impressions", "clicks", "orders", "acos", "roas", "ctr", "cpc", "cvr"]}}, "summary": {"type": "object", "description": "Totals over the FULL result set (not just this page).", "properties": {"totalSpend": {"type": "number", "description": "Sum of spend, 2 decimals."}, "totalSales": {"type": "number", "description": "Sum of attributed sales, 2 decimals."}, "totalImpressions": {"type": "integer", "description": "Sum of impressions."}, "totalClicks": {"type": "integer", "description": "Sum of clicks."}, "totalOrders": {"type": "integer", "description": "Sum of orders."}, "overallAcos": {"type": "number", "description": "totalSpend / totalSales * 100; 0 when no sales."}, "overallRoas": {"type": "number", "description": "totalSales / totalSpend; 0 when no spend."}}, "required": ["totalSpend", "totalSales", "totalImpressions", "totalClicks", "totalOrders", "overallAcos", "overallRoas"]}, "dateRange": {"type": "object", "description": "The requested date range, echoed back.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL row count.", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the full result set."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total (full row count)."}, "account": {"type": "object", "description": "The Amazon account queried.", "properties": {"id": {"type": "string", "description": "Amazon account id (Mongo id)."}, "name": {"type": "string", "description": "Account display name."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}}, "required": ["data", "summary", "dateRange", "pagination", "total", "account", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_marketplace_summary": {"post": {"operationId": "get_marketplace_summary", "tags": ["Campaigns"], "summary": "Get Marketplace Summary", "description": "Tool name: `get_marketplace_summary` \u00b7 **Scope:** requires `tools:read`.\n\nAggregated ads metrics per account across the workspace. Takes `amazon_account_ids` (list) \u2014 defaults to all accounts the key can reach.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "amazon_account_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional list of account IDs. Defaults to all accounts in workspace."}}, "required": ["start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Aggregated ads performance per Amazon account in the workspace, plus workspace totals for the date range.", "properties": {"accounts": {"type": "array", "description": "One entry per queried account; empty when no account matched the workspace.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Amazon account id (Mongo id)."}, "name": {"type": "string", "description": "Account display name."}, "country": {"type": "string", "description": "Account countryCode."}, "currency": {"type": "string", "description": "Account currencyCode."}, "timezone": {"type": "string", "description": "Account timezone."}, "metrics": {"type": "object", "description": "Account-level metrics for the range; all zeros when the per-account query failed.", "properties": {"spend": {"type": "number", "description": "Ad spend (cost), 2 decimals."}, "sales": {"type": "number", "description": "Attributed sales (14-day), 2 decimals."}, "acos": {"type": "number", "description": "ACOS percent, 2 decimals."}, "roas": {"type": "number", "description": "ROAS, 2 decimals."}, "impressions": {"type": "integer", "description": "Impressions."}, "clicks": {"type": "integer", "description": "Clicks."}, "ctr": {"type": "number", "description": "Click-through rate percent, 2 decimals."}, "cpc": {"type": "number", "description": "Cost per click, 2 decimals."}, "orders": {"type": "integer", "description": "Attributed orders (purchases)."}}, "required": ["spend", "sales", "acos", "roas", "impressions", "clicks", "ctr", "cpc", "orders"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this account."}}, "required": ["id", "name", "country", "currency", "timezone", "metrics", "chatAssistantUrl"]}}, "totals": {"type": "object", "description": "Sums across all accounts; an EMPTY object when no accounts were queried.", "properties": {"spend": {"type": "number", "description": "Sum of account spend."}, "sales": {"type": "number", "description": "Sum of account sales."}, "impressions": {"type": "integer", "description": "Sum of impressions."}, "clicks": {"type": "integer", "description": "Sum of clicks."}, "orders": {"type": "integer", "description": "Sum of orders."}, "acos": {"type": "number", "description": "spend / sales * 100, 2 decimals; 0 when no sales."}, "roas": {"type": "number", "description": "sales / spend, 2 decimals; 0 when no spend."}}}, "dateRange": {"type": "object", "description": "The requested date range, echoed back.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}}, "required": ["accounts", "totals", "dateRange"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_placement_performance": {"post": {"operationId": "get_placement_performance", "tags": ["Campaigns"], "summary": "Get Placement Performance", "description": "Tool name: `get_placement_performance` \u00b7 **Scope:** requires `tools:read`.\n\nMetrics per placement (Top of Search / Product Page / Rest of Search; SB also Home) per campaign, plus bid-adjustment % and bidding strategy. Set `sponsored_type` for SP-only or SB-only numbers. Paginated; supports a `metrics` selector.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format."}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format."}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["campaignId", "placementClassification", "sponsoredType", "timeWindowStart", "week", "month", "year"]}, "description": "Dimensions to group results by. Defaults to ['campaignId', 'placementClassification', 'sponsoredType'] \u2014 one row per campaign x placement x ad type, with metadata (campaign name, bidding strategy, bid adjustments) joined in. Drop campaignId for an account-level summary. Use time fields (week/month) for trend analysis. NEVER include campaignName \u2014 campaign names come from metadata enrichment, not grouping."}, "metrics": {"type": "array", "items": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"]}, "description": "Metrics to fetch. Defaults to the full set. Raw additive metrics are always included internally so that derived metrics stay correct after the SB Home/Homepage alias merge."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific campaigns by ID."}, "campaign_names": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific campaigns by name (case-insensitive PARTIAL match, same as get_campaign_performance's campaign_name). Names are resolved to campaign IDs via a CampaignData lookup before the fetch \u2014 faster than name-based matching and avoids ambiguity when two campaigns share a name."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Optional ad-type filter. Pass [\"Product\"] for Sponsored Products (SP), [\"Brand\"] for Sponsored Brands (SB), [\"Display\"] for Sponsored Display (SD). Required whenever the user is asking about SP-only or SB-only metrics \u2014 without it the response (and summary totals) mixes all ad types."}, "placement_classification": {"type": "array", "items": {"type": "string", "enum": ["Top of Search", "Product Page", "Home", "Rest of Search"]}, "description": "Filter to specific placements. Uses this tool's canonical names (Top of Search / Product Page / Home / Rest of Search); they are translated to the smbot internal vocabulary before fetching. Consumer placements only \u2014 Amazon Business (B2B) has no value here. Omit this filter to see every placement the account has, including any whose name is not in the list above."}, "state": {"type": "array", "items": {"type": "string", "enum": ["enabled", "paused", "archived"]}, "description": "Filter by campaign state."}, "campaign_targeting_type": {"type": "array", "items": {"type": "string", "enum": ["AUTO", "MANUAL"]}, "description": "Filter by campaign targeting type (auto vs manual targeting)."}, "sort_field": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"], "description": "Field to sort results by. Defaults to 'cost'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of placement-level performance rows (campaign x placement x ad type by default) plus a summary over the FULL set.", "properties": {"placements": {"type": "array", "description": "Placement rows on this page.", "items": {"type": "object", "properties": {"timeWindowStart": {"type": "string", "description": "Daily bucket start (datetime string); present when grouped by timeWindowStart."}, "week": {"type": "string", "description": "Week bucket start (datetime string); present when grouped by week."}, "month": {"type": "string", "description": "Month bucket start (datetime string); present when grouped by month."}, "year": {"type": "integer", "description": "Year bucket; present when grouped by year."}, "campaignId": {"type": "string", "description": "Amazon campaign id; empty string when not grouped by campaign."}, "campaignName": {"type": "string", "description": "Campaign name from metadata enrichment."}, "placement": {"type": "string", "description": "Placement label: Top of Search, Product Page, Home, Rest of Search, or raw name."}, "sponsoredType": {"type": "string", "description": "Ad type (Product/Brand/Display)."}, "state": {"type": "string", "description": "Campaign state joined from metadata."}, "targetingType": {"type": "string", "description": "Campaign targeting type joined from metadata (AUTO/MANUAL)."}, "biddingStrategy": {"type": ["string", "null"], "description": "Bidding strategy code (e.g. LEGACY_FOR_SALES); null when unknown."}, "biddingStrategyName": {"type": ["string", "null"], "description": "Human-readable bidding strategy label; null when unknown."}, "spend": {"type": "number", "description": "Ad spend, 2 decimals."}, "sales": {"type": "number", "description": "Attributed sales, 2 decimals."}, "acos": {"type": "number", "description": "ACOS percent, 2 decimals."}, "roas": {"type": "number", "description": "ROAS, 2 decimals."}, "impressions": {"type": "integer", "description": "Impressions."}, "clicks": {"type": "integer", "description": "Clicks."}, "ctr": {"type": "number", "description": "Click-through rate percent, 2 decimals."}, "cpc": {"type": "number", "description": "Cost per click, 2 decimals."}, "orders": {"type": "integer", "description": "Attributed orders."}, "cvr": {"type": "number", "description": "Conversion rate percent, 2 decimals."}, "bidAdjustments": {"type": "array", "description": "Placement bid adjustments on the campaign (SP placementBidding or SB bidAdjustmentsByPlacement).", "items": {"type": "object", "properties": {"placement": {"type": ["string", "null"], "description": "Placement label in this tool's vocabulary."}, "bidAdjustmentPercent": {"type": ["number", "null"], "description": "Bid adjustment percentage for the placement."}}, "required": ["placement", "bidAdjustmentPercent"]}}, "basePlacement": {"type": "object", "description": "SellerMate-only saved base placement percentages (SP), null when unset.", "properties": {"topOfSearch": {"type": ["number", "null"], "description": "Base placement % for Top of Search."}, "detailPage": {"type": ["number", "null"], "description": "Base placement % for Product Page."}, "restOfSearch": {"type": ["number", "null"], "description": "Base placement % for Rest of Search."}}, "required": ["topOfSearch", "detailPage", "restOfSearch"]}}, "required": ["campaignId", "campaignName", "placement", "sponsoredType", "state", "targetingType", "biddingStrategy", "biddingStrategyName", "spend", "sales", "acos", "roas", "impressions", "clicks", "ctr", "cpc", "orders", "cvr", "bidAdjustments", "basePlacement"]}}, "summary": {"type": "object", "description": "Totals over the FULL (filtered) result set, not just this page.", "properties": {"totalSpend": {"type": "number", "description": "Sum of spend, 2 decimals."}, "totalSales": {"type": "number", "description": "Sum of sales, 2 decimals."}, "totalImpressions": {"type": "integer", "description": "Sum of impressions."}, "totalClicks": {"type": "integer", "description": "Sum of clicks."}, "totalOrders": {"type": "integer", "description": "Sum of orders."}, "overallAcos": {"type": "number", "description": "totalSpend / totalSales * 100; 0 when no sales."}, "overallRoas": {"type": "number", "description": "totalSales / totalSpend; 0 when no spend."}}, "required": ["totalSpend", "totalSales", "totalImpressions", "totalClicks", "totalOrders", "overallAcos", "overallRoas"]}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL row count.", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the full result set."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total (full row count)."}}, "required": ["placements", "summary", "pagination", "total"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_ad_groups": {"post": {"operationId": "list_ad_groups", "tags": ["Campaigns"], "summary": "List Ad Groups", "description": "Tool name: `list_ad_groups` \u00b7 **Scope:** requires `tools:read`.\n\nAd-group inventory (no metrics): `adGroupId`, name, parent `campaignId` / `campaignName`, `campaignState`, state, `defaultBid`, `sponsoredType`. This is where every ad-group-scoped write gets its `ad_group_id`. Defaults to ENABLED \u2014 pass `state` (or `[\"ALL\"]`) to widen; filter by `campaign_id` (recommended: an account-wide call can return thousands), `campaign_ids`, `name_search` or `sponsored_type`. Check `campaignState` before writing \u2014 Amazon rejects writes to ad groups of an archived campaign. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "campaign_id": {"type": "string", "description": "Filter to one campaign by its Amazon campaignId (from list_campaigns). Strongly recommended \u2014 an account-wide call can return thousands of ad groups."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to several campaigns by Amazon campaignId."}, "name_search": {"type": "string", "description": "Search ad groups by name (case-insensitive partial match)."}, "state": {"type": "array", "items": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED", "ALL"]}, "description": "Filter by ad group state. Defaults to ENABLED only. Pass ['ALL'] to return every state."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Filter by ad type (Sponsored Products, Brands, Display)."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of ad groups for the account, with pagination metadata and the account identity.", "properties": {"adGroups": {"type": "array", "description": "Ad group rows on this page, sorted by campaignId, name, adGroupId.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "SellerMate Mongo id of the ad group document."}, "adGroupId": {"type": "string", "description": "Amazon ad group id."}, "name": {"type": "string", "description": "Ad group name."}, "campaignId": {"type": "string", "description": "Parent Amazon campaign id."}, "campaignName": {"type": "string", "description": "Parent campaign name (denormalized by sync)."}, "state": {"type": "string", "description": "Ad group state, upper-cased (ENABLED, PAUSED, ARCHIVED)."}, "defaultBid": {"type": ["number", "null"], "description": "Ad group default bid, as stored."}, "sponsoredType": {"type": "string", "description": "Ad type (Product/Brand/Display)."}, "createdAt": {"type": ["string", "null"], "description": "Creation time (datetime string); falls back to the ObjectId generation time."}, "updatedAt": {"type": ["string", "null"], "description": "Last update time (datetime string) or null."}, "campaignState": {"type": "string", "description": "Parent campaign state, upper-cased; empty string when unknown."}}, "required": ["id", "adGroupId", "name", "campaignId", "campaignName", "state", "defaultBid", "sponsoredType", "createdAt", "updatedAt", "campaignState"]}}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL match count (capped at 5000 fetched).", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the full fetched set."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}, "fetchCapped": {"type": "integer", "description": "Present (5000) when the fetch cap was hit and more rows may exist."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "account": {"type": "object", "description": "The Amazon account the ad groups belong to.", "properties": {"id": {"type": "string", "description": "Amazon account id (Mongo id)."}, "name": {"type": "string", "description": "Account display name."}}, "required": ["id", "name"]}}, "required": ["adGroups", "pagination", "total", "account"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_campaigns": {"post": {"operationId": "list_campaigns", "tags": ["Campaigns"], "summary": "List Campaigns", "description": "Tool name: `list_campaigns` \u00b7 **Scope:** requires `tools:read`.\n\nCampaign inventory (no metrics): name, state, budget, type, targeting type. Defaults to ENABLED campaigns \u2014 pass `status` or `name_search` to widen.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "status": {"type": "array", "items": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"]}, "description": "Filter by campaign status. Defaults to ENABLED only. Omit when using name_search to find a campaign regardless of state."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Filter by ad type (Sponsored Products, Brands, Display)."}, "name_search": {"type": "string", "description": "Search campaigns by name (case-insensitive partial match)."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of advertising campaigns for the account, with pagination metadata and the account identity.", "properties": {"campaigns": {"type": "array", "description": "Campaign rows on this page, sorted by startDate then campaignId descending.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "SellerMate Mongo id of the campaign document."}, "campaignId": {"type": "string", "description": "Amazon campaign id."}, "name": {"type": "string", "description": "Campaign name."}, "type": {"type": "string", "description": "Ad type (sponsoredType): Product, Brand or Display."}, "state": {"type": "string", "description": "Campaign state, upper-cased (ENABLED, PAUSED, ARCHIVED)."}, "budget": {"type": ["number", "null"], "description": "Budget amount in the account currency, as stored."}, "budgetType": {"type": "string", "description": "Budget type, upper-cased (e.g. DAILY); empty string when unknown."}, "targetingType": {"type": "string", "description": "Campaign targeting type (AUTO or MANUAL), as stored."}, "startDate": {"type": "string", "description": "Campaign start date as stored (stringified)."}, "portfolioId": {"type": ["string", "null"], "description": "Amazon portfolio id, or null when the campaign has none."}}, "required": ["id", "campaignId", "name", "type", "state", "budget", "budgetType", "targetingType", "startDate", "portfolioId"]}}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL match count.", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the full result set."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total (full match count)."}, "account": {"type": "object", "description": "The Amazon account the campaigns belong to.", "properties": {"id": {"type": "string", "description": "Amazon account id (Mongo id)."}, "name": {"type": "string", "description": "Account display name."}}, "required": ["id", "name"]}}, "required": ["campaigns", "pagination", "total", "account"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_ad_group": {"post": {"operationId": "update_ad_group", "tags": ["Campaigns"], "summary": "Update Ad Group", "description": "Tool name: `update_ad_group` \u00b7 **Scope:** requires `tools:write`.\n\nUpdate up to 50 ad groups per call: `state` (ENABLED / PAUSED), `default_bid` and/or `name` per `ad_group_id` from `list_ad_groups`. Sponsored Products only \u2014 Sponsored Brands / Display items are rejected individually while the rest apply. Ad groups are never archived; PAUSED is the stop state. Atomic against workspace policy (`neverPause`, `maxBid` / `minBid`): one blocked field returns `422` and the whole batch is left untouched.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-ad-group updates. Each needs ad_group_id plus at least one of state/default_bid/name.", "items": {"type": "object", "properties": {"ad_group_id": {"type": "string", "description": "Amazon ad group ID (the `adGroupId` from list_ad_groups, NOT the Mongo id)."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "New ad group state. Pausing stops every target and product ad under this ad group, reversibly."}, "default_bid": {"type": "number", "exclusiveMinimum": 0, "description": "New default bid (absolute, not a delta). Inherited by new product ads and used for targets with no own bid. Subject to bid policy."}, "name": {"type": "string", "description": "New ad group name (2-1000 characters)."}}, "required": ["ad_group_id"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why the user wants this change. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Batch result of ad group updates (state/default_bid/name) from the shared entity-update engine; `status` is success, partial_success, failed, policy_violation or pending_approval.", "properties": {"status": {"type": "string", "description": "success, partial_success, failed, policy_violation or pending_approval."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome."}, "summary": {"type": "object", "description": "Counts over results.", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (pending_approval only), else 0."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item.", "items": {"type": "object", "properties": {"ad_group_id": {"type": ["string", "null"], "description": "Amazon ad group id of the item."}, "status": {"type": "string", "description": "updated, failed, not_found, blocked, would_pass or pending_approval."}, "error": {"type": "string", "description": "Failure reason; present on failed and not_found rows."}, "before": {"type": "object", "description": "Current values of the changed fields, keyed by field name.", "properties": {"state": {"type": ["string", "null"], "description": "Previous state."}, "default_bid": {"type": ["number", "null"], "description": "Previous default bid."}, "name": {"type": ["string", "null"], "description": "Previous name."}}}, "after": {"type": "object", "description": "Effective values after the update, keyed by field name.", "properties": {"state": {"type": "string", "description": "Requested state (ENABLED or PAUSED)."}, "default_bid": {"type": "number", "description": "Requested default bid."}, "name": {"type": "string", "description": "New name, trimmed."}}}, "changed": {"type": "array", "description": "Field names present in the item (state, default_bid, name).", "items": {"type": "string"}}, "violations": {"type": "array", "description": "Policy violations for this item (policy_violation only).", "items": {"type": "object", "description": "Policy check object (see policy_checks items)."}}, "note": {"type": "string", "description": "Side-effect note from the backend, when any."}}, "required": ["ad_group_id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid) covering succeeded items; null when nothing applied."}, "policy_checks": {"type": "array", "description": "Policy checks per item field (violations only on policy_violation/pending_approval; empty on pre-flight failure).", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "passed or violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message."}, "ad_group_id": {"type": ["string", "null"], "description": "Ad group the check applies to."}, "field": {"type": "string", "description": "Field the check applies to (state, default_bid, name)."}}, "required": ["policyId", "scope", "category", "rule", "result", "message", "ad_group_id", "field"]}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Link to the MCP Admin policies page; present on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles allowed to edit policies; present on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/update_campaign": {"post": {"operationId": "update_campaign", "tags": ["Campaigns"], "summary": "Update Campaign", "description": "Tool name: `update_campaign` \u00b7 **Scope:** requires `tools:write`.\n\nUpdate up to 50 campaigns per call; each item needs `campaign_id` plus at least one of `state` (ENABLED / PAUSED / ARCHIVED), `budget` (new absolute daily budget, not a delta) or `dynamic_bidding` (Sponsored Products only: bidding `strategy` \u2014 `LEGACY_FOR_SALES`, `AUTO_FOR_SALES`, `MANUAL`, `RULE_BASED` \u2014 and/or `placementBidding: [{placement, percentage}]`, 0\u2013900, merged into the campaign's existing settings). ARCHIVED is permanent, Sponsored Products only, and must be the only field on its item; it also pauses every ad group in the campaign. Atomic against workspace policy (budget min / max / multiplier, `neverPause`, `neverArchive`): one blocked field returns `422` and nothing is sent to Amazon.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-campaign updates. Each needs campaign_id plus at least one of state/budget/dynamic_bidding.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (the `campaignId` from list_campaigns, NOT the Mongo id)."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"], "description": "New campaign state. ARCHIVED is permanent, is Sponsored Products only, and must be the only field set on its item."}, "budget": {"type": "number", "exclusiveMinimum": 0, "description": "New absolute daily budget (not a delta). Subject to budget policy."}, "dynamic_bidding": {"type": "object", "description": "Sponsored Products bidding update. Set `strategy` and/or `placementBidding: [{placement, percentage}]` (percentage 0-900). Merged into the campaign's existing settings, so omitted placements are kept.", "properties": {"strategy": {"type": "string", "enum": ["LEGACY_FOR_SALES", "AUTO_FOR_SALES", "MANUAL", "RULE_BASED"], "description": "Bidding strategy. LEGACY_FOR_SALES = dynamic bids (down only); AUTO_FOR_SALES = dynamic bids (up and down); MANUAL = fixed bids; RULE_BASED = rule-based bidding."}, "placementBidding": {"type": "array", "description": "Per-placement bid adjustments. Each entry raises the bid for that placement by `percentage`%.", "items": {"type": "object", "properties": {"placement": {"type": "string", "enum": ["PLACEMENT_TOP", "PLACEMENT_PRODUCT_PAGE", "PLACEMENT_REST_OF_SEARCH", "SITE_AMAZON_BUSINESS"], "description": "Placement to adjust: PLACEMENT_TOP (top of search), PLACEMENT_PRODUCT_PAGE (product pages), PLACEMENT_REST_OF_SEARCH (rest of search), SITE_AMAZON_BUSINESS (Amazon Business)."}, "percentage": {"type": "number", "minimum": 0, "maximum": 900, "description": "Bid adjustment percent (0\u2013900)."}}, "required": ["placement", "percentage"]}}}}}, "required": ["campaign_id"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why the user wants this change. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Batch result of campaign updates (state/budget/dynamic_bidding) from the shared entity-update engine; `status` is success, partial_success, failed, policy_violation or pending_approval.", "properties": {"status": {"type": "string", "description": "success, partial_success, failed, policy_violation or pending_approval."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome."}, "summary": {"type": "object", "description": "Counts over results.", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (pending_approval only), else 0."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item.", "items": {"type": "object", "properties": {"campaign_id": {"type": ["string", "null"], "description": "Amazon campaign id of the item."}, "status": {"type": "string", "description": "updated, failed, not_found, blocked, would_pass or pending_approval."}, "error": {"type": "string", "description": "Failure reason; present on failed and not_found rows."}, "before": {"type": "object", "description": "Current values of the changed fields, keyed by field name.", "properties": {"state": {"type": ["string", "null"], "description": "Previous state."}, "budget": {"type": ["number", "null"], "description": "Previous daily budget."}, "dynamic_bidding": {"type": ["object", "null"], "description": "Previous stored dynamicBidding object."}}}, "after": {"type": "object", "description": "Effective values after the update, keyed by field name.", "properties": {"state": {"type": "string", "description": "Requested state."}, "budget": {"type": "number", "description": "Requested daily budget."}, "dynamic_bidding": {"type": "object", "description": "Merged dynamicBidding {strategy, placementBidding}.", "properties": {"strategy": {"type": "string", "description": "Bidding strategy."}, "placementBidding": {"type": "array", "description": "Per-placement adjustments.", "items": {"type": "object", "properties": {"placement": {"type": "string", "description": "SP placement predicate."}, "percentage": {"type": "number", "description": "Adjustment percent."}}}}}}}}, "changed": {"type": "array", "description": "Field names present in the item (state, budget, dynamic_bidding).", "items": {"type": "string"}}, "violations": {"type": "array", "description": "Policy violations for this item (policy_violation only).", "items": {"type": "object", "description": "Policy check object (see policy_checks items)."}}, "note": {"type": "string", "description": "Side-effect note, e.g. ad groups paused when a campaign was archived."}}, "required": ["campaign_id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid) covering succeeded items; null when nothing applied."}, "policy_checks": {"type": "array", "description": "Policy checks per item field (violations only on policy_violation/pending_approval; empty on pre-flight failure).", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "passed or violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message."}, "campaign_id": {"type": ["string", "null"], "description": "Campaign the check applies to."}, "field": {"type": "string", "description": "Field the check applies to (state, budget, dynamic_bidding)."}}, "required": ["policyId", "scope", "category", "rule", "result", "message", "campaign_id", "field"]}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Link to the MCP Admin policies page; present on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles allowed to edit policies; present on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/add_targets": {"post": {"operationId": "add_targets", "tags": ["Targeting"], "summary": "Add Targets", "description": "Tool name: `add_targets` \u00b7 **Scope:** requires `tools:write`.\n\nAdd up to 50 keyword or product targets to existing ad groups of MANUAL Sponsored Products campaigns (AUTO campaigns reject explicit targets). Each item needs `campaign_id`, `ad_group_id`, an absolute `bid`, and exactly one of `keyword_text` + `match_type` (`BROAD` / `EXACT` / `PHRASE`) or an `expression` list of `{type, value}` predicates (e.g. `ASIN_SAME_AS`, `ASIN_CATEGORY_SAME_AS`). A duplicate already in the ad group is rejected per item while the rest apply. Atomic against the workspace bid policy (`maxBid` / `minBid`): one blocked bid returns `422` and nothing is sent to Amazon.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "targets": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Targets to add to existing ad groups. Each item is either a keyword (keyword_text + match_type) or a product target (expression) \u2014 never both.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (from list_campaigns). Must be a MANUAL Sponsored Products campaign."}, "ad_group_id": {"type": "string", "description": "Amazon ad group ID the target is added to (from list_ad_groups)."}, "keyword_text": {"type": "string", "description": "Keyword targets only. The customer search term to target. Requires match_type; mutually exclusive with expression."}, "match_type": {"type": "string", "enum": ["BROAD", "EXACT", "PHRASE"], "description": "Keyword targets only. EXACT matches the term only; PHRASE matches it in order; BROAD matches related terms."}, "expression": {"type": "array", "minItems": 1, "description": "Product targets only. Predicates identifying what to target; mutually exclusive with keyword_text.", "items": {"type": "object", "properties": {"type": {"type": "string", "description": "Predicate type, e.g. ASIN_SAME_AS (a specific competitor ASIN) or ASIN_CATEGORY_SAME_AS (a category id)."}, "value": {"type": "string", "description": "The ASIN, category id, or brand id to target."}}, "required": ["type", "value"]}}, "bid": {"type": "number", "exclusiveMinimum": 0, "description": "Absolute bid for this target. Required \u2014 subject to the workspace's maxBid/minBid policy."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Optional. Defaults to ENABLED."}}, "required": ["campaign_id", "ad_group_id", "bid"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "targets"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of adding keyword/product targets to Sponsored Products ad groups: batch status, counts and one result row per requested target.", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "pending_approval", "failed"], "description": "Batch outcome; only success/partial_success mean targets were created."}, "applied": {"type": "boolean", "description": "True when Amazon was called and at least one target was added."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results.", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "added": {"type": "integer", "description": "Targets Amazon accepted (always 0 unless success/partial_success)."}, "failed": {"type": "integer", "description": "Targets rejected before or by Amazon."}, "pending": {"type": "integer", "description": "Targets queued for admin approval; present only on pending_approval."}}, "required": ["total", "added", "failed"]}, "results": {"type": "array", "description": "One row per requested target, sorted by the caller's index.", "items": {"type": "object", "description": "Per-target outcome; label keys depend on the target kind.", "properties": {"index": {"type": "integer", "description": "Position of the item in the request's targets array."}, "status": {"type": "string", "enum": ["added", "failed", "pending_approval"], "description": "Outcome for this item."}, "error": {"type": "string", "description": "Why the item failed (validation, unknown ad group, duplicate, or Amazon error)."}, "ad_group_id": {"type": "string", "description": "Ad group the target was aimed at; present once the item passed field validation."}, "target_type": {"type": "string", "enum": ["keyword", "product"], "description": "Resolved kind; present once the item passed field validation."}, "keyword_text": {"type": ["string", "null"], "description": "Keyword text for keyword targets (echoed raw on early validation failures)."}, "match_type": {"type": "string", "description": "BROAD / EXACT / PHRASE for keyword targets."}, "expression": {"type": ["array", "null"], "description": "Product-target predicates for product targets (echoed raw on early validation failures).", "items": {"type": "object", "description": "One {type, value} predicate as supplied by the caller.", "properties": {"type": {"type": "string", "description": "Predicate type, e.g. ASIN_SAME_AS."}, "value": {"type": "string", "description": "ASIN, category id or brand id."}}}}, "target_id": {"type": "string", "description": "Amazon id of the created target; present only on added rows."}, "bid": {"type": "number", "description": "Bid the target was created with; present only on added rows."}, "state": {"type": "string", "description": "State the target was created with; present only on added rows."}}, "required": ["index", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the added (or queued) targets; null when nothing was written or queued."}, "policy_checks": {"type": "array", "description": "PolicyService evaluations (all checks on success/pending; only violations on policy_violation). Absent on the early all-invalid failure.", "items": {"type": "object", "description": "One PolicyService check.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_search_term_performance": {"post": {"operationId": "get_search_term_performance", "tags": ["Targeting"], "summary": "Get Search Term Performance", "description": "Tool name: `get_search_term_performance` \u00b7 **Scope:** requires `tools:read`.\n\nCustomer search queries that triggered your ads, with their metrics; default grouping is search term. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["searchTerm", "targetingValue", "targetingType", "campaignName", "campaignId", "adGroupName", "adGroupId", "matchType", "reportType", "tags", "week", "month", "year"]}, "description": "Dimensions to group results by. Defaults to ['searchTerm']. Include 'targetingValue' to see which target each search term matched. Include 'campaignName' to break down by campaign."}, "search_term": {"type": "string", "description": "Filter by search term \u2014 case-insensitive PARTIAL match (e.g. 'yoga' returns 'yoga mat' and 'best yoga block')."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific campaigns by ID."}, "ad_group_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific ad groups by ID."}, "targeting_type": {"type": "array", "items": {"type": "string", "enum": ["EXACT", "PHRASE", "BROAD", "LOOSE_MATCH", "CLOSE_MATCH", "SUBSTITUTES", "COMPLEMENTS"]}, "description": "Filter by the targeting type that triggered the search term."}, "sort_field": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"], "description": "Field to sort results by. Defaults to 'cost'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "tag_values": {"type": "array", "items": {"type": "string"}, "description": "Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified."}, "group_by_tag": {"type": "boolean", "description": "When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true."}, "include_tags": {"type": "boolean", "description": "When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId)."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Aggregated performance metrics per customer search term (one page of rows), a full-set summary, the date range and pagination.", "properties": {"data": {"type": "array", "description": "Performance rows for the requested page, sorted by sort_field/sort_direction over the full set.", "items": {"type": "object", "description": "One aggregated row: the requested group_by dimension keys plus the metric keys (_transform_performance_results).", "properties": {"searchTerm": {"type": "string", "description": "Customer search term (default grouping)."}, "targetingValue": {"type": "string", "description": "Target that matched the search term; present when grouped by it."}, "targetingType": {"type": "string", "description": "Match/expression type that triggered the term; present when grouped by it."}, "campaignName": {"type": "string", "description": "Campaign name; present when grouped by it."}, "campaignId": {"type": "string", "description": "Amazon campaign id; present when grouped by it."}, "adGroupName": {"type": "string", "description": "Ad group name; present when grouped by it."}, "adGroupId": {"type": "string", "description": "Amazon ad group id; present when grouped by it."}, "matchType": {"type": "string", "description": "Keyword match type; present when grouped by it."}, "reportType": {"type": "string", "description": "Source report type; present when grouped by it."}, "week": {"type": ["string", "number"], "description": "Week bucket; present when grouped by week."}, "month": {"type": ["string", "number"], "description": "Month bucket; present when grouped by month."}, "year": {"type": ["string", "number"], "description": "Year bucket; present when grouped by year."}, "tagValue": {"type": "string", "description": "Tag label; present when group_by_tag=true (one row per tag)."}, "spend": {"type": "number", "description": "Ad spend (cost), rounded to 2 decimals."}, "sales": {"type": "number", "description": "Attributed sales 14d, rounded to 2 decimals."}, "impressions": {"type": "integer", "description": "Impressions."}, "clicks": {"type": "integer", "description": "Clicks."}, "orders": {"type": "integer", "description": "Purchases."}, "acos": {"type": ["number", "null"], "description": "ACOS, 2 decimals; null when undefined (divide-by-zero)."}, "roas": {"type": ["number", "null"], "description": "ROAS, 2 decimals; null when undefined."}, "ctr": {"type": ["number", "null"], "description": "Click-through rate, 2 decimals; null when undefined."}, "cpc": {"type": ["number", "null"], "description": "Cost per click, 2 decimals; null when undefined."}, "cvr": {"type": ["number", "null"], "description": "Conversion rate, 2 decimals; null when undefined."}, "tags": {"type": "array", "description": "Active legacy search_term tags for the row's searchTerm; present only when include_tags=true.", "items": {"type": "object", "description": "One legacy tag assignment.", "properties": {"_id": {"type": "string", "description": "Tag definition id."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Hex text color."}, "bgColor": {"type": "string", "description": "Hex background color."}, "tagEntityId": {"type": "string", "description": "Id of the tagsEntity assignment row."}}, "required": ["_id", "value", "color", "bgColor", "tagEntityId"]}}}, "required": ["spend", "sales", "impressions", "clicks", "orders", "acos", "roas", "ctr", "cpc", "cvr"]}}, "summary": {"type": "object", "description": "Totals over the FULL result set (not just this page); zeros when there are no rows.", "properties": {"totalSpend": {"type": "number", "description": "Sum of spend, 2 decimals."}, "totalSales": {"type": "number", "description": "Sum of attributed sales 14d, 2 decimals."}, "totalImpressions": {"type": "integer", "description": "Sum of impressions."}, "totalClicks": {"type": "integer", "description": "Sum of clicks."}, "totalOrders": {"type": "integer", "description": "Sum of purchases."}, "overallAcos": {"type": "number", "description": "totalSpend / totalSales * 100; 0 when no sales."}, "overallRoas": {"type": "number", "description": "totalSales / totalSpend; 0 when no spend."}}, "required": ["totalSpend", "totalSales", "totalImpressions", "totalClicks", "totalOrders", "overallAcos", "overallRoas"]}, "dateRange": {"type": "object", "description": "The requested reporting window.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "pagination": {"type": "object", "description": "Page metadata computed over the full result set (_pagination.paginate).", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the FULL result set, not just this page."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Total rows in the full set (same as pagination.total)."}, "account": {"type": "object", "description": "The Amazon account the results belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["data", "summary", "dateRange", "pagination", "total", "account", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_targeting_performance": {"post": {"operationId": "get_targeting_performance", "tags": ["Targeting"], "summary": "Get Targeting Performance", "description": "Tool name: `get_targeting_performance` \u00b7 **Scope:** requires `tools:read`.\n\nMetrics per target over a date range; default grouping is targeting value + campaign. Filter by campaign/ad-group/type; sortable. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["targetingValue", "targetingType", "campaignName", "campaignId", "adGroupName", "adGroupId", "reportType", "sponsoredType", "tags", "week", "month", "year", "dayOfWeek"]}, "description": "Dimensions to group results by. Defaults to ['targetingValue', 'campaignName']. Use time fields (week, month) for trend analysis. reportType maps to ad type: spTargetingDaily=Sponsored Products, sbTargetingDaily=Sponsored Brands, sdTargetingDaily=Sponsored Display."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific campaigns by ID."}, "ad_group_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific ad groups by ID."}, "targeting_type": {"type": "array", "items": {"type": "string", "enum": ["EXACT", "PHRASE", "BROAD", "ASIN_SAME_AS", "ASIN_BRAND_SAME_AS", "ASIN_CATEGORY_SAME_AS", "ASIN_EXPANDED_FROM", "LOOSE_MATCH", "CLOSE_MATCH", "SUBSTITUTES", "COMPLEMENTS", "AUDIENCE", "PURCHASES", "SIMILAR_PRODUCT", "VIEWS"]}, "description": "Filter by targeting type. Keyword: EXACT/PHRASE/BROAD. Product: ASIN_SAME_AS/ASIN_BRAND_SAME_AS/ASIN_CATEGORY_SAME_AS. Auto: LOOSE_MATCH/CLOSE_MATCH/SUBSTITUTES/COMPLEMENTS."}, "targeting_value": {"type": "string", "description": "Filter by targeting value (keyword text or ASIN) \u2014 case-insensitive PARTIAL match."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Filter by ad type."}, "sort_field": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"], "description": "Field to sort results by. Defaults to 'cost'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "tag_values": {"type": "array", "items": {"type": "string"}, "description": "Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified."}, "group_by_tag": {"type": "boolean", "description": "When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true."}, "include_tags": {"type": "boolean", "description": "When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId)."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Aggregated performance metrics per target (one page of rows), a full-set summary, the date range and pagination.", "properties": {"data": {"type": "array", "description": "Performance rows for the requested page, sorted by sort_field/sort_direction over the full set.", "items": {"type": "object", "description": "One aggregated row: the requested group_by dimension keys plus the metric keys (_transform_performance_results).", "properties": {"targetingValue": {"type": "string", "description": "Keyword text or product expression value (default grouping)."}, "campaignName": {"type": "string", "description": "Campaign name (default grouping)."}, "targetingType": {"type": "string", "description": "Match type or expression type; present when grouped by it."}, "campaignId": {"type": "string", "description": "Amazon campaign id; present when grouped by it."}, "adGroupName": {"type": "string", "description": "Ad group name; present when grouped by it."}, "adGroupId": {"type": "string", "description": "Amazon ad group id; present when grouped by it."}, "reportType": {"type": "string", "description": "spTargetingDaily / sbTargetingDaily / sdTargetingDaily; present when grouped by it."}, "sponsoredType": {"type": "string", "description": "Ad type; present when grouped by it."}, "week": {"type": ["string", "number"], "description": "Week bucket; present when grouped by week."}, "month": {"type": ["string", "number"], "description": "Month bucket; present when grouped by month."}, "year": {"type": ["string", "number"], "description": "Year bucket; present when grouped by year."}, "dayOfWeek": {"type": ["string", "number"], "description": "Day-of-week bucket; present when grouped by dayOfWeek."}, "tagValue": {"type": "string", "description": "Tag label; present when group_by_tag=true (one row per tag)."}, "spend": {"type": "number", "description": "Ad spend (cost), rounded to 2 decimals."}, "sales": {"type": "number", "description": "Attributed sales 14d, rounded to 2 decimals."}, "impressions": {"type": "integer", "description": "Impressions."}, "clicks": {"type": "integer", "description": "Clicks."}, "orders": {"type": "integer", "description": "Purchases."}, "acos": {"type": ["number", "null"], "description": "ACOS, 2 decimals; null when undefined (divide-by-zero)."}, "roas": {"type": ["number", "null"], "description": "ROAS, 2 decimals; null when undefined."}, "ctr": {"type": ["number", "null"], "description": "Click-through rate, 2 decimals; null when undefined."}, "cpc": {"type": ["number", "null"], "description": "Cost per click, 2 decimals; null when undefined."}, "cvr": {"type": ["number", "null"], "description": "Conversion rate, 2 decimals; null when undefined."}, "tags": {"type": "array", "description": "Active legacy tags for the row's targetingValue; present only when include_tags=true.", "items": {"type": "object", "description": "One legacy tag assignment.", "properties": {"_id": {"type": "string", "description": "Tag definition id."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Hex text color."}, "bgColor": {"type": "string", "description": "Hex background color."}, "tagEntityId": {"type": "string", "description": "Id of the tagsEntity assignment row."}}, "required": ["_id", "value", "color", "bgColor", "tagEntityId"]}}}, "required": ["spend", "sales", "impressions", "clicks", "orders", "acos", "roas", "ctr", "cpc", "cvr"]}}, "summary": {"type": "object", "description": "Totals over the FULL result set (not just this page); zeros when there are no rows.", "properties": {"totalSpend": {"type": "number", "description": "Sum of spend, 2 decimals."}, "totalSales": {"type": "number", "description": "Sum of attributed sales 14d, 2 decimals."}, "totalImpressions": {"type": "integer", "description": "Sum of impressions."}, "totalClicks": {"type": "integer", "description": "Sum of clicks."}, "totalOrders": {"type": "integer", "description": "Sum of purchases."}, "overallAcos": {"type": "number", "description": "totalSpend / totalSales * 100; 0 when no sales."}, "overallRoas": {"type": "number", "description": "totalSales / totalSpend; 0 when no spend."}}, "required": ["totalSpend", "totalSales", "totalImpressions", "totalClicks", "totalOrders", "overallAcos", "overallRoas"]}, "dateRange": {"type": "object", "description": "The requested reporting window.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "pagination": {"type": "object", "description": "Page metadata computed over the full result set (_pagination.paginate).", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the FULL result set, not just this page."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Total rows in the full set (same as pagination.total)."}, "account": {"type": "object", "description": "The Amazon account the results belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["data", "summary", "dateRange", "pagination", "total", "account", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_targets": {"post": {"operationId": "list_targets", "tags": ["Targeting"], "summary": "List Targets", "description": "Tool name: `list_targets` \u00b7 **Scope:** requires `tools:read`.\n\nFull target inventory (keywords / product / auto): id, current bid, state, match type, keyword text or product expression, parent campaign/ad-group ids, marketplace/country. Returns ALL states by default. No metrics. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "state": {"type": "array", "items": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED", "ALL"]}, "description": "Filter by target state. Omit (or pass ['ALL']) to return targets in ALL states \u2014 list_targets is a full inventory call, not performance-bound."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Filter by ad type (Sponsored Products/Brands/Display)."}, "campaign_id": {"type": "string", "description": "Filter targets to a specific campaign by campaign ID."}, "ad_group_id": {"type": "string", "description": "Filter targets to a specific ad group by ad group ID (from list_ad_groups)."}, "keyword_text": {"type": "string", "description": "Search for targets by keyword text \u2014 case-insensitive PARTIAL match against the target's keyword text / targeting value."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format. Defaults to 30 days ago."}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format. Defaults to today."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "include_tags": {"type": "boolean", "description": "When true, each target includes active legacy tags for its targetingValue (loaded from MarketingData)."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the account's targeting inventory (keywords, product and auto targets) with pagination metadata and no performance metrics.", "properties": {"targets": {"type": "array", "description": "Target rows for the requested page (full set sorted by cost desc, then sliced).", "items": {"type": "object", "description": "One KeywordTargetData row as flattened by _transform_entity_results.", "properties": {"id": {"type": "string", "description": "Amazon target/keyword id; pass as target_id to update_target."}, "bid": {"type": ["number", "null"], "description": "Current bid at Amazon."}, "baseBid": {"type": ["number", "null"], "description": "SellerMate-only base bid that dayparting/automation multipliers apply to."}, "state": {"type": "string", "description": "Target state, e.g. ENABLED, PAUSED, ARCHIVED."}, "keywordText": {"type": "string", "description": "Keyword text; empty string for product/auto targets."}, "matchType": {"type": "string", "description": "Keyword match type (BROAD/EXACT/PHRASE); empty for product targets."}, "targetingValue": {"type": "string", "description": "Keyword text, or the product-expression value for product targets."}, "sponsoredType": {"type": "string", "description": "Ad type: Product, Brand or Display."}, "type": {"type": "string", "description": "Row kind: Keyword or Target (product/auto target)."}, "expressionType": {"type": "string", "description": "Product-target expression type (e.g. ASIN_SAME_AS); empty for keywords."}, "expressionValue": {"type": "string", "description": "First expression predicate value; key omitted when empty."}, "targetProductName": {"type": "string", "description": "Resolved product name for ASIN targets; key omitted when empty."}, "targetAsin": {"type": "string", "description": "Resolved ASIN for product targets; key omitted when empty."}, "campaignName": {"type": "string", "description": "Parent campaign name."}, "campaignId": {"type": "string", "description": "Parent Amazon campaign id."}, "adGroupName": {"type": "string", "description": "Parent ad group name."}, "adGroupId": {"type": "string", "description": "Parent Amazon ad group id."}, "marketplace": {"type": ["string", "null"], "description": "Account marketplaceStringId (constant per account)."}, "country": {"type": ["string", "null"], "description": "Account countryCode (constant per account)."}, "tags": {"type": "array", "description": "Active legacy tags for this targetingValue; present only when include_tags=true.", "items": {"type": "object", "description": "One legacy tag assignment (tag_helpers._format_tag_row).", "properties": {"_id": {"type": "string", "description": "Tag definition id."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Hex text color."}, "bgColor": {"type": "string", "description": "Hex background color."}, "tagEntityId": {"type": "string", "description": "Id of the tagsEntity assignment row."}}, "required": ["_id", "value", "color", "bgColor", "tagEntityId"]}}}, "required": ["id", "bid", "baseBid", "state", "keywordText", "matchType", "targetingValue", "sponsoredType", "type", "expressionType", "campaignName", "campaignId", "adGroupName", "adGroupId", "marketplace", "country"]}}, "pagination": {"type": "object", "description": "Page metadata computed over the full result set (_pagination.paginate).", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the FULL result set, not just this page."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Total targets in the full set (same as pagination.total)."}, "account": {"type": "object", "description": "The Amazon account the results belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}}, "required": ["targets", "pagination", "total", "account"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_target": {"post": {"operationId": "update_target", "tags": ["Targeting"], "summary": "Update Target", "description": "Tool name: `update_target` \u00b7 **Scope:** requires `tools:write`.\n\nUpdate up to 50 keyword or product targets per call; each item needs `target_id` from `list_targets` plus at least one of `bid` (absolute, sent to Amazon), `state` (ENABLED / PAUSED / ARCHIVED \u2014 ARCHIVED is permanent) or `baseBid`. `baseBid` is SellerMate-only and never sent to Amazon: it is the reference bid that bid dayparting and automation multipliers apply to, and this is the only tool that sets it; an item with only `baseBid` makes no Amazon change. Atomic against workspace policy (bid multiplier, `neverPause`, `neverArchive`): one blocked field returns `422`.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-target updates. Each needs target_id plus at least one of bid/state/baseBid.", "items": {"type": "object", "properties": {"target_id": {"type": "string", "description": "Target id from list_targets (keyword or product target)."}, "bid": {"type": "number", "exclusiveMinimum": 0, "description": "New absolute bid (not a delta). Sent to Amazon."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"], "description": "New state. ARCHIVED is permanent."}, "baseBid": {"type": "number", "exclusiveMinimum": 0, "description": "New base bid \u2014 a SellerMate-only reference (NOT sent to Amazon) that bid-dayparting/automation multipliers apply to. Only baseBid = local update, no Amazon change."}}, "required": ["target_id"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of a batch of target bid/state/baseBid updates: top-level status plus one result row per update item (entity-update engine response contract).", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "pending_approval", "failed"], "description": "Batch outcome; only success/partial_success mean something was written."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results (_framework._summary).", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (non-zero only on pending_approval)."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item; keys beyond target_id/status depend on how far the item got.", "items": {"type": "object", "description": "Per-target outcome.", "properties": {"target_id": {"type": ["string", "null"], "description": "The target id from the request item."}, "status": {"type": "string", "enum": ["updated", "failed", "not_found", "blocked", "would_pass", "pending_approval"], "description": "Outcome for this item."}, "error": {"type": "string", "description": "Failure reason; present on failed / not_found."}, "before": {"type": "object", "description": "Current values of the changed fields (only keys in `changed`); present once the target resolved.", "properties": {"bid": {"type": ["number", "null"], "description": "Bid before the update."}, "state": {"type": ["string", "null"], "description": "State before the update (upper-cased)."}, "baseBid": {"type": ["number", "null"], "description": "Base bid before the update."}}}, "after": {"type": "object", "description": "Requested values of the changed fields (only keys in `changed`).", "properties": {"bid": {"type": "number", "description": "New absolute bid."}, "state": {"type": "string", "description": "New state: ENABLED, PAUSED or ARCHIVED."}, "baseBid": {"type": "number", "description": "New SellerMate-only base bid."}}}, "changed": {"type": "array", "description": "Names of the fields present in the update item.", "items": {"type": "string", "enum": ["bid", "state", "baseBid"]}}, "violations": {"type": "array", "description": "Policy checks that failed for this item; present on blocked / would_pass rows.", "items": {"type": "object", "description": "One violated PolicyService check.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "description": "Always violated here."}, "message": {"type": "string", "description": "Human-readable reason."}}}}, "note": {"type": "string", "description": "Backend side-effect note carried onto an updated row, when the backend returns one."}}, "required": ["target_id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the succeeded (or queued) items; null when nothing was written or queued."}, "policy_checks": {"type": "array", "description": "Policy evaluations (all checks on success; only violations on policy_violation / pending_approval).", "items": {"type": "object", "description": "One PolicyService check annotated with the item it applies to.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}, "target_id": {"type": ["string", "null"], "description": "Target the check was evaluated for."}, "field": {"type": "string", "description": "Field (bid or state) the check was evaluated for."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/add_negative_keywords": {"post": {"operationId": "add_negative_keywords", "tags": ["Negatives"], "summary": "Add Negative Keywords", "description": "Tool name: `add_negative_keywords` \u00b7 **Scope:** requires `tools:write`.\n\nAdd up to 50 negative keywords to existing campaigns or ad groups. Each item needs `campaign_id`, `keyword_text` and `match_type` (`NEGATIVE_EXACT` / `NEGATIVE_PHRASE` / `NEGATIVE_BROAD`); include `ad_group_id` for an ad-group-level negative, omit it for campaign level. `state` defaults to ENABLED. Atomic: a negation blocked by workspace policy returns `422` and nothing is sent to Amazon.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "negatives": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Negative keywords to add. Omit ad_group_id for a campaign-level negative.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (from list_campaigns)."}, "ad_group_id": {"type": "string", "description": "Optional. Amazon ad group ID (from list_ad_groups) for an ad-group-level negative. Omit for campaign-level."}, "keyword_text": {"type": "string", "description": "The search term to negate."}, "match_type": {"type": "string", "enum": ["NEGATIVE_EXACT", "NEGATIVE_PHRASE", "NEGATIVE_BROAD"], "description": "Negative match type."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Optional. Defaults to ENABLED."}}, "required": ["campaign_id", "keyword_text", "match_type"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "negatives"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of adding campaign- or ad-group-level negative keywords: batch status and one result row per requested negative.", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "failed"], "description": "Batch outcome; only success/partial_success mean negatives were created."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one negative was added."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results; present only after the backend was called (success/partial_success/failed-at-Amazon).", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "added": {"type": "integer", "description": "Negatives the bulk manager reported as created."}, "failed": {"type": "integer", "description": "Negatives that failed validation or at Amazon."}}, "required": ["total", "added", "failed"]}, "results": {"type": "array", "description": "One row per requested negative (validation failures first, then backend outcomes).", "items": {"type": "object", "description": "Per-negative outcome.", "properties": {"index": {"type": "integer", "description": "Position of the item in the request's negatives array."}, "status": {"type": "string", "enum": ["added", "failed"], "description": "Outcome for this item."}, "keyword_text": {"type": ["string", "null"], "description": "The negated search term (may be null on validation failures)."}, "match_type": {"type": "string", "description": "NEGATIVE_EXACT / NEGATIVE_PHRASE / NEGATIVE_BROAD; present once validated."}, "scope": {"type": "string", "enum": ["campaign", "ad_group"], "description": "Level the negative was applied at; present once validated."}, "error": {"type": "string", "description": "Validation or Amazon error; present on failed rows."}}, "required": ["index", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the added negatives; null when none were added. Absent on early returns."}, "policy_checks": {"type": "array", "description": "PolicyService evaluations (all checks on success; only violations on policy_violation). Absent on the early all-invalid failure.", "items": {"type": "object", "description": "One PolicyService check (addNegation category).", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "results", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/add_negative_product_targets": {"post": {"operationId": "add_negative_product_targets", "tags": ["Negatives"], "summary": "Add Negative Product Targets", "description": "Tool name: `add_negative_product_targets` \u00b7 **Scope:** requires `tools:write`.\n\nAdd up to 50 negative product targets to existing campaigns or ad groups. Each item needs `campaign_id` and an `expression` of `{type, value}` predicates \u2014 `ASIN_SAME_AS` with the ASIN to negate; brand-level negation is not supported. Include `ad_group_id` for an ad-group-level negative, omit it for campaign level. Atomic: a negation blocked by workspace policy returns `422` and nothing is sent to Amazon.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "negatives": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Negative product targets to add. Omit ad_group_id for campaign-level.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (from list_campaigns)."}, "ad_group_id": {"type": "string", "description": "Optional. Amazon ad group ID (from list_ad_groups) for an ad-group-level negative. Omit for campaign-level."}, "expression": {"type": "array", "minItems": 1, "description": "Predicates identifying what to negate.", "items": {"type": "object", "properties": {"type": {"type": "string", "enum": ["ASIN_SAME_AS"], "description": "ASIN_SAME_AS \u2014 negate a specific product by ASIN. (Brand negation not supported yet.)"}, "value": {"type": "string", "description": "The ASIN to negate."}}, "required": ["type", "value"]}}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED"], "description": "Optional. Defaults to ENABLED."}}, "required": ["campaign_id", "expression"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "negatives"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of adding campaign- or ad-group-level negative product targets (ASIN_SAME_AS): batch status and one result row per requested negative.", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "failed"], "description": "Batch outcome; only success/partial_success mean negatives were created."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one negative was added."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results; present only after the backend was called (success/partial_success/failed-at-Amazon).", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "added": {"type": "integer", "description": "Negatives the bulk manager reported as created."}, "failed": {"type": "integer", "description": "Negatives that failed validation or at Amazon."}}, "required": ["total", "added", "failed"]}, "results": {"type": "array", "description": "One row per requested negative (validation failures first, then backend outcomes).", "items": {"type": "object", "description": "Per-negative outcome.", "properties": {"index": {"type": "integer", "description": "Position of the item in the request's negatives array."}, "status": {"type": "string", "enum": ["added", "failed"], "description": "Outcome for this item."}, "expression": {"type": "array", "description": "The negated expression as supplied; present once validated.", "items": {"type": "object", "description": "One {type, value} predicate.", "properties": {"type": {"type": "string", "description": "Predicate type (ASIN_SAME_AS)."}, "value": {"type": "string", "description": "The negated ASIN."}}}}, "scope": {"type": "string", "enum": ["campaign", "ad_group"], "description": "Level the negative was applied at; present once validated."}, "error": {"type": "string", "description": "Validation or Amazon error; present on failed rows."}}, "required": ["index", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the added negatives; null when none were added. Absent on early returns."}, "policy_checks": {"type": "array", "description": "PolicyService evaluations (all checks on success; only violations on policy_violation). Absent on the early all-invalid failure.", "items": {"type": "object", "description": "One PolicyService check (addNegation category).", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "results", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/list_negative_targets": {"post": {"operationId": "list_negative_targets", "tags": ["Negatives"], "summary": "List Negative Targets", "description": "Tool name: `list_negative_targets` \u00b7 **Scope:** requires `tools:read`.\n\nNegative-targeting inventory: negative keywords and negative product targets at campaign and ad-group scope \u2014 match type, state, keyword text or product expression, parent ids, created/updated dates. No metrics. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "data_type": {"type": "string", "enum": ["keyword", "product", "all"], "description": "Negative keywords, negative product targets, or all (default)."}, "scope": {"type": "string", "enum": ["campaign", "adGroup", "all"], "description": "Restrict to campaign-level or ad-group-level negatives. Defaults to all."}, "campaign_id": {"type": "string", "description": "Filter to a single campaign by ID."}, "ad_group_id": {"type": "string", "description": "Filter to a single ad group by ID."}, "state": {"type": "array", "items": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED", "ALL"]}, "description": "Filter by state. Omit (or pass ['ALL']) to return all states."}, "sponsored_type": {"type": "array", "items": {"type": "string", "enum": ["Product", "Brand", "Display"]}, "description": "Filter by ad type."}, "match_type": {"type": "array", "items": {"type": "string"}, "description": "Filter by negative match type, e.g. NEGATIVE_EXACT, NEGATIVE_PHRASE (keywords) or ASIN_SAME_AS (product targets)."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the account's negative keywords and negative product targets (campaign- and ad-group-level) with pagination metadata.", "properties": {"negativeTargets": {"type": "array", "description": "Negative rows for the requested page (NegativeKeywordTargetData docs flattened by _flatten_negative).", "items": {"type": "object", "description": "One negative keyword or negative product target.", "properties": {"id": {"type": "string", "description": "Amazon negative id; pass as negative_id to update_negative_keyword / update_negative_product_target."}, "type": {"type": "string", "description": "Doc type: NegativeKeyword, CampaignNegativeKeyword, NegativeTarget or CampaignNegativeTarget."}, "scope": {"type": "string", "enum": ["campaign", "adGroup"], "description": "campaign for campaign-level negatives, adGroup otherwise."}, "campaignId": {"type": "string", "description": "Parent Amazon campaign id."}, "adGroupId": {"type": ["string", "null"], "description": "Parent Amazon ad group id; null for campaign-level negatives."}, "state": {"type": "string", "description": "Negative state, e.g. ENABLED, PAUSED, ARCHIVED."}, "sponsoredType": {"type": "string", "description": "Ad type: Product, Brand or Display."}, "matchType": {"type": "string", "description": "NEGATIVE_EXACT / NEGATIVE_PHRASE / NEGATIVE_BROAD for keywords, expression type for products."}, "createdAt": {"type": ["string", "null"], "description": "Doc insertedAt timestamp (datetime serialized as string)."}, "updatedAt": {"type": ["string", "null"], "description": "Doc updatedAt timestamp (datetime serialized as string)."}, "keywordText": {"type": "string", "description": "Negated search term; present only for keyword types."}, "expression": {"type": "array", "description": "Negative product expression predicates; present only for product-target types.", "items": {"type": "object", "description": "One expression predicate as stored by the sync.", "properties": {"type": {"type": "string", "description": "Predicate type, e.g. ASIN_SAME_AS."}, "value": {"type": "string", "description": "Negated ASIN or brand id."}}}}, "marketplace": {"type": ["string", "null"], "description": "Account marketplaceStringId (constant per account)."}, "country": {"type": ["string", "null"], "description": "Account countryCode (constant per account)."}}, "required": ["id", "type", "scope", "campaignId", "adGroupId", "state", "sponsoredType", "matchType", "createdAt", "updatedAt", "marketplace", "country"]}}, "pagination": {"type": "object", "description": "Page metadata computed over the full fetched set (_pagination.paginate).", "properties": {"page": {"type": "integer", "description": "0-indexed page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-500)."}, "total": {"type": "integer", "description": "Size of the FULL fetched set, not just this page."}, "totalPages": {"type": "integer", "description": "Number of pages in the full set."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}, "fetchCapped": {"type": "integer", "description": "Present (value 5000) when the underlying fetch hit the pull cap."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Total negatives in the full fetched set (same as pagination.total)."}, "account": {"type": "object", "description": "The Amazon account the results belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}}, "required": ["negativeTargets", "pagination", "total", "account"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_negative_keyword": {"post": {"operationId": "update_negative_keyword", "tags": ["Negatives"], "summary": "Update Negative Keyword", "description": "Tool name: `update_negative_keyword` \u00b7 **Scope:** requires `tools:write`.\n\nSet the state of up to 50 negative keywords per call: each item is `{negative_id, state}` with the negative's `id` from `list_negative_targets` and `state` ENABLED / PAUSED / ARCHIVED. Scope, campaign and ad group are derived from the id. ARCHIVED removes the negative permanently.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-negative keyword state changes.", "items": {"type": "object", "properties": {"negative_id": {"type": "string", "description": "The negative keyword's `id` from list_negative_targets."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"], "description": "Target state. ARCHIVED = permanent removal."}}, "required": ["negative_id", "state"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of a batch of negative-keyword state changes: top-level status plus one result row per update item (entity-update engine response contract).", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "pending_approval", "failed"], "description": "Batch outcome; only success/partial_success mean something was written."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results (_framework._summary).", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (non-zero only on pending_approval)."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item; keys beyond negative_id/status depend on how far the item got.", "items": {"type": "object", "description": "Per-negative outcome.", "properties": {"negative_id": {"type": ["string", "null"], "description": "The negative's Amazon id (from the resolved doc or the request)."}, "status": {"type": "string", "enum": ["updated", "failed", "not_found", "blocked", "would_pass", "pending_approval"], "description": "Outcome for this item."}, "error": {"type": "string", "description": "Failure reason; present on failed / not_found."}, "before": {"type": "object", "description": "Current value of the changed field; present once the negative resolved.", "properties": {"state": {"type": ["string", "null"], "description": "State before the update (upper-cased)."}}}, "after": {"type": "object", "description": "Requested value of the changed field.", "properties": {"state": {"type": "string", "description": "New state: ENABLED, PAUSED or ARCHIVED (ARCHIVED deletes at Amazon)."}}}, "changed": {"type": "array", "description": "Names of the fields present in the update item (always state).", "items": {"type": "string"}}, "violations": {"type": "array", "description": "Policy checks that failed for this item; present on blocked / would_pass rows.", "items": {"type": "object", "description": "One violated PolicyService check.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "description": "Always violated here."}, "message": {"type": "string", "description": "Human-readable reason."}}}}, "note": {"type": "string", "description": "Backend side-effect note carried onto an updated row, when the backend returns one."}}, "required": ["negative_id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the succeeded (or queued) items; null when nothing was written or queued."}, "policy_checks": {"type": "array", "description": "Policy evaluations (all checks on success; only violations on policy_violation / pending_approval).", "items": {"type": "object", "description": "One PolicyService check annotated with the item it applies to.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}, "negative_id": {"type": ["string", "null"], "description": "Negative the check was evaluated for."}, "field": {"type": "string", "description": "Field the check was evaluated for (state)."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/update_negative_product_target": {"post": {"operationId": "update_negative_product_target", "tags": ["Negatives"], "summary": "Update Negative Product Target", "description": "Tool name: `update_negative_product_target` \u00b7 **Scope:** requires `tools:write`.\n\nSet the state of up to 50 negative product targets per call: each item is `{negative_id, state}` with the negative's `id` from `list_negative_targets` and `state` ENABLED / PAUSED / ARCHIVED. Scope, campaign and ad group are derived from the id. ARCHIVED removes the negative permanently.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-negative product target state changes.", "items": {"type": "object", "properties": {"negative_id": {"type": "string", "description": "The negative product target's `id` from list_negative_targets."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"], "description": "Target state. ARCHIVED = permanent removal."}}, "required": ["negative_id", "state"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of a batch of negative-product-target state changes: top-level status plus one result row per update item (entity-update engine response contract).", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "policy_violation", "pending_approval", "failed"], "description": "Batch outcome; only success/partial_success mean something was written."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome for the caller."}, "summary": {"type": "object", "description": "Counts over results (_framework._summary).", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (non-zero only on pending_approval)."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item; keys beyond negative_id/status depend on how far the item got.", "items": {"type": "object", "description": "Per-negative outcome.", "properties": {"negative_id": {"type": ["string", "null"], "description": "The negative's Amazon id (from the resolved doc or the request)."}, "status": {"type": "string", "enum": ["updated", "failed", "not_found", "blocked", "would_pass", "pending_approval"], "description": "Outcome for this item."}, "error": {"type": "string", "description": "Failure reason; present on failed / not_found."}, "before": {"type": "object", "description": "Current value of the changed field; present once the negative resolved.", "properties": {"state": {"type": ["string", "null"], "description": "State before the update (upper-cased)."}}}, "after": {"type": "object", "description": "Requested value of the changed field.", "properties": {"state": {"type": "string", "description": "New state: ENABLED, PAUSED or ARCHIVED (ARCHIVED deletes at Amazon)."}}}, "changed": {"type": "array", "description": "Names of the fields present in the update item (always state).", "items": {"type": "string"}}, "violations": {"type": "array", "description": "Policy checks that failed for this item; present on blocked / would_pass rows.", "items": {"type": "object", "description": "One violated PolicyService check.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "description": "Always violated here."}, "message": {"type": "string", "description": "Human-readable reason."}}}}, "note": {"type": "string", "description": "Backend side-effect note carried onto an updated row, when the backend returns one."}}, "required": ["negative_id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the succeeded (or queued) items; null when nothing was written or queued."}, "policy_checks": {"type": "array", "description": "Policy evaluations (all checks on success; only violations on policy_violation / pending_approval).", "items": {"type": "object", "description": "One PolicyService check annotated with the item it applies to.", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy document the rule came from."}, "scope": {"type": "string", "description": "Scope label: baseline, workspace, or level:id."}, "category": {"type": "string", "description": "Policy rule category."}, "rule": {"type": "string", "description": "Rule name."}, "result": {"type": "string", "enum": ["passed", "violated"], "description": "Check outcome."}, "message": {"type": "string", "description": "Human-readable evaluation message."}, "negative_id": {"type": ["string", "null"], "description": "Negative the check was evaluated for."}, "field": {"type": "string", "description": "Field the check was evaluated for (state)."}}}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Deep link to MCP Admin Policies; present only on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles that can edit policies; present only on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_advertised_product_performance": {"post": {"operationId": "get_advertised_product_performance", "tags": ["Products & Reports"], "summary": "Get Advertised Product Performance", "description": "Tool name: `get_advertised_product_performance` \u00b7 **Scope:** requires `tools:read`.\n\nAds-only metrics per advertised ASIN over a date range (only products that received ad impressions). Returns `cost` (ad spend), `attributedSales14d` (ad sales), impressions, clicks, and derived ACOS/ROAS/CTR/CPC/CVR. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["adAsin", "adProductName", "campaignName", "campaignId", "adGroupName", "adGroupId", "reportType", "tags", "week", "month", "year"]}, "description": "Dimensions to group results by. Defaults to ['adAsin', 'adProductName']. Use time fields (week, month) for trend analysis. reportType maps to ad type: spAdvertisedDaily=Sponsored Products, sbAdvertisedDaily=Sponsored Brands, sdAdvertisedDaily=Sponsored Display."}, "ad_asin": {"type": "string", "description": "Filter to a specific ASIN."}, "ad_product_name": {"type": "string", "description": "Filter by product name \u2014 case-insensitive PARTIAL match."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific campaigns by ID."}, "ad_group_ids": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific ad groups by ID."}, "report_type": {"type": "array", "items": {"type": "string", "enum": ["spAdvertisedDaily", "sbAdvertisedDaily", "sdAdvertisedDaily"]}, "description": "Filter by ad type. spAdvertisedDaily=Sponsored Products, sbAdvertisedDaily=Sponsored Brands, sdAdvertisedDaily=Sponsored Display."}, "sort_field": {"type": "string", "enum": ["cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "ctr", "cpc", "cvr"], "description": "Field to sort results by. Defaults to 'cost'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "tag_values": {"type": "array", "items": {"type": "string"}, "description": "Optional legacy tag labels. For campaigns, only ENABLED campaigns with an active tag assignment are included unless status or a named campaign is specified."}, "group_by_tag": {"type": "boolean", "description": "When true, results are one row per tag (rollup metrics by tag). Each row includes tagValue. include_tags is ignored when true."}, "include_tags": {"type": "boolean", "description": "When true (and group_by_tag is false), each row includes tags loaded from MarketingData after metrics (legacy tag assignments: value, color, bgColor, tagEntityId)."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of ads-only advertised-product (ASIN) performance rows, with a summary over the FULL result set and pagination metadata.", "properties": {"data": {"type": "array", "description": "Rows for the requested page, sorted by sort_field/sort_direction.", "items": {"type": "object", "description": "One grouped row; which dimension keys appear depends on group_by (default adAsin + adProductName). Metric keys are always present.", "properties": {"adAsin": {"type": "string", "description": "Advertised ASIN (present when grouped by adAsin)."}, "adProductName": {"type": "string", "description": "Advertised product name (present when grouped by adProductName)."}, "campaignName": {"type": "string", "description": "Campaign name (present when grouped by campaignName)."}, "campaignId": {"type": "string", "description": "Campaign id (present when grouped by campaignId)."}, "adGroupName": {"type": "string", "description": "Ad group name (present when grouped by adGroupName)."}, "adGroupId": {"type": "string", "description": "Ad group id (present when grouped by adGroupId)."}, "reportType": {"type": "string", "description": "Ad type: spAdvertisedDaily, sbAdvertisedDaily or sdAdvertisedDaily (when grouped by reportType)."}, "tagValue": {"type": "string", "description": "Tag label for the row (present when group_by_tag=true)."}, "week": {"type": ["string", "number"], "description": "Week bucket (present when grouped by week)."}, "month": {"type": ["string", "number"], "description": "Month bucket (present when grouped by month)."}, "year": {"type": ["string", "number"], "description": "Year bucket (present when grouped by year)."}, "spend": {"type": "number", "description": "Ad spend (cost), rounded to 2 decimals."}, "sales": {"type": "number", "description": "14-day attributed ad sales, rounded to 2 decimals."}, "impressions": {"type": "integer", "description": "Ad impressions."}, "clicks": {"type": "integer", "description": "Ad clicks."}, "orders": {"type": "integer", "description": "Attributed purchases (orders)."}, "acos": {"type": ["number", "null"], "description": "ACOS percent; null when the denominator is zero."}, "roas": {"type": ["number", "null"], "description": "ROAS; null when the denominator is zero."}, "ctr": {"type": ["number", "null"], "description": "Click-through rate; null when the denominator is zero."}, "cpc": {"type": ["number", "null"], "description": "Cost per click; null when the denominator is zero."}, "cvr": {"type": ["number", "null"], "description": "Conversion rate; null when the denominator is zero."}, "tags": {"type": "array", "description": "Active legacy tag assignments for the ASIN; present only when include_tags=true (and group_by_tag is false).", "items": {"type": "object", "description": "One legacy tag assignment.", "properties": {"_id": {"type": "string", "description": "Tag id."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Tag text colour."}, "bgColor": {"type": "string", "description": "Tag background colour."}, "tagEntityId": {"type": "string", "description": "Id of the tag-to-entity assignment document."}}, "required": ["_id", "value", "color", "bgColor", "tagEntityId"]}}}, "required": ["spend", "sales", "impressions", "clicks", "orders", "acos", "roas", "ctr", "cpc", "cvr"]}}, "summary": {"type": "object", "description": "Totals over the FULL result set (not just this page); explicit zeros when empty.", "properties": {"totalSpend": {"type": "number", "description": "Sum of spend."}, "totalSales": {"type": "number", "description": "Sum of attributed sales."}, "totalImpressions": {"type": "integer", "description": "Sum of impressions."}, "totalClicks": {"type": "integer", "description": "Sum of clicks."}, "totalOrders": {"type": "integer", "description": "Sum of orders."}, "overallAcos": {"type": "number", "description": "totalSpend / totalSales * 100; 0 when no sales."}, "overallRoas": {"type": "number", "description": "totalSales / totalSpend; 0 when no spend."}}, "required": ["totalSpend", "totalSales", "totalImpressions", "totalClicks", "totalOrders", "overallAcos", "overallRoas"]}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL set size.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total rows in the full result set."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 cursor for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["data", "summary", "dateRange", "pagination", "total", "account", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_fba_customer_returns": {"post": {"operationId": "get_fba_customer_returns", "tags": ["Products & Reports"], "summary": "Get FBA Customer Returns", "description": "Tool name: `get_fba_customer_returns` \u00b7 **Scope:** requires `tools:read`.\n\nFBA customer returns for a Seller Central account over a date range, per ASIN/SKU, with return reasons and dispositions.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"start_date": {"type": "string", "description": "Start date (inclusive) in YYYY-MM-DD format, filtered by returnDate."}, "end_date": {"type": "string", "description": "End date (inclusive) in YYYY-MM-DD format, filtered by returnDate."}, "page": {"type": "integer", "description": "0-indexed page of returns to return. Default 0."}, "page_size": {"type": "integer", "description": "Returns per page. Default 100, max 500. Check the response's pagination.hasMore/totalPages and increment page to fetch every return."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["start_date", "end_date", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of FBA customer return records for an Amazon account within a return-date range, with the full-set count and pagination.", "properties": {"order_returns": {"type": "array", "description": "Return records for this page, newest returnDate first.", "items": {"type": "object", "description": "One FbaCustomerReturnsReport document as stored by the SP-API FBA customer returns sync (_id and amazonAccountId are projected out). Only sku, asin and returnDate are verified from code; other stored fields pass through unchanged.", "properties": {"sku": {"type": ["string", "null"], "description": "Seller SKU of the returned item."}, "asin": {"type": ["string", "null"], "description": "ASIN of the returned item."}, "returnDate": {"type": "string", "description": "Return date/time, stringified datetime."}}}}, "total_count": {"type": "integer", "description": "Total returns in the full result set (not just this page)."}, "date_range": {"type": ["object", "null"], "description": "Date window applied, as ISO-8601 datetime strings.", "properties": {"start_date": {"type": "string", "description": "Window start, ISO-8601 datetime (midnight of start_date)."}, "end_date": {"type": "string", "description": "Window end, ISO-8601 datetime (midnight of end_date; the query covers the whole end day)."}}, "required": ["start_date", "end_date"]}, "pagination": {"type": "object", "description": "Page metadata from the shared paginate helper; total is the FULL set size.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total returns in the full result set."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 cursor for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}}, "required": ["order_returns", "total_count", "date_range", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_inventory": {"post": {"operationId": "get_inventory", "tags": ["Products & Reports"], "summary": "Get Inventory", "description": "Tool name: `get_inventory` \u00b7 **Scope:** requires `tools:read`.\n\nPer-ASIN stock: FBM quantity (`fbm.quantity`) and FBA warehouse balance (`fba.endingWarehouseBalance`, from the daily FBA Inventory Ledger). A null `fbm` or `fba` block means not applicable or no data, not zero (FBA SKUs have `fbm: null`). Amazon's fulfillable / inbound / reserved / unfulfillable figures are not available. Requires Seller Central. Uses `limit`/`offset`.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific ASINs."}, "view": {"type": "string", "enum": ["merged", "fbm", "fba", "fba_by_location"], "description": "merged (default; use for stock and days-of-cover): one row per ASIN with both FBM and FBA blocks. fbm: merchant-fulfilled rows only, excludes FBA stock (FBA SKUs get fbm: null). fba: FBA-only rows. fba_by_location: FBA-only rows broken out per Amazon fulfillment center (FC) \u2014 each ASIN carries a `fba.byLocation` array with the warehouse balance at each location, plus the rolled-up network total."}, "offset": {"type": "integer", "minimum": 0, "description": "Pagination offset. Defaults to 0."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "description": "Pagination limit. Defaults to 50. Hard cap at 200."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Per-ASIN inventory state (FBM listing quantity and/or FBA ledger warehouse balance) for one of four views, or a connect prompt when Seller Central is not connected.", "oneOf": [{"type": "object", "description": "Seller Central (SP-API) is not connected; empty item list with a connect URL.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "view": {"type": "string", "description": "Requested view: merged, fbm, fba or fba_by_location."}, "message": {"type": "string", "description": "Explanation that Seller Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Seller Central can be connected."}, "items": {"type": "array", "description": "Always empty.", "items": {"type": "object", "description": "Never populated."}}, "total": {"type": "integer", "description": "Always 0."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant."}}, "required": ["connected", "view", "message", "connectUrl", "items", "total", "account", "chatAssistantUrl"]}, {"type": "object", "description": "Seller Central connected; one item per ASIN (merged/fba/fba_by_location) or per listing (fbm).", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "view": {"type": "string", "description": "View used: merged, fbm, fba or fba_by_location."}, "items": {"type": "array", "description": "Inventory rows for this page (after optional asins filter).", "items": {"type": "object", "description": "One inventory row; which keys appear depends on view (see descriptions).", "properties": {"asin": {"type": "string", "description": "ASIN."}, "sku": {"type": "string", "description": "Seller SKU; empty string in merged and fba views (not carried by those service rows)."}, "itemName": {"type": "string", "description": "Item name; empty in fba view."}, "price": {"type": ["number", "string", "null"], "description": "Listing price as stored in SPActiveProductListing; null in fba view."}, "mainImageUrl": {"type": ["string", "null"], "description": "Main image URL or null."}, "fulfillmentChannel": {"type": ["string", "null"], "description": "fbm view only: DEFAULT or AMAZON_* for the listing."}, "fulfillmentChannels": {"type": "array", "description": "merged view only: distinct listing channels for the ASIN.", "items": {"type": "string", "description": "DEFAULT or AMAZON_*."}}, "fbm": {"type": ["object", "null"], "description": "Merchant-fulfilled stock; null when not applicable (FBA listing / FBA-only ASIN / fba views).", "properties": {"quantity": {"type": ["integer", "null"], "description": "FBM listing quantity; null when the listing has no quantity."}}, "required": ["quantity"]}, "fba": {"type": ["object", "null"], "description": "FBA ledger stock; null when no ledger snapshot exists (no data, not zero) or in the fbm view.", "properties": {"endingWarehouseBalance": {"type": "integer", "description": "On-hand units from the daily FBA Inventory Ledger (network total)."}, "fnskus": {"type": "array", "description": "FNSKUs rolled into this balance (when available).", "items": {"type": "string", "description": "FNSKU."}}, "asOfDate": {"type": "string", "description": "ISO-8601 datetime of the ledger snapshot used (when available)."}, "byLocation": {"type": "array", "description": "fba_by_location view only: per fulfillment-center breakdown.", "items": {"type": "object", "description": "One ledger row for one (ASIN, SKU, FC location).", "properties": {"location": {"type": ["string", "null"], "description": "Fulfillment center location code."}, "endingWarehouseBalance": {"type": "integer", "description": "On-hand units at this location."}, "fnsku": {"type": "string", "description": "FNSKU (when present)."}, "sku": {"type": "string", "description": "Seller SKU (when present)."}, "asOfDate": {"type": "string", "description": "ISO-8601 datetime of the ledger row (when present)."}}, "required": ["location", "endingWarehouseBalance"]}}}, "required": ["endingWarehouseBalance"]}, "note": {"type": "string", "description": "fbm view only, on FBA listings: points to the merged/fba views for stock."}}, "required": ["asin", "sku", "fbm", "fba"]}}, "total": {"type": "integer", "description": "Rows after the asins filter, before offset/limit."}, "offset": {"type": "integer", "description": "Effective pagination offset."}, "limit": {"type": "integer", "description": "Effective page limit (1-200)."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant."}, "note": {"type": "string", "description": "merged view only, when no FBA ledger snapshot exists for the last two days: fba is null, not zero."}}, "required": ["connected", "view", "items", "total", "offset", "limit", "account", "chatAssistantUrl"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_orders_report": {"post": {"operationId": "get_orders_report", "tags": ["Products & Reports"], "summary": "Get Orders Report", "description": "Tool name: `get_orders_report` \u00b7 **Scope:** requires `tools:read`.\n\nOrders for a date range: aggregate totals plus a breakdown by state; raw order rows only when `include_orders` is set.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format."}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format."}, "marketplace_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional marketplace IDs list."}, "include_orders": {"type": "boolean", "description": "If true, include the full raw per-order rows, paginated via page/page_size. Defaults to false \u2014 only aggregates are returned. Combine with state to drill into one state."}, "page": {"type": "integer", "description": "0-indexed page of orders to return when include_orders=true. Default 0."}, "page_size": {"type": "integer", "description": "Orders per page when include_orders=true. Default 100, max 500. Check the response's `pagination.hasMore`/`pagination.totalPages` and increment `page` to fetch every order."}, "top_states": {"type": "integer", "description": "Return only the top N state groups (by total value) in the aggregate SUMMARY breakdown; the remainder is summarized as a single 'otherStates' bucket. Does NOT limit the raw `orders` list (that covers every state, subject to `state` and pagination). Default 25, max 100."}, "state": {"type": "string", "description": "Optional case-insensitive state filter, applied to both the summary breakdown and the raw orders list. Matches state labels containing this value (e.g. 'maharashtra')."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Order totals for a date range with a by-state summary, plus (when include_orders=true) a paginated list of raw per-order rows.", "properties": {"totalCount": {"type": "integer", "description": "Total orders reported by the getOrders resolver (0 when it returned nothing)."}, "dateRange": {"type": "object", "description": "Date window the resolver applied (echoes the request when the resolver returned none).", "properties": {"createdAfter": {"type": "string", "description": "Window start date/time string."}, "createdBefore": {"type": "string", "description": "Window end date/time string."}}, "required": ["createdAfter", "createdBefore"]}, "summary": {"type": "object", "description": "Aggregates over every state group (after the optional state filter).", "properties": {"totalOrders": {"type": "integer", "description": "Sum of orders across state groups."}, "totalValue": {"type": "number", "description": "Sum of order value across state groups, 2 decimals."}, "currencyCode": {"type": ["string", "null"], "description": "Currency with the most orders; null when there are no groups."}, "uniqueStates": {"type": "integer", "description": "Number of state groups."}, "topStates": {"type": "array", "description": "Up to top_states groups ordered by totalValue desc.", "items": {"type": "object", "description": "Aggregate for one shipping state.", "properties": {"state": {"type": ["string", "null"], "description": "State label."}, "totalOrders": {"type": ["integer", "null"], "description": "Orders in this state."}, "totalValue": {"type": ["number", "null"], "description": "Order value in this state."}, "currencyCode": {"type": ["string", "null"], "description": "Currency of totalValue."}}, "required": ["state", "totalOrders", "totalValue", "currencyCode"]}}, "otherStates": {"type": ["object", "null"], "description": "Roll-up of groups beyond top_states; null when none.", "properties": {"states": {"type": "integer", "description": "Number of states rolled up."}, "totalOrders": {"type": "integer", "description": "Orders in the rolled-up states."}, "totalValue": {"type": "number", "description": "Order value in the rolled-up states."}}, "required": ["states", "totalOrders", "totalValue"]}}, "required": ["totalOrders", "totalValue", "currencyCode", "uniqueStates", "topStates", "otherStates"]}, "filters": {"type": "object", "description": "Echo of the request options; absent when the resolver returned no payload.", "properties": {"state": {"type": ["string", "null"], "description": "Lower-cased state substring filter, or null."}, "marketplaceIds": {"type": ["array", "null"], "description": "Marketplace ids filter, or null.", "items": {"type": "string", "description": "Marketplace id."}}, "includeOrders": {"type": "boolean", "description": "Whether raw orders were requested."}, "topStates": {"type": "integer", "description": "Effective top_states (1-100)."}}, "required": ["state", "marketplaceIds", "includeOrders", "topStates"]}, "orders": {"type": "array", "description": "Present only when include_orders=true: one page of orders across ALL states, newest purchaseDate first. Empty/null fields are stripped from each row.", "items": {"type": "object", "description": "One order as stored in the synced orders report; every key is optional because empty values are removed.", "properties": {"state": {"type": "string", "description": "Shipping state label of the group the order came from."}, "amazonOrderId": {"type": "string", "description": "Amazon order id."}, "sellerOrderId": {"type": "string", "description": "Seller order id."}, "purchaseDate": {"type": "string", "description": "Purchase date/time string."}, "lastUpdateDate": {"type": "string", "description": "Last update date/time string."}, "orderStatus": {"type": "string", "description": "Amazon order status."}, "fulfillmentChannel": {"type": "string", "description": "Fulfillment channel."}, "salesChannel": {"type": "string", "description": "Sales channel."}, "orderChannel": {"type": "string", "description": "Order channel."}, "shipServiceLevel": {"type": "string", "description": "Ship service level."}, "orderTotal": {"type": "object", "description": "Order total money value.", "properties": {"currencyCode": {"type": "string", "description": "Currency code."}, "amount": {"type": "string", "description": "Amount as a string."}}}, "numberOfItemsShipped": {"type": "integer", "description": "Items shipped."}, "numberOfItemsUnshipped": {"type": "integer", "description": "Items not yet shipped."}, "paymentMethod": {"type": "string", "description": "Payment method."}, "marketplaceId": {"type": "string", "description": "Marketplace id."}, "shipmentServiceLevelCategory": {"type": "string", "description": "Shipment service level category."}, "easyShipShipmentStatus": {"type": "string", "description": "Easy Ship shipment status."}, "cbaDisplayableShippingLabel": {"type": "string", "description": "CBA displayable shipping label."}, "orderType": {"type": "string", "description": "Order type."}, "earliestShipDate": {"type": "string", "description": "Earliest ship date string."}, "latestShipDate": {"type": "string", "description": "Latest ship date string."}, "earliestDeliveryDate": {"type": "string", "description": "Earliest delivery date string."}, "latestDeliveryDate": {"type": "string", "description": "Latest delivery date string."}, "isBusinessOrder": {"type": "boolean", "description": "Business order flag."}, "isPrime": {"type": "boolean", "description": "Prime order flag."}, "isPremiumOrder": {"type": "boolean", "description": "Premium order flag."}, "isGlobalExpressEnabled": {"type": "boolean", "description": "Global Express flag."}, "replacedOrderId": {"type": "string", "description": "Id of the order this one replaces."}, "isReplacementOrder": {"type": "boolean", "description": "Replacement order flag."}, "promiseResponseDeadline": {"type": "string", "description": "Promise response deadline string."}, "isEstimatedShipDateSet": {"type": "boolean", "description": "Estimated ship date set flag."}, "isSoldByAb": {"type": "boolean", "description": "Sold by Amazon Business flag."}, "isIba": {"type": "boolean", "description": "IBA flag."}, "defaultShipFromLocationAddress": {"type": "object", "description": "Order address (OrderAddressType); empty fields are stripped.", "properties": {"name": {"type": "string", "description": "Recipient name."}, "addressLine1": {"type": "string", "description": "Address line 1."}, "addressLine2": {"type": "string", "description": "Address line 2."}, "addressLine3": {"type": "string", "description": "Address line 3."}, "city": {"type": "string", "description": "City."}, "county": {"type": "string", "description": "County."}, "district": {"type": "string", "description": "District."}, "stateOrRegion": {"type": "string", "description": "State or region."}, "municipality": {"type": "string", "description": "Municipality."}, "postalCode": {"type": "string", "description": "Postal code."}, "countryCode": {"type": "string", "description": "Country code."}, "phone": {"type": "string", "description": "Phone number."}, "addressType": {"type": "string", "description": "Address type."}}}, "buyerInvoicePreference": {"type": "string", "description": "Buyer invoice preference."}, "isIspu": {"type": "boolean", "description": "In-store pickup flag."}, "sellerDisplayName": {"type": "string", "description": "Seller display name."}, "shippingAddress": {"type": "object", "description": "Order address (OrderAddressType); empty fields are stripped.", "properties": {"name": {"type": "string", "description": "Recipient name."}, "addressLine1": {"type": "string", "description": "Address line 1."}, "addressLine2": {"type": "string", "description": "Address line 2."}, "addressLine3": {"type": "string", "description": "Address line 3."}, "city": {"type": "string", "description": "City."}, "county": {"type": "string", "description": "County."}, "district": {"type": "string", "description": "District."}, "stateOrRegion": {"type": "string", "description": "State or region."}, "municipality": {"type": "string", "description": "Municipality."}, "postalCode": {"type": "string", "description": "Postal code."}, "countryCode": {"type": "string", "description": "Country code."}, "phone": {"type": "string", "description": "Phone number."}, "addressType": {"type": "string", "description": "Address type."}}}, "hasRegulatedItems": {"type": "boolean", "description": "Regulated items flag."}}}}, "pagination": {"type": "object", "description": "Present only when include_orders=true; page metadata over the full flattened order list.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total orders in the full list."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 cursor for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}}, "required": ["totalCount", "dateRange", "summary"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_retail_product_performance": {"post": {"operationId": "get_retail_product_performance", "tags": ["Products & Reports"], "summary": "Get Retail Product Performance", "description": "Tool name: `get_retail_product_performance` \u00b7 **Scope:** requires `tools:read`.\n\nCombined retail + ads metrics per ASIN \u2014 total revenue, sessions, page views, buy-box %, TACoS, organic vs ads split. Requires a Seller Central (SP-API) connection; supports child/parent ASIN rollup.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format"}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format"}, "listing_type": {"type": "string", "enum": ["child_asin", "parent_asin"], "description": "Product listing level. 'child_asin' (default) shows individual product variations. 'parent_asin' shows parent-level rollup across all variations."}, "asin": {"type": "string", "description": "Filter to a specific ASIN."}, "item_name": {"type": "string", "description": "Filter by product name."}, "sort_field": {"type": "string", "enum": ["totalSales", "pageViews", "sessions", "unitsOrdered", "buyBoxPercentage", "cost", "attributedSales14d", "impressions", "clicks", "purchases", "acos", "roas", "tacos"], "description": "Field to sort results by. Defaults to 'totalSales'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Combined retail (Seller Central) and advertising metrics per ASIN over a date range, or a connect prompt when Seller Central is not connected.", "oneOf": [{"type": "object", "description": "Seller Central (SP-API) is not connected for this account; no data is returned.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "message": {"type": "string", "description": "Human-readable explanation that Seller Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Seller Central can be connected."}, "account": {"type": "object", "description": "The Amazon account the call was scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "message", "connectUrl", "account"]}, {"type": "object", "description": "Seller Central is connected; per-ASIN rows plus a summary.", "properties": {"connected": {"type": "boolean", "description": "Always true in this branch."}, "data": {"type": "array", "description": "One row per ASIN (child or parent per listing_type).", "items": {"type": "object", "description": "Retail + advertising metrics for one ASIN; N/A values are coerced to 0.", "properties": {"asin": {"type": "string", "description": "ASIN."}, "productName": {"type": "string", "description": "Item name from the product listing join."}, "pageViews": {"type": "integer", "description": "Retail page views."}, "sessions": {"type": "integer", "description": "Retail sessions."}, "totalSales": {"type": "number", "description": "Retail ordered product sales."}, "unitsOrdered": {"type": "integer", "description": "Retail units ordered."}, "totalOrderItems": {"type": "integer", "description": "Retail total order items."}, "buyBoxPercentage": {"type": "number", "description": "Buy box percentage as returned by the query service."}, "averageSellingPrice": {"type": "number", "description": "Average selling price (asp)."}, "adSpend": {"type": "number", "description": "Ad cost."}, "adSales": {"type": "number", "description": "14-day attributed ad sales."}, "adImpressions": {"type": "integer", "description": "Ad impressions."}, "adClicks": {"type": "integer", "description": "Ad clicks."}, "adOrders": {"type": "integer", "description": "Ad-attributed purchases."}, "acos": {"type": "number", "description": "ACOS percent."}, "roas": {"type": "number", "description": "ROAS."}, "adCtr": {"type": "number", "description": "Ad click-through rate."}, "adCpc": {"type": "number", "description": "Ad cost per click."}, "adCvr": {"type": "number", "description": "Ad conversion rate."}, "tacos": {"type": "number", "description": "Total ACOS (ad spend / total sales) percent."}, "adSalesPercentage": {"type": "number", "description": "Ad sales as a percentage of total sales."}, "adSpendPerUnit": {"type": "number", "description": "Ad spend per unit ordered."}}, "required": ["asin", "productName", "pageViews", "sessions", "totalSales", "unitsOrdered", "totalOrderItems", "buyBoxPercentage", "averageSellingPrice", "adSpend", "adSales", "adImpressions", "adClicks", "adOrders", "acos", "roas", "adCtr", "adCpc", "adCvr", "tacos", "adSalesPercentage", "adSpendPerUnit"]}}, "summary": {"type": "object", "description": "Totals over all returned rows; an EMPTY object when the query returned no rows.", "properties": {"totalPageViews": {"type": "integer", "description": "Sum of page views."}, "totalSessions": {"type": "integer", "description": "Sum of sessions."}, "totalSales": {"type": "number", "description": "Sum of retail sales."}, "totalUnitsOrdered": {"type": "integer", "description": "Sum of units ordered."}, "totalOrderItems": {"type": "integer", "description": "Sum of order items."}, "totalAdSpend": {"type": "number", "description": "Sum of ad spend."}, "totalAdSales": {"type": "number", "description": "Sum of ad sales."}, "totalAdImpressions": {"type": "integer", "description": "Sum of ad impressions."}, "totalAdClicks": {"type": "integer", "description": "Sum of ad clicks."}, "totalAdOrders": {"type": "integer", "description": "Sum of ad orders."}, "overallTacos": {"type": "number", "description": "totalAdSpend / totalSales * 100; 0 when no sales."}, "overallAdSalesPercentage": {"type": "number", "description": "totalAdSales / totalSales * 100; 0 when no sales."}, "overallAcos": {"type": "number", "description": "totalAdSpend / totalAdSales * 100; 0 when no ad sales."}, "overallRoas": {"type": "number", "description": "totalAdSales / totalAdSpend; 0 when no ad spend."}}}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "listingType": {"type": "string", "description": "child_asin or parent_asin, as requested (default child_asin)."}, "total": {"type": "integer", "description": "Number of rows in data."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["connected", "data", "summary", "dateRange", "listingType", "total", "account", "chatAssistantUrl"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_scp_report": {"post": {"operationId": "get_scp_report", "tags": ["Products & Reports"], "summary": "Get SCP Report", "description": "Tool name: `get_scp_report` \u00b7 **Scope:** requires `tools:read`.\n\nAmazon Brand Analytics Search Catalog Performance \u2014 one row per ASIN per month (no search-query dimension), with nested impression / click / cart-add / purchase metrics (counts, rates, median prices, shipping-speed breakdowns, search-traffic sales) plus product title and image. Takes integer `month` + `year`; `asin` narrows to one product. Sorted by `impressionCount` by default (`sort_field` / `sort_direction`). Paginated (`page_size` 50, max 200).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "month": {"type": "integer", "description": "Calendar month (1-12)"}, "year": {"type": "integer", "description": "Four-digit year"}, "asin": {"type": "string", "description": "Optional ASIN filter (exact match)."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 50, max 200. Keep small \u2014 responses over ~1 MB can be rejected by the MCP client."}, "sort_field": {"type": "string", "description": "Field to sort by. Defaults to 'impressionCount'. Common alternatives: 'clickCount', 'cartAddCount', 'purchaseCount', 'clickRate', 'conversionRate', 'asin'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}}, "required": ["amazon_account_id", "month", "year"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of enriched monthly Search Catalog Performance rows (one per ASIN) for the requested month.", "properties": {"reports": {"type": "array", "description": "Rows shaped by SCPPipelineService (restructured metrics + productTitle/productImage join), serialized (datetime -> ISO-8601 string).", "items": {"type": "object", "description": "One SCP row.", "properties": {"basic": {"type": "object", "description": "Restructured SCP document for one ASIN.", "properties": {"id": {"type": ["string", "null"], "description": "Same as asin."}, "asin": {"type": ["string", "null"], "description": "ASIN."}, "amazonAccountId": {"type": ["string", "null"], "description": "Amazon account id, or null."}, "requestId": {"type": ["string", "null"], "description": "Report request id, or null."}, "startDate": {"type": ["string", "null"], "description": "Month start, ISO-8601 datetime."}, "endDate": {"type": ["string", "null"], "description": "Month end, ISO-8601 datetime."}, "syncDate": {"type": ["string", "null"], "description": "Sync time, ISO-8601 datetime."}, "createdAt": {"type": ["string", "null"], "description": "Creation time, ISO-8601 datetime."}, "productTitle": {"type": ["string", "null"], "description": "Item name joined from the product listing / catalog."}, "productImage": {"type": ["string", "null"], "description": "Main image URL joined from the product listing / catalog."}, "impressionData": {"type": "object", "description": "Impression metrics.", "properties": {"impressionCount": {"type": ["number", "null"], "description": "Impressions."}, "impressionMedianPrice": {"type": ["object", "null"], "description": "Money value; null when neither amount nor currency is stored.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}, "required": ["amount", "currencyCode"]}, "sameDayShippingImpressionCount": {"type": ["number", "null"], "description": "Same-day shipping impressions."}, "oneDayShippingImpressionCount": {"type": ["number", "null"], "description": "One-day shipping impressions."}, "twoDayShippingImpressionCount": {"type": ["number", "null"], "description": "Two-day shipping impressions."}}, "required": ["impressionCount", "impressionMedianPrice", "sameDayShippingImpressionCount", "oneDayShippingImpressionCount", "twoDayShippingImpressionCount"]}, "clickData": {"type": "object", "description": "Click metrics.", "properties": {"clickCount": {"type": ["number", "null"], "description": "Clicks."}, "clickRate": {"type": ["number", "null"], "description": "Click rate."}, "clickedMedianPrice": {"type": ["object", "null"], "description": "Money value; null when neither amount nor currency is stored.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}, "required": ["amount", "currencyCode"]}, "sameDayShippingClickCount": {"type": ["number", "null"], "description": "Same-day shipping clicks."}, "oneDayShippingClickCount": {"type": ["number", "null"], "description": "One-day shipping clicks."}, "twoDayShippingClickCount": {"type": ["number", "null"], "description": "Two-day shipping clicks."}}, "required": ["clickCount", "clickRate", "clickedMedianPrice", "sameDayShippingClickCount", "oneDayShippingClickCount", "twoDayShippingClickCount"]}, "cartAddData": {"type": "object", "description": "Cart-add metrics.", "properties": {"cartAddCount": {"type": ["number", "null"], "description": "Cart adds."}, "cartAddedMedianPrice": {"type": ["object", "null"], "description": "Money value; null when neither amount nor currency is stored.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}, "required": ["amount", "currencyCode"]}, "sameDayShippingCartAddCount": {"type": ["number", "null"], "description": "Same-day shipping cart adds."}, "oneDayShippingCartAddCount": {"type": ["number", "null"], "description": "One-day shipping cart adds."}, "twoDayShippingCartAddCount": {"type": ["number", "null"], "description": "Two-day shipping cart adds."}}, "required": ["cartAddCount", "cartAddedMedianPrice", "sameDayShippingCartAddCount", "oneDayShippingCartAddCount", "twoDayShippingCartAddCount"]}, "purchaseData": {"type": "object", "description": "Purchase metrics.", "properties": {"purchaseCount": {"type": ["number", "null"], "description": "Purchases."}, "searchTrafficSales": {"type": ["object", "null"], "description": "Money value; null when neither amount nor currency is stored.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}, "required": ["amount", "currencyCode"]}, "conversionRate": {"type": ["number", "null"], "description": "Conversion rate."}, "purchaseMedianPrice": {"type": ["object", "null"], "description": "Money value; null when neither amount nor currency is stored.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}, "required": ["amount", "currencyCode"]}, "sameDayShippingPurchaseCount": {"type": ["number", "null"], "description": "Same-day shipping purchases."}, "oneDayShippingPurchaseCount": {"type": ["number", "null"], "description": "One-day shipping purchases."}, "twoDayShippingPurchaseCount": {"type": ["number", "null"], "description": "Two-day shipping purchases."}}, "required": ["purchaseCount", "searchTrafficSales", "conversionRate", "purchaseMedianPrice", "sameDayShippingPurchaseCount", "oneDayShippingPurchaseCount", "twoDayShippingPurchaseCount"]}}, "required": ["id", "asin", "amazonAccountId", "requestId", "startDate", "endDate", "syncDate", "createdAt", "productTitle", "productImage", "impressionData", "clickData", "cartAddData", "purchaseData"]}, "group": {"type": "object", "description": "Group key for the row.", "properties": {"asin": {"type": ["string", "null"], "description": "ASIN."}}, "required": ["asin"]}}, "required": ["basic", "group"]}}, "returned": {"type": "integer", "description": "Number of rows in reports."}, "total": {"type": "integer", "description": "Unique ASINs matching the filter (0 if the count failed)."}, "month": {"type": "integer", "description": "Requested calendar month (1-12)."}, "year": {"type": "integer", "description": "Requested four-digit year."}, "pagination": {"type": "object", "description": "Simple page metadata.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "page_size": {"type": "integer", "description": "Effective page size (1-200)."}, "has_more": {"type": "boolean", "description": "Whether a further page exists."}, "next_page": {"type": ["integer", "null"], "description": "Next page number, or null on the last page."}}, "required": ["page", "page_size", "has_more", "next_page"]}, "sort": {"type": "object", "description": "Sort applied.", "properties": {"field": {"type": "string", "description": "Field sorted on (default impressionCount)."}, "direction": {"type": "string", "description": "asc or desc."}}, "required": ["field", "direction"]}, "filters": {"type": "object", "description": "Echo of the optional filters.", "properties": {"asin": {"type": ["string", "null"], "description": "Exact ASIN filter, or null."}}, "required": ["asin"]}}, "required": ["reports", "returned", "total", "month", "year", "pagination", "sort", "filters"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_sqp_report": {"post": {"operationId": "get_sqp_report", "tags": ["Products & Reports"], "summary": "Get SQP Report", "description": "Tool name: `get_sqp_report` \u00b7 **Scope:** requires `tools:read`.\n\nAmazon Search Query Performance \u2014 one row per (ASIN, query). Uses integer `month` + `year`, not a date range. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "month": {"type": "integer", "description": "Calendar month (1-12)"}, "year": {"type": "integer", "description": "Four-digit year"}, "asin": {"type": "string", "description": "Optional ASIN filter (exact match)."}, "search_query": {"type": "string", "description": "Optional search query filter (exact match)."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 50, max 200. Keep small \u2014 responses over ~1 MB can be rejected by the MCP client."}, "sort_field": {"type": "string", "description": "Field to sort by. Defaults to 'searchQueryData.searchQueryScore'. Common alternatives: 'searchQueryData.searchQueryVolume', 'asin'."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}}, "required": ["amazon_account_id", "month", "year"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of raw monthly Search Query Performance documents (one per ASIN x search query) for the requested month.", "properties": {"reports": {"type": "array", "description": "Raw SQPReportsMonthly documents for this page, serialized (ObjectId -> string, datetime -> ISO-8601 string).", "items": {"type": "object", "description": "One stored SQP document; fields are whatever the sync wrote (nested blocks shown as the GraphQL SQP type exposes them).", "properties": {"_id": {"type": "string", "description": "Document id."}, "amazonAccountId": {"type": "string", "description": "Amazon account id (when stored)."}, "sellerAccountId": {"type": "string", "description": "Seller (SP-API) account id (when stored)."}, "requestId": {"type": "string", "description": "Report request id (when stored)."}, "asin": {"type": "string", "description": "ASIN the row is about."}, "startDate": {"type": "string", "description": "Report period start, ISO-8601 datetime."}, "endDate": {"type": "string", "description": "Report period end, ISO-8601 datetime."}, "syncDate": {"type": "string", "description": "When the row was synced, ISO-8601 datetime (when stored)."}, "createdAt": {"type": "string", "description": "When the row was created, ISO-8601 datetime (when stored)."}, "searchQueryData": {"type": "object", "description": "Search query block.", "properties": {"searchQuery": {"type": "string", "description": "The search query text."}, "searchQueryScore": {"type": ["number", "null"], "description": "Amazon search query score (default sort key)."}, "searchQueryVolume": {"type": ["number", "null"], "description": "Search query volume."}}}, "impressionData": {"type": "object", "description": "Impression block.", "properties": {"totalQueryImpressionCount": {"type": ["number", "null"], "description": "Total impressions for the query."}, "asinImpressionCount": {"type": ["number", "null"], "description": "Impressions for this ASIN."}, "asinImpressionShare": {"type": ["number", "null"], "description": "ASIN impression share."}}}, "clickData": {"type": "object", "description": "Click block (counts, rate, share, median prices, shipping-speed counts).", "properties": {"totalClickCount": {"type": ["number", "null"], "description": "Total clicks for the query."}, "totalClickRate": {"type": ["number", "null"], "description": "Total click rate."}, "asinClickCount": {"type": ["number", "null"], "description": "Clicks for this ASIN."}, "asinClickShare": {"type": ["number", "null"], "description": "ASIN click share."}, "totalMedianClickPrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "asinMedianClickPrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "totalSameDayShippingClickCount": {"type": ["number", "null"], "description": "Same-day shipping clicks."}, "totalOneDayShippingClickCount": {"type": ["number", "null"], "description": "One-day shipping clicks."}, "totalTwoDayShippingClickCount": {"type": ["number", "null"], "description": "Two-day shipping clicks."}}}, "cartAddData": {"type": "object", "description": "Cart-add block (same layout as clickData with cart-add names).", "properties": {"totalCartAddCount": {"type": ["number", "null"], "description": "Total cart adds for the query."}, "totalCartAddRate": {"type": ["number", "null"], "description": "Total cart-add rate."}, "asinCartAddCount": {"type": ["number", "null"], "description": "Cart adds for this ASIN."}, "asinCartAddShare": {"type": ["number", "null"], "description": "ASIN cart-add share."}, "totalMedianCartAddPrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "asinMedianCartAddPrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "totalSameDayShippingCartAddCount": {"type": ["number", "null"], "description": "Same-day shipping cart adds."}, "totalOneDayShippingCartAddCount": {"type": ["number", "null"], "description": "One-day shipping cart adds."}, "totalTwoDayShippingCartAddCount": {"type": ["number", "null"], "description": "Two-day shipping cart adds."}}}, "purchaseData": {"type": "object", "description": "Purchase block (same layout as clickData with purchase names).", "properties": {"totalPurchaseCount": {"type": ["number", "null"], "description": "Total purchases for the query."}, "totalPurchaseRate": {"type": ["number", "null"], "description": "Total purchase rate."}, "asinPurchaseCount": {"type": ["number", "null"], "description": "Purchases for this ASIN."}, "asinPurchaseShare": {"type": ["number", "null"], "description": "ASIN purchase share."}, "totalMedianPurchasePrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "asinMedianPurchasePrice": {"type": ["object", "null"], "description": "Money value.", "properties": {"amount": {"type": ["number", "null"], "description": "Amount."}, "currencyCode": {"type": ["string", "null"], "description": "Currency code."}}}, "totalSameDayShippingPurchaseCount": {"type": ["number", "null"], "description": "Same-day shipping purchases."}, "totalOneDayShippingPurchaseCount": {"type": ["number", "null"], "description": "One-day shipping purchases."}, "totalTwoDayShippingPurchaseCount": {"type": ["number", "null"], "description": "Two-day shipping purchases."}}}}}}, "returned": {"type": "integer", "description": "Number of rows in reports."}, "total": {"type": "integer", "description": "Total matching documents for the month and filters."}, "month": {"type": "integer", "description": "Requested calendar month (1-12)."}, "year": {"type": "integer", "description": "Requested four-digit year."}, "pagination": {"type": "object", "description": "Simple page metadata.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "page_size": {"type": "integer", "description": "Effective page size (1-200)."}, "has_more": {"type": "boolean", "description": "Whether a further page exists."}, "next_page": {"type": ["integer", "null"], "description": "Next page number, or null on the last page."}}, "required": ["page", "page_size", "has_more", "next_page"]}, "sort": {"type": "object", "description": "Sort applied.", "properties": {"field": {"type": "string", "description": "Mongo field path sorted on (default searchQueryData.searchQueryScore)."}, "direction": {"type": "string", "description": "asc or desc."}}, "required": ["field", "direction"]}, "filters": {"type": "object", "description": "Echo of the optional filters.", "properties": {"asin": {"type": ["string", "null"], "description": "Exact ASIN filter, or null."}, "search_query": {"type": ["string", "null"], "description": "Exact search query filter, or null."}}, "required": ["asin", "search_query"]}}, "required": ["reports", "returned", "total", "month", "year", "pagination", "sort", "filters"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_product_catalog": {"post": {"operationId": "list_product_catalog", "tags": ["Products & Reports"], "summary": "List Product Catalog", "description": "Tool name: `list_product_catalog` \u00b7 **Scope:** requires `tools:read`.\n\nSeller product catalog (ASIN + SKU, name, image, price, fulfillment channel, status, FBM quantity). Optionally pass a date range to add retail and ad metrics per product. Requires Seller Central. Uses `limit`/`offset`.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific ASINs."}, "skus": {"type": "array", "items": {"type": "string"}, "description": "Filter to specific SKUs."}, "name_search": {"type": "string", "description": "Case-insensitive substring match against the item name."}, "fulfillment_channel": {"type": "string", "enum": ["FBA", "FBM", "ALL"], "description": "Filter by fulfillment. FBA = Amazon-fulfilled (channel starts with AMAZON_), FBM = merchant-fulfilled (channel = DEFAULT). Defaults to ALL."}, "include_suppressed": {"type": "boolean", "description": "When false (default), products whose status list includes 'SUPPRESSED' or 'INACTIVE' are filtered out."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format. Presence of this field switches the tool to Mode 2 (catalog + performance). end_date is required when start_date is set."}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format. Required iff start_date is set; must be on or after start_date."}, "include_retail_metrics": {"type": "boolean", "description": "Mode 2 only. Default true. When true, each row carries a `retail` block with sessions, pageViews, unitsOrdered, totalRevenue, conversionRate, buyBoxPercentage."}, "include_ads_metrics": {"type": "boolean", "description": "Mode 2 only. Default false. When true, each row carries an `ads` block with spend, attributedSales14d, ACOS, ROAS, orders, impressions, clicks."}, "unadvertised_only": {"type": "boolean", "description": "Mode 2 only. When true, only products with zero ad spend in the date range are returned \u2014 i.e. candidates for create_campaign. Forces include_ads_metrics=true."}, "min_total_revenue": {"type": "number", "description": "Mode 2 only. Filter to products whose retail revenue in the date range is >= this value."}, "max_acos": {"type": "number", "description": "Mode 2 only. Filter to products whose advertising ACOS in the date range is <= this value (percent, e.g. 30 for 30%). Skips products with no ad spend."}, "sort_by": {"type": "object", "description": "Sort key. Mode 1 defaults to itemName asc. Mode 2 defaults to totalRevenue desc.", "properties": {"field": {"type": "string", "enum": ["itemName", "price", "quantity", "totalRevenue", "unitsOrdered", "sessions", "pageViews", "conversionRate", "buyBoxPercentage", "spend", "attributedSales14d", "acos", "roas", "orders", "impressions", "clicks"]}, "direction": {"type": "string", "enum": ["asc", "desc"]}}, "required": ["field"]}, "offset": {"type": "integer", "minimum": 0, "description": "Pagination offset. Defaults to 0."}, "limit": {"type": "integer", "minimum": 1, "maximum": 200, "description": "Pagination limit. Defaults to 50. Hard cap at 200."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Seller product catalog (Mode 1) or catalog joined with retail/ad performance (Mode 2), or a connect prompt when Seller Central is not connected.", "oneOf": [{"type": "object", "description": "Seller Central (SP-API) is not connected; empty product list with a connect URL.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "mode": {"type": "string", "description": "catalog or performance, as detected from the arguments."}, "message": {"type": "string", "description": "Explanation that Seller Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Seller Central can be connected."}, "products": {"type": "array", "description": "Always empty.", "items": {"type": "object", "description": "Never populated."}}, "total": {"type": "integer", "description": "Always 0."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant."}}, "required": ["connected", "mode", "message", "connectUrl", "products", "total", "account", "chatAssistantUrl"]}, {"type": "object", "description": "Mode 1 (no start_date/end_date): catalog rows from SPActiveProductListing, paginated with offset/limit.", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "mode": {"type": "string", "description": "Always \"catalog\"."}, "products": {"type": "array", "description": "Catalog rows for this page.", "items": {"type": "object", "description": "One SPActiveProductListing document.", "properties": {"asin": {"type": "string", "description": "ASIN."}, "sku": {"type": "string", "description": "Seller SKU."}, "itemName": {"type": "string", "description": "Item name."}, "price": {"type": ["number", "string", "null"], "description": "Listing price as stored in SPActiveProductListing (see tool description)."}, "fulfillmentChannel": {"type": "string", "description": "DEFAULT (merchant-fulfilled) or AMAZON_* (FBA)."}, "status": {"type": "array", "description": "Listing status flags.", "items": {"type": "string", "description": "Status value."}}, "mainImageUrl": {"type": ["string", "null"], "description": "Main image URL or null."}, "quantity": {"type": ["integer", "null"], "description": "FBM listing quantity; null when absent."}, "marketplaceId": {"type": "string", "description": "Amazon marketplace id."}}, "required": ["asin", "sku", "itemName", "price", "fulfillmentChannel", "status", "mainImageUrl", "quantity", "marketplaceId"]}}, "total": {"type": "integer", "description": "Count of catalog documents matching the filters (before offset/limit)."}, "offset": {"type": "integer", "description": "Effective pagination offset."}, "limit": {"type": "integer", "description": "Effective page limit (1-200)."}, "sortBy": {"type": "object", "description": "Sort actually applied.", "properties": {"field": {"type": "string", "description": "Sort field used."}, "direction": {"type": "string", "description": "asc or desc."}}, "required": ["field", "direction"]}, "dateRange": {"type": "null", "description": "Always null in catalog mode."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant."}}, "required": ["connected", "mode", "products", "total", "offset", "limit", "sortBy", "dateRange", "account", "chatAssistantUrl"]}, {"type": "object", "description": "Mode 2 (start_date + end_date): sp_product performance rows enriched with catalog fields.", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "mode": {"type": "string", "description": "Always \"performance\"."}, "products": {"type": "array", "description": "Rows after post-filters, truncated to limit.", "items": {"type": "object", "description": "Catalog row (same keys as Mode 1; sku is the first listing for the ASIN) plus retail/ads metric blocks and isAdvertised.", "allOf": [{"type": "object", "description": "One SPActiveProductListing document.", "properties": {"asin": {"type": "string", "description": "ASIN."}, "sku": {"type": "string", "description": "Seller SKU."}, "itemName": {"type": "string", "description": "Item name."}, "price": {"type": ["number", "string", "null"], "description": "Listing price as stored in SPActiveProductListing (see tool description)."}, "fulfillmentChannel": {"type": "string", "description": "DEFAULT (merchant-fulfilled) or AMAZON_* (FBA)."}, "status": {"type": "array", "description": "Listing status flags.", "items": {"type": "string", "description": "Status value."}}, "mainImageUrl": {"type": ["string", "null"], "description": "Main image URL or null."}, "quantity": {"type": ["integer", "null"], "description": "FBM listing quantity; null when absent."}, "marketplaceId": {"type": "string", "description": "Amazon marketplace id."}}, "required": ["asin", "sku", "itemName", "price", "fulfillmentChannel", "status", "mainImageUrl", "quantity", "marketplaceId"]}], "properties": {"retail": {"type": ["object", "null"], "description": "Retail metrics; null when include_retail_metrics=false.", "properties": {"totalRevenue": {"type": "number", "description": "Retail ordered product sales."}, "unitsOrdered": {"type": "integer", "description": "Units ordered."}, "totalOrderItems": {"type": "integer", "description": "Total order items."}, "sessions": {"type": "integer", "description": "Sessions."}, "pageViews": {"type": "integer", "description": "Page views."}, "buyBoxPercentage": {"type": "number", "description": "Buy box percentage."}, "averageSellingPrice": {"type": "number", "description": "Average selling price (asp)."}}, "required": ["totalRevenue", "unitsOrdered", "totalOrderItems", "sessions", "pageViews", "buyBoxPercentage", "averageSellingPrice"]}, "ads": {"type": ["object", "null"], "description": "Ad metrics; null unless include_ads_metrics=true or unadvertised_only=true.", "properties": {"spend": {"type": "number", "description": "Ad cost."}, "attributedSales14d": {"type": "number", "description": "14-day attributed ad sales."}, "acos": {"type": "number", "description": "ACOS percent."}, "roas": {"type": "number", "description": "ROAS."}, "orders": {"type": "integer", "description": "Ad-attributed purchases."}, "impressions": {"type": "integer", "description": "Ad impressions."}, "clicks": {"type": "integer", "description": "Ad clicks."}, "ctr": {"type": "number", "description": "Click-through rate."}, "cpc": {"type": "number", "description": "Cost per click."}}, "required": ["spend", "attributedSales14d", "acos", "roas", "orders", "impressions", "clicks", "ctr", "cpc"]}, "isAdvertised": {"type": "boolean", "description": "True when ad spend in the range is greater than 0."}}, "required": ["retail", "ads", "isAdvertised"]}}, "summary": {"type": "object", "description": "Counts over the filtered set; revenue/ad totals cover the RETURNED page only.", "properties": {"totalProducts": {"type": "integer", "description": "Rows after filters, before limit."}, "unadvertisedCount": {"type": "integer", "description": "Returned rows with isAdvertised=false."}, "totalRevenue": {"type": "number", "description": "Sum of retail.totalRevenue over returned rows (when include_retail_metrics)."}, "totalUnitsOrdered": {"type": "integer", "description": "Sum of retail.unitsOrdered over returned rows (when include_retail_metrics)."}, "totalAdSpend": {"type": "number", "description": "Sum of ads.spend over returned rows (when ads metrics included)."}, "totalAdSales": {"type": "number", "description": "Sum of ads.attributedSales14d over returned rows (when ads metrics included)."}}, "required": ["totalProducts", "unadvertisedCount"]}, "total": {"type": "integer", "description": "Rows after filters, before limit (same as summary.totalProducts)."}, "offset": {"type": "integer", "description": "Effective pagination offset."}, "limit": {"type": "integer", "description": "Effective page limit (1-200)."}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "sortBy": {"type": "object", "description": "Sort actually applied.", "properties": {"field": {"type": "string", "description": "Sort field used."}, "direction": {"type": "string", "description": "asc or desc."}}, "required": ["field", "direction"]}, "filters": {"type": "object", "description": "Echo of the Mode 2 filter arguments.", "properties": {"unadvertisedOnly": {"type": "boolean", "description": "Whether only zero-spend products were returned."}, "minTotalRevenue": {"type": ["number", "null"], "description": "Minimum retail revenue filter, or null."}, "maxAcos": {"type": ["number", "null"], "description": "Maximum ACOS filter, or null."}, "includeRetailMetrics": {"type": "boolean", "description": "Whether retail blocks were included."}, "includeAdsMetrics": {"type": "boolean", "description": "Whether ads blocks were included."}}, "required": ["unadvertisedOnly", "minTotalRevenue", "maxAcos", "includeRetailMetrics", "includeAdsMetrics"]}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant."}}, "required": ["connected", "mode", "products", "summary", "total", "offset", "limit", "dateRange", "sortBy", "filters", "account", "chatAssistantUrl"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_product_ad": {"post": {"operationId": "update_product_ad", "tags": ["Products & Reports"], "summary": "Update Product Ad", "description": "Tool name: `update_product_ad` \u00b7 **Scope:** requires `tools:write`.\n\nSet the state of up to 50 product ads per call: each item needs `campaign_id`, `ad_group_id`, the `asin` (or `ad_id`) and `state` ENABLED / PAUSED / ARCHIVED. ARCHIVED removes the product ad and is permanent \u2014 PAUSED stops advertising a product reversibly.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "updates": {"type": "array", "minItems": 1, "maxItems": 50, "description": "Per-product-ad state changes.", "items": {"type": "object", "properties": {"campaign_id": {"type": "string", "description": "Amazon campaign ID (from list_campaigns)."}, "ad_group_id": {"type": "string", "description": "Amazon ad group ID the product ad is in."}, "asin": {"type": "string", "description": "Product ASIN identifying the ad (resolved to the ad id)."}, "ad_id": {"type": "string", "description": "Optional. Amazon ad id, used instead of asin if known."}, "state": {"type": "string", "enum": ["ENABLED", "PAUSED", "ARCHIVED"], "description": "Target state. ARCHIVED = permanent removal."}}, "required": ["campaign_id", "ad_group_id", "state"]}}, "_reasoning": {"type": "string", "description": "Briefly explain why. Stored for audit."}}, "required": ["amazon_account_id", "updates"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Batch result of product-ad state updates from the shared entity-update engine; `status` is success, partial_success, failed, policy_violation or pending_approval.", "properties": {"status": {"type": "string", "description": "success, partial_success, failed, policy_violation or pending_approval."}, "applied": {"type": "boolean", "description": "True when the backend was called and at least one item succeeded."}, "message": {"type": "string", "description": "Natural-language summary of the outcome."}, "summary": {"type": "object", "description": "Counts over results.", "properties": {"total": {"type": "integer", "description": "Number of result rows."}, "succeeded": {"type": "integer", "description": "Rows with status updated."}, "failed": {"type": "integer", "description": "Rows with status failed, blocked or not_found."}, "pending": {"type": "integer", "description": "Rows queued for approval (pending_approval only), else 0."}}, "required": ["total", "succeeded", "failed", "pending"]}, "results": {"type": "array", "description": "One row per update item; the id key is `id` because product ads resolve by composite key.", "items": {"type": "object", "properties": {"id": {"type": ["string", "null"], "description": "Amazon ad id when resolved, else the supplied ad_id or asin."}, "status": {"type": "string", "description": "updated, failed, not_found, blocked, would_pass or pending_approval."}, "error": {"type": "string", "description": "Failure reason; present on failed and not_found rows."}, "before": {"type": "object", "description": "Current values of the changed fields.", "properties": {"state": {"type": ["string", "null"], "description": "Previous product-ad state, upper-cased."}}}, "after": {"type": "object", "description": "Requested values.", "properties": {"state": {"type": "string", "description": "Requested state (ENABLED, PAUSED or ARCHIVED)."}}}, "changed": {"type": "array", "description": "Field names present in the item (state).", "items": {"type": "string"}}, "violations": {"type": "array", "description": "Policy violations for this item (policy_violation only).", "items": {"type": "object", "description": "Policy check object (see policy_checks items)."}}, "note": {"type": "string", "description": "Side-effect note from the backend, when any."}}, "required": ["id", "status"]}}, "rollback_token": {"type": ["string", "null"], "description": "Decision-log rollback token (uuid) covering succeeded items; null when nothing applied."}, "policy_checks": {"type": "array", "description": "Policy checks per item (violations only on policy_violation/pending_approval; empty on pre-flight failure).", "items": {"type": "object", "properties": {"policyId": {"type": ["string", "null"], "description": "Id of the policy that supplied the rule, or null."}, "scope": {"type": "string", "description": "Scope label where the rule was resolved."}, "category": {"type": "string", "description": "Policy category."}, "rule": {"type": "string", "description": "Rule name evaluated."}, "result": {"type": "string", "description": "passed or violated."}, "message": {"type": ["string", "null"], "description": "Evaluator message."}, "id": {"type": ["string", "null"], "description": "Product ad the check applies to (ad id / ad_id / asin)."}, "field": {"type": "string", "description": "Field the check applies to (state)."}}, "required": ["policyId", "scope", "category", "rule", "result", "message", "id", "field"]}}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate AI chat assistant for this workspace/account."}, "policyAdminUrl": {"type": "string", "description": "Link to the MCP Admin policies page; present on policy_violation."}, "policyAdminRoles": {"type": "array", "description": "Workspace roles allowed to edit policies; present on policy_violation.", "items": {"type": "string"}}}, "required": ["status", "applied", "message", "summary", "results", "rollback_token", "policy_checks", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_tag": {"post": {"operationId": "create_tag", "tags": ["Tags"], "summary": "Create Tag", "description": "Tool name: `create_tag` \u00b7 **Scope:** requires `tools:write`.\n\nCreate a tag label and assign it to entities of one `data_type` (campaign IDs, ASINs, target / keyword texts, or search terms). Pass `tag_value` + `entities`, or `assignments` for several labels in one call. An existing label is reused, not duplicated; `color` / `bg_color` apply to new labels only. Omit `tag_group` for legacy free-form tags (an entity may carry many). Pass `tag_group` (e.g. `Brand`) for grouped tags: a group is a column holding exactly one value per entity, so assigning a new value archives the entity's previous one; a missing group is created unless `create_tag_group_if_missing` is false.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "data_type": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "What the entities are: campaign (campaignId), product (ASIN), targeting (keyword/target text), or search_term."}, "tag_value": {"type": "string", "description": "The tag label, max 60 characters. Letters, numbers, spaces and _ - . @ # & ! + / , * $ ^ ( ) ~ = { } [ ] | only. Use with 'entities' for the common single-label case."}, "entities": {"type": "array", "items": {"type": "string"}, "description": "Entity ids to tag, matching data_type: campaignId for campaign, ASIN for product, the target/keyword text for targeting, the search term for search_term. ASINs are uppercased automatically."}, "assignments": {"type": "array", "description": "Batch form: apply several different labels in one call. Each item is {tag_value, entities, color?, bg_color?}. Use this INSTEAD of tag_value/entities, not alongside them.", "items": {"type": "object", "properties": {"tag_value": {"type": "string", "description": "The tag label."}, "entities": {"type": "array", "items": {"type": "string"}, "description": "Entity ids to give this label."}, "color": {"type": "string", "description": "Hex text color, e.g. '#FFFFFF'."}, "bg_color": {"type": "string", "description": "Hex background color, e.g. '#0037EB'."}}, "required": ["tag_value", "entities"]}}, "color": {"type": "string", "description": "Optional hex text color for a NEW tag label. Ignored when the label already exists. Auto-picked from the SellerMate palette when omitted."}, "bg_color": {"type": "string", "description": "Optional hex background color for a NEW tag label. Ignored when the label already exists. Auto-picked when omitted."}, "create_tag_group_if_missing": {"type": "boolean", "description": "When true (default) a tag_group title that does not exist yet is created for this data_type. Set false to fail instead."}, "tag_group": {"type": "string", "description": "NEW-tag group (column) title, e.g. 'Brand' or 'Product Line'. Omit for OLD/legacy tags. Within a group an entity holds exactly one value \u2014 assigning another value archives the previous one."}, "tag_group_id": {"type": "string", "description": "NEW-tag group id, if known. Alternative to tag_group; takes precedence when both are supplied."}}, "required": ["amazon_account_id", "data_type"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Outcome of assigning one or more tag labels to entities (legacy tags, or values inside a NEW-tag group), with one result row per entity/label pair.", "properties": {"status": {"type": "string", "enum": ["success", "no_change"], "description": "success when at least one new assignment was written; no_change when every pair was already tagged."}, "applied": {"type": "boolean", "description": "True when at least one assignment was created."}, "message": {"type": "string", "description": "Natural-language summary including already-tagged and archived-previous-value counts."}, "tagSystem": {"type": "string", "enum": ["old", "new"], "description": "old = legacy free-form tags; new = values inside a tag group (dimension)."}, "dataType": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "Entity type the assignments apply to."}, "tagGroup": {"type": ["object", "null"], "description": "The tag group (TAG dimension) written to; null for legacy tags.", "properties": {"tagGroupId": {"type": "string", "description": "custom_dimension_and_metric document id."}, "title": {"type": "string", "description": "Group title, e.g. Brand."}, "dataType": {"type": "string", "description": "Entity type the group belongs to."}, "state": {"type": "string", "description": "Group state (active)."}}, "required": ["tagGroupId", "title", "dataType", "state"]}, "tagGroupCreated": {"type": "boolean", "description": "True when the tag group was created by this call."}, "newTagLabels": {"type": "array", "description": "Labels whose tag definition was created by this call.", "items": {"type": "string"}}, "summary": {"type": "object", "description": "Counts over results.", "properties": {"total": {"type": "integer", "description": "Number of entity/label pairs processed."}, "tagged": {"type": "integer", "description": "New assignments created."}, "alreadyTagged": {"type": "integer", "description": "Pairs that already had an active assignment."}, "replaced": {"type": "integer", "description": "Previous values archived in the tag group (0 for legacy tags)."}}, "required": ["total", "tagged", "alreadyTagged", "replaced"]}, "results": {"type": "array", "description": "One row per entity/label pair.", "items": {"type": "object", "description": "Per-pair outcome.", "properties": {"entity": {"type": "string", "description": "Normalized entity id (campaignId / ASIN / target text / search term)."}, "tagValue": {"type": "string", "description": "Normalized tag label."}, "status": {"type": "string", "enum": ["tagged", "already_tagged"], "description": "Whether a new assignment was written."}, "tagEntityId": {"type": "string", "description": "Id of the (new or existing) tagsEntity assignment row."}, "tagId": {"type": "string", "description": "Tag definition id; present only on tagged rows."}}, "required": ["entity", "tagValue", "status", "tagEntityId"]}}, "rollback_token": {"type": ["string", "null"], "description": "UUID covering the new assignments; null when nothing was written."}, "account": {"type": "object", "description": "The Amazon account the tags belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "tagSystem", "dataType", "tagGroup", "tagGroupCreated", "newTagLabels", "summary", "results", "rollback_token", "account", "chatAssistantUrl"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/delete_tag": {"post": {"operationId": "delete_tag", "tags": ["Tags"], "summary": "Delete Tag", "description": "Tool name: `delete_tag` \u00b7 **Scope:** requires `tools:write`.\n\nSoft-delete (archive) tags; nothing is destroyed. `scope: \"assignment\"` (default) untags the given `entities` (or `tag_entity_ids`) but keeps the label; `\"tag\"` archives a label and every assignment of it; `\"tag_group\"` archives a whole group and its values while the underlying labels survive. Archived rows disappear from `get_tags` and tag filters.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "scope": {"type": "string", "enum": ["assignment", "tag", "tag_group"], "description": "'assignment' (default) untags specific entities; 'tag' archives a tag label everywhere; 'tag_group' archives a NEW-tag group."}, "data_type": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "Entity type. Required for scope='assignment' when identifying entities, and for scope='tag_group' when identifying the group by title. Optional for scope='tag' to limit the removal to one entity type."}, "tag_id": {"type": "string", "description": "The tag id from get_tags."}, "tag_value": {"type": "string", "description": "The tag's label, if tag_id is unknown."}, "entities": {"type": "array", "items": {"type": "string"}, "description": "scope='assignment': entity ids to untag (campaignId / ASIN / target text / search term). Combine with tag_id or tag_value."}, "tag_entity_ids": {"type": "array", "items": {"type": "string"}, "description": "scope='assignment': archive these tag assignments directly by their tagEntityId from get_tags. Use instead of tag_value + entities when you already have the ids."}, "tag_group": {"type": "string", "description": "NEW-tag group (column) title, e.g. 'Brand' or 'Product Line'. Omit for OLD/legacy tags. Within a group an entity holds exactly one value \u2014 assigning another value archives the previous one."}, "tag_group_id": {"type": "string", "description": "NEW-tag group id, if known. Alternative to tag_group; takes precedence when both are supplied."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"description": "Outcome of a soft-delete (archive) of tag assignments, a whole tag label, or a whole NEW-tag group; the shape depends on the request's scope.", "oneOf": [{"type": "object", "description": "scope='assignment': specific tag assignments were archived (or none matched, status no_change).", "properties": {"status": {"type": "string", "enum": ["success", "no_change"], "description": "success when at least one assignment was archived."}, "applied": {"type": "boolean", "description": "True when at least one tagsEntity row was archived."}, "message": {"type": "string", "description": "Natural-language summary of what was archived."}, "scope": {"type": "string", "enum": ["assignment"], "description": "Always assignment on this branch."}, "summary": {"type": "object", "description": "Counts.", "properties": {"archivedAssignments": {"type": "integer", "description": "Number of tagsEntity rows set to archived."}}, "required": ["archivedAssignments"]}, "archivedTagEntityIds": {"type": "array", "description": "Ids of the archived tagsEntity rows; present only on success.", "items": {"type": "string"}}, "rollback_token": {"type": "string", "description": "UUID for the recorded diffs; present only on success."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "scope", "summary", "chatAssistantUrl"]}, {"type": "object", "description": "scope='tag': every assignment of a tag label was archived, and the label itself unless data_type was given.", "properties": {"status": {"type": "string", "enum": ["success"], "description": "Always success on this branch (failures raise errors)."}, "applied": {"type": "boolean", "description": "Always true on this branch."}, "message": {"type": "string", "description": "Natural-language summary stating whether the label was archived too."}, "scope": {"type": "string", "enum": ["tag"], "description": "Always tag on this branch."}, "tag": {"type": "object", "description": "The tag label that was targeted.", "properties": {"tagId": {"type": "string", "description": "Tag definition id."}, "value": {"type": "string", "description": "Tag label."}}, "required": ["tagId", "value"]}, "summary": {"type": "object", "description": "Counts and whether the label was archived.", "properties": {"archivedAssignments": {"type": "integer", "description": "Number of tagsEntity rows set to archived."}, "labelArchived": {"type": "boolean", "description": "True when the tags document was archived (no data_type given)."}}, "required": ["archivedAssignments", "labelArchived"]}, "rollback_token": {"type": "string", "description": "UUID for the recorded diff."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "scope", "tag", "summary", "rollback_token", "chatAssistantUrl"]}, {"type": "object", "description": "scope='tag_group': a NEW-tag group and every value inside it were archived; tag labels survive.", "properties": {"status": {"type": "string", "enum": ["success"], "description": "Always success on this branch (failures raise errors)."}, "applied": {"type": "boolean", "description": "Always true on this branch."}, "message": {"type": "string", "description": "Natural-language summary of the archive."}, "scope": {"type": "string", "enum": ["tag_group"], "description": "Always tag_group on this branch."}, "tagSystem": {"type": "string", "enum": ["new"], "description": "Tag groups exist only in the new tag system."}, "tagGroup": {"type": ["object", "null"], "description": "The archived group (serialize_tag_group of the service result).", "properties": {"tagGroupId": {"type": "string", "description": "custom_dimension_and_metric document id."}, "title": {"type": "string", "description": "Group title."}, "dataType": {"type": "string", "description": "Entity type the group belongs to."}, "state": {"type": "string", "description": "Group state after the call (archived)."}}, "required": ["tagGroupId", "title", "dataType", "state"]}, "summary": {"type": "object", "description": "Counts.", "properties": {"archivedAssignments": {"type": "integer", "description": "Number of tagsEntity rows in the group set to archived."}}, "required": ["archivedAssignments"]}, "rollback_token": {"type": "string", "description": "UUID for the recorded diff."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "scope", "tagSystem", "tagGroup", "summary", "rollback_token", "chatAssistantUrl"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_tags": {"post": {"operationId": "get_tags", "tags": ["Tags"], "summary": "Get Tags", "description": "Tool name: `get_tags` \u00b7 **Scope:** requires `tools:read`.\n\nTag inventory for one entity type (campaign / product / targeting / search_term): labels, colors, assigned entities (`tagEntityId`), optional per-tag metrics. Lists legacy free-form tags only \u2014 tag groups and their values are not included.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "data_type": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "Entity type tags apply to: campaign, product (ASIN), targeting (keyword/target), or search_term."}, "include_entities": {"type": "boolean", "description": "When true (default), each tag includes the list of assigned entity ids (campaignId, ASIN, targetingValue, or searchTerm depending on data_type)."}, "include_metrics": {"type": "boolean", "description": "When true, include aggregated ads metrics per tag for the date range. Requires start_date and end_date. Campaign metrics match getCampaignTags; other types use report rollups by tag."}, "start_date": {"type": "string", "description": "Start date YYYY-MM-DD (required if include_metrics is true)"}, "end_date": {"type": "string", "description": "End date YYYY-MM-DD (required if include_metrics is true)"}, "tag_labels": {"type": "array", "items": {"type": "string"}, "description": "Optional: only return tags whose value matches one of these labels."}}, "required": ["amazon_account_id", "data_type"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Active legacy (old-system) tags for one entity type, each with its assigned entities and, optionally, aggregated ads metrics for a date range.", "properties": {"dataType": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "The entity type the tags apply to (normalized from the request)."}, "tags": {"type": "array", "description": "One entry per active tag definition, sorted by label (tag_helpers.list_legacy_tags_grouped).", "items": {"type": "object", "description": "One legacy tag with its assignments.", "properties": {"tagId": {"type": "string", "description": "Tag definition id; use as tag_id in update_tag / delete_tag."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Hex text color."}, "bgColor": {"type": "string", "description": "Hex background color."}, "entityCount": {"type": "integer", "description": "Number of active assignments (for campaign: ENABLED campaigns only)."}, "entities": {"type": "array", "description": "Assigned entities; present only when include_entities is true (default).", "items": {"type": "object", "description": "One tag assignment.", "properties": {"entity": {"type": "string", "description": "campaignId, ASIN (upper-cased), targetingValue or searchTerm per dataType."}, "tagEntityId": {"type": "string", "description": "Id of the tagsEntity row; use in delete_tag tag_entity_ids."}}, "required": ["entity", "tagEntityId"]}}, "metrics": {"type": ["object", "null"], "description": "Aggregated ads metrics for the tag; present only when include_metrics=true (null when no report rows).", "properties": {"performanceMetrics": {"type": "object", "description": "Raw summed metrics; key set differs by dataType (campaign keys listed first).", "properties": {"cost": {"type": ["number", "null"], "description": "Ad spend."}, "spend": {"type": "number", "description": "Spend column sum (campaign only)."}, "clicks": {"type": ["number", "null"], "description": "Clicks."}, "impressions": {"type": ["number", "null"], "description": "Impressions."}, "attributed_sales_14d": {"type": ["number", "null"], "description": "Attributed sales 14d."}, "purchases": {"type": ["number", "null"], "description": "Purchases (orders)."}, "attributed_conversions_14d": {"type": "number", "description": "Attributed conversions 14d (campaign only)."}}}, "derivedMetrics": {"type": "object", "description": "Ratios; campaign values may carry the 1e9 divide-by-zero sentinel, other types may be null.", "properties": {"acos": {"type": ["number", "null"], "description": "cost / attributed_sales_14d."}, "roas": {"type": ["number", "null"], "description": "attributed_sales_14d / cost."}, "ctr": {"type": ["number", "null"], "description": "clicks / impressions."}, "cpc": {"type": ["number", "null"], "description": "cost / clicks."}, "cvr": {"type": ["number", "null"], "description": "purchases / clicks."}, "profit": {"type": "number", "description": "attributed_sales_14d - cost (campaign only)."}, "topOfSearchImpressionShare": {"type": "number", "description": "Average top-of-search impression share (campaign only)."}, "cpm": {"type": "number", "description": "cost / impressions * 1000 (campaign only)."}, "cpo": {"type": "number", "description": "clicks / purchases (campaign only)."}, "cpa": {"type": "number", "description": "cost / purchases (campaign only)."}, "adsAOV": {"type": "number", "description": "attributed_sales_14d / purchases (campaign only)."}}}}}, "campaigns": {"type": "array", "description": "CampaignData docs for the tag's ENABLED campaigns; present only for dataType=campaign with include_metrics=true.", "items": {"type": "object", "description": "Projected CampaignData document (serialize_data).", "properties": {"_id": {"type": "string", "description": "Mongo document id."}, "campaignId": {"type": "string", "description": "Amazon campaign id."}, "name": {"type": "string", "description": "Campaign name."}, "state": {"type": "string", "description": "Campaign state."}, "sponsoredType": {"type": "string", "description": "Ad type: Product, Brand or Display."}, "budget": {"type": ["number", "object", "null"], "description": "Stored budget value (see tool description)."}, "startDate": {"type": ["string", "null"], "description": "Campaign start date as stored."}, "endDate": {"type": ["string", "null"], "description": "Campaign end date as stored."}, "portfolioId": {"type": ["string", "null"], "description": "Amazon portfolio id, if any."}}}}}, "required": ["tagId", "value", "color", "bgColor", "entityCount"]}}, "totalTags": {"type": "integer", "description": "Number of tags returned (after tag_labels filtering)."}, "totalAssignments": {"type": "integer", "description": "Sum of entityCount across the returned tags."}, "account": {"type": "object", "description": "The Amazon account the tags belong to.", "properties": {"id": {"type": "string", "description": "SellerMate Amazon account id."}, "name": {"type": "string", "description": "Account display name (accountName)."}}, "required": ["id", "name"]}, "dateRange": {"type": "object", "description": "The metrics window; present only when include_metrics=true.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}}, "required": ["dataType", "tags", "totalTags", "totalAssignments", "account"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_tag": {"post": {"operationId": "update_tag", "tags": ["Tags"], "summary": "Update Tag", "description": "Tool name: `update_tag` \u00b7 **Scope:** requires `tools:write`.\n\nRename or restyle a tag (`target: \"tag\"`, the default): `new_tag_value` renames it everywhere it is assigned, `color` / `bg_color` restyle it. `target: \"tag_group\"` renames a tag group via `new_title` (give `data_type` when identifying the group by title). Does not change which entities carry the tag \u2014 use `create_tag` / `delete_tag` for that.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID Auto-filled when your API key is restricted to a single Amazon account."}, "target": {"type": "string", "enum": ["tag", "tag_group"], "description": "'tag' (default) edits a tag label; 'tag_group' renames a NEW-tag group/column."}, "tag_id": {"type": "string", "description": "target='tag': the tag id from get_tags. Preferred over tag_value."}, "tag_value": {"type": "string", "description": "target='tag': the tag's current label, if tag_id is unknown."}, "new_tag_value": {"type": "string", "description": "target='tag': new label, max 60 characters. Renames the tag everywhere it is currently assigned."}, "color": {"type": "string", "description": "target='tag': new hex text color, e.g. '#FFFFFF'."}, "bg_color": {"type": "string", "description": "target='tag': new hex background color, e.g. '#0037EB'."}, "new_title": {"type": "string", "description": "target='tag_group': the group's new title."}, "data_type": {"type": "string", "enum": ["campaign", "product", "targeting", "search_term"], "description": "target='tag_group': the group's entity type. Needed to disambiguate when identifying the group by title."}, "tag_group": {"type": "string", "description": "NEW-tag group (column) title, e.g. 'Brand' or 'Product Line'. Omit for OLD/legacy tags. Within a group an entity holds exactly one value \u2014 assigning another value archives the previous one."}, "tag_group_id": {"type": "string", "description": "NEW-tag group id, if known. Alternative to tag_group; takes precedence when both are supplied."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"description": "Outcome of renaming/restyling a tag label (target=tag) or renaming a NEW-tag group (target=tag_group); the shape depends on target.", "oneOf": [{"type": "object", "description": "target='tag': the tag label was updated, or nothing differed (status no_change).", "properties": {"status": {"type": "string", "enum": ["success", "no_change"], "description": "success when at least one field changed; no_change when nothing differed."}, "applied": {"type": "boolean", "description": "True when the tags document was written."}, "message": {"type": "string", "description": "Natural-language summary naming the changed fields."}, "target": {"type": "string", "enum": ["tag"], "description": "Always tag on this branch."}, "tag": {"type": "object", "description": "The tag after the update (current values on no_change).", "properties": {"tagId": {"type": "string", "description": "Tag definition id."}, "value": {"type": "string", "description": "Tag label."}, "color": {"type": "string", "description": "Hex text color."}, "bgColor": {"type": "string", "description": "Hex background color."}}, "required": ["tagId", "value", "color", "bgColor"]}, "changes": {"type": "object", "description": "Before/after per changed field; present only on success.", "properties": {"value": {"type": "object", "description": "Label rename.", "properties": {"before": {"type": ["string", "null"], "description": "Previous label."}, "after": {"type": "string", "description": "New normalized label."}}, "required": ["before", "after"]}, "color": {"type": "object", "description": "Text color change.", "properties": {"before": {"type": ["string", "null"], "description": "Previous hex text color."}, "after": {"type": "string", "description": "New hex text color."}}, "required": ["before", "after"]}, "bgColor": {"type": "object", "description": "Background color change.", "properties": {"before": {"type": ["string", "null"], "description": "Previous hex background color."}, "after": {"type": "string", "description": "New hex background color."}}, "required": ["before", "after"]}}}, "rollback_token": {"type": ["string", "null"], "description": "UUID for the recorded diff; present only on success."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "target", "tag", "chatAssistantUrl"]}, {"type": "object", "description": "target='tag_group': the NEW-tag group was renamed.", "properties": {"status": {"type": "string", "enum": ["success"], "description": "Always success on this branch (failures raise errors)."}, "applied": {"type": "boolean", "description": "Always true on this branch."}, "message": {"type": "string", "description": "Natural-language summary of the rename."}, "target": {"type": "string", "enum": ["tag_group"], "description": "Always tag_group on this branch."}, "tagSystem": {"type": "string", "enum": ["new"], "description": "Tag groups exist only in the new tag system."}, "tagGroup": {"type": ["object", "null"], "description": "The group after the rename (serialize_tag_group of the service result).", "properties": {"tagGroupId": {"type": "string", "description": "custom_dimension_and_metric document id."}, "title": {"type": "string", "description": "New group title."}, "dataType": {"type": "string", "description": "Entity type the group belongs to."}, "state": {"type": "string", "description": "Group state (active)."}}, "required": ["tagGroupId", "title", "dataType", "state"]}, "changes": {"type": "object", "description": "Before/after of the title.", "properties": {"title": {"type": "object", "description": "Title rename.", "properties": {"before": {"type": ["string", "null"], "description": "Previous title."}, "after": {"type": "string", "description": "New title."}}, "required": ["before", "after"]}}, "required": ["title"]}, "rollback_token": {"type": "string", "description": "UUID for the recorded diff."}, "chatAssistantUrl": {"type": "string", "description": "Deep link to the SellerMate chat assistant for this workspace/account."}}, "required": ["status", "applied", "message", "target", "tagSystem", "tagGroup", "changes", "rollback_token", "chatAssistantUrl"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_dsp_performance": {"post": {"operationId": "get_dsp_performance", "tags": ["Amazon DSP"], "summary": "Get DSP Performance", "description": "Tool name: `get_dsp_performance` \u00b7 **Scope:** requires `tools:read`.\n\nAmazon DSP performance over a date range \u2014 five reports behind one `report` enum (campaign / product / inventory / geo / audience), with `group_by` and `metrics` chosen per report. Separate from Sponsored Products data; do not combine the two. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "report": {"type": "string", "enum": ["audience", "campaign", "geo", "inventory", "product"], "description": "Which DSP report to run. 'campaign' for spend/sales/ROAS by campaign, 'product' for per-ASIN conversions, 'inventory' for placement/creative, 'geo' for geography, 'audience' for segments."}, "start_date": {"type": "string", "description": "Start date, YYYY-MM-DD (inclusive)."}, "end_date": {"type": "string", "description": "End date, YYYY-MM-DD (inclusive)."}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["advertiserId", "advertiserName", "asin", "brandName", "city", "conversionType", "country", "creativeId", "creativeName", "creativeSize", "creativeType", "deal", "dealId", "dealType", "dmaCode", "dmaName", "featuredAsin", "lineItemId", "lineItemName", "marketplace", "month", "orderCurrency", "orderId", "orderName", "parentAsin", "placement", "placementSize", "postalCode", "productCategory", "productGroup", "productName", "productSubCategory", "region", "reportGranularity", "segmentClassCode", "segmentId", "segmentMarketplaceId", "segmentName", "segmentSource", "segmentType", "site", "supplySource", "targetingMethod", "timeWindowStart", "week", "year"]}, "description": "Dimensions to break results out by. Valid values depend on `report` \u2014 this enum is the union across all five. Every report also accepts the time buckets 'timeWindowStart' (daily), 'week', 'month' and 'year'. Omit for the per-report default. Each extra dimension multiplies the row count, so add them one at a time."}, "metrics": {"type": "array", "items": {"type": "string", "enum": ["ROAS", "ROASFromClicks", "ROASFromViews", "addToCart", "addToCartRate", "addToList", "brandHaloPurchases", "brandHaloSales", "brandHaloUnitsSold", "brandSearchRate", "brandSearches", "clickThroughRate", "clicks", "combinedPurchaseRate", "detailPageViewRate", "detailPageViews", "eCPAddToCart", "eCPBrandSearch", "eCPC", "eCPDetailPageView", "eCPM", "eCPNewSubscribeAndSave", "eCPP", "impressions", "longTermROAS", "longTermSales", "measurableImpressions", "newSubscribeAndSave", "newSubscribeAndSaveRate", "newToBrandDetailPageViewRate", "newToBrandDetailPageViews", "newToBrandECPDetailPageView", "newToBrandECPP", "newToBrandPurchaseRate", "newToBrandPurchases", "newToBrandPurchasesPercentage", "newToBrandROAS", "newToBrandSales", "newToBrandUnitsSold", "productReviewPageVisits", "promotedPurchaseRate", "promotedPurchases", "promotedSales", "promotedUnitsSold", "purchases", "purchasesFromClicks", "purchasesFromViews", "sales", "totalCost", "totalDetailPageViews", "unitsSold", "vCPM", "viewabilityRate", "viewableClickThroughRate", "viewableImpressions"]}, "description": "Metric columns to return. Valid values depend on `report` \u2014 this enum is the union across all five. Omit for a sensible default set."}, "order_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional DSP order (campaign) IDs to restrict to. Resolve names to IDs with list_dsp_campaigns."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Optional ASIN filter. Only applies to report='product' \u2014 the other collections carry no ASIN field."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 200, "description": "Rows per page. Defaults to 50, max 200. Keep it small \u2014 responses over ~1 MB can be rejected by the MCP client."}, "sort_field": {"type": "string", "description": "Metric or dimension to sort by (must be valid for this report). Defaults to totalCost, or sales for report='product' (that collection has no cost field)."}, "sort_direction": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}}, "required": ["amazon_account_id", "report", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Amazon DSP performance rows for one of five reports (campaign, product, inventory, geo, audience), grouped by the requested dimensions, or an empty payload when no DSP advertiser is linked.", "oneOf": [{"type": "object", "description": "No active DSP advertiser account is linked to this Amazon account; rows is empty.", "properties": {"returned": {"type": "integer", "description": "Always 0."}, "message": {"type": "string", "description": "Explains that no DSP advertiser is linked (a setup gap, not an empty range)."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "rows": {"type": "array", "description": "Always empty.", "items": {"type": "object", "description": "Never populated."}}, "report": {"type": "string", "description": "Requested report name."}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": ["string", "null"], "description": "Start date, YYYY-MM-DD."}, "end": {"type": ["string", "null"], "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "groupBy": {"type": "array", "description": "Effective group_by dimensions.", "items": {"type": "string", "description": "Dimension query key."}}, "metricsRequested": {"type": "array", "description": "Effective metric keys.", "items": {"type": "string", "description": "Metric query key."}}}, "required": ["returned", "message", "account", "rows", "report", "dateRange", "groupBy", "metricsRequested"]}, {"type": "object", "description": "Report ran; the envelope is identical for all five reports, only the keys inside each row's dimensions/metrics maps differ per report.", "properties": {"report": {"type": "string", "description": "campaign, product, inventory, geo or audience."}, "rows": {"type": "array", "description": "One grouped row per distinct dimension combination for this page (a single row when group_by is empty).", "items": {"type": "object", "description": "Grouped row with camelCase dimension and metric maps.", "properties": {"dimensions": {"type": "object", "description": "Keys = requested group_by (plus auto-linked ids, e.g. orderId when grouping by orderName). Time buckets: timeWindowStart/week/month (ISO-8601 datetime strings), year (integer). Per report: campaign = orderId, orderName, orderCurrency, advertiserId, advertiserName, marketplace; product = asin, parentAsin, brandName, productName, productCategory, productSubCategory, productGroup, marketplace, orderId, orderName, lineItemId, lineItemName, advertiserId, advertiserName, conversionType, reportGranularity, featuredAsin, orderCurrency; inventory = orderId, orderName, lineItemId, lineItemName, supplySource, placementSize, placement, site, creativeId, creativeName, creativeSize, creativeType, deal, dealId, dealType, orderCurrency; geo = orderId, orderName, lineItemId, lineItemName, region, city, country, postalCode, dmaCode, dmaName, advertiserId, advertiserName, orderCurrency; audience = segmentName, segmentId, segmentType, targetingMethod, segmentSource, segmentClassCode, segmentMarketplaceId, advertiserId, advertiserName, orderCurrency, orderId, orderName, lineItemId, lineItemName.", "additionalProperties": {"type": ["string", "number", "null"], "description": "Dimension value as stored (ids may be stored as string or number)."}}, "metrics": {"type": "object", "description": "Keys = requested metrics (default set per report). Rates are percentages, ROAS = sales/cost, cost-per and rate metrics are null when the denominator is zero. Per report: campaign = impressions, viewableImpressions, clicks, totalCost, detailPageViews, purchases, purchasesFromClicks, purchasesFromViews, newToBrandPurchases, sales, unitsSold, longTermSales, clickThroughRate, viewableClickThroughRate, eCPP, newToBrandECPP, ROAS, longTermROAS, ROASFromClicks, ROASFromViews; product = impressions, clicks, clickThroughRate, purchases, sales, unitsSold, promotedPurchases, promotedSales, promotedUnitsSold, brandHaloPurchases, brandHaloSales, brandHaloUnitsSold, newToBrandPurchases, newToBrandSales, newToBrandUnitsSold, detailPageViews, totalDetailPageViews, addToCart, addToList, productReviewPageVisits, newSubscribeAndSave, newToBrandPurchasesPercentage, combinedPurchaseRate, promotedPurchaseRate, newToBrandPurchaseRate, detailPageViewRate; inventory = impressions, viewableImpressions, measurableImpressions, clicks, totalCost, detailPageViews, newToBrandDetailPageViews, addToCart, brandSearches, newSubscribeAndSave, purchases, sales, unitsSold, newToBrandPurchases, newToBrandSales, newToBrandUnitsSold, eCPM, clickThroughRate, eCPC, viewabilityRate, vCPM, eCPP, ROAS, newToBrandROAS, detailPageViewRate, eCPDetailPageView, newToBrandDetailPageViewRate, newToBrandECPDetailPageView, addToCartRate, eCPAddToCart, brandSearchRate, eCPBrandSearch, newSubscribeAndSaveRate, eCPNewSubscribeAndSave; geo = impressions, viewableImpressions, clicks, totalCost, detailPageViews, addToCart, brandSearches, newSubscribeAndSave, purchases, sales, unitsSold, newToBrandPurchases, clickThroughRate, vCPM, combinedPurchaseRate, ROAS, detailPageViewRate, eCPDetailPageView, addToCartRate, eCPAddToCart, brandSearchRate, eCPBrandSearch, newSubscribeAndSaveRate, eCPNewSubscribeAndSave; audience = impressions, clicks, totalCost, purchases, detailPageViews, clickThroughRate, eCPC.", "additionalProperties": {"type": ["number", "null"], "description": "Metric value; null when a derived metric's denominator is zero."}}}, "required": ["dimensions", "metrics"]}}, "returned": {"type": "integer", "description": "Number of rows on this page."}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": ["string", "null"], "description": "Start date, YYYY-MM-DD."}, "end": {"type": ["string", "null"], "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "groupBy": {"type": "array", "description": "Effective group_by dimensions (defaults: campaign=[orderName], product=[asin], others=[]).", "items": {"type": "string", "description": "Dimension query key."}}, "metricsRequested": {"type": "array", "description": "Effective metric keys.", "items": {"type": "string", "description": "Metric query key."}}, "filters": {"type": "object", "description": "Echo of the entity filters.", "properties": {"orderIds": {"type": ["array", "null"], "description": "DSP order ids filtered to, or null.", "items": {"type": "string", "description": "Order id."}}, "asins": {"type": ["array", "null"], "description": "ASINs filtered to (product report only), or null.", "items": {"type": "string", "description": "ASIN."}}}, "required": ["orderIds", "asins"]}, "sort": {"type": "object", "description": "Sort applied.", "properties": {"field": {"type": "string", "description": "Metric or dimension sorted on (default totalCost; sales for product)."}, "direction": {"type": "string", "description": "asc or desc."}}, "required": ["field", "direction"]}, "pagination": {"type": "object", "description": "Page metadata; has_more is inferred from a full page (no total count).", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "page_size": {"type": "integer", "description": "Effective page size (1-200)."}, "has_more": {"type": "boolean", "description": "True when the page is exactly full (may be a false positive on the last page)."}, "next_page": {"type": ["integer", "null"], "description": "Next page number, or null."}}, "required": ["page", "page_size", "has_more", "next_page"]}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "dspAdvertiserAccounts": {"type": "integer", "description": "Number of active DSP advertiser accounts the query was fenced to."}, "notes": {"type": "array", "description": "In-band caveats (product-report zeros note; shared promoted+halo attribution note).", "items": {"type": "string", "description": "Caveat text."}}}, "required": ["report", "rows", "returned", "dateRange", "groupBy", "metricsRequested", "filters", "sort", "pagination", "account", "dspAdvertiserAccounts", "notes"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_dsp_campaigns": {"post": {"operationId": "list_dsp_campaigns", "tags": ["Amazon DSP"], "summary": "List DSP Campaigns", "description": "Tool name: `list_dsp_campaigns` \u00b7 **Scope:** requires `tools:read`.\n\nDSP campaigns (orders) for an account: order_id, name, state, delivery status and flight dates. Metadata only \u2014 resolve a campaign name to the order_id that `get_dsp_performance` filters on.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context) Auto-filled when your API key is restricted to a single Amazon account."}, "name_search": {"type": "string", "description": "Filter by campaign name (case-insensitive partial match)."}, "state": {"type": "array", "items": {"type": "string"}, "description": "Filter by campaign state as stored by Amazon (e.g. ACTIVE, PAUSED, ARCHIVED). Omit to return every state."}, "delivery_status": {"type": "array", "items": {"type": "string"}, "description": "Filter by Amazon delivery status (e.g. DELIVERING, NOT_DELIVERING). Omit to return every status."}, "order_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional exact DSP order (campaign) IDs to look up."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 200, "description": "Campaigns per page. Defaults to 50, max 200."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Paginated list of Amazon DSP campaigns (orders) with metadata only, or an empty payload when no DSP advertiser is linked.", "oneOf": [{"type": "object", "description": "No active DSP advertiser account is linked to this Amazon account; campaigns is empty.", "properties": {"returned": {"type": "integer", "description": "Always 0."}, "message": {"type": "string", "description": "Explains that no DSP advertiser is linked (a setup gap, not an empty list)."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "campaigns": {"type": "array", "description": "Always empty.", "items": {"type": "object", "description": "Never populated."}}}, "required": ["returned", "message", "account", "campaigns"]}, {"type": "object", "description": "One page of DspCampaignData documents sorted by name asc.", "properties": {"campaigns": {"type": "array", "description": "Campaign rows for this page; only orderId is guaranteed, other fields appear when stored on the document.", "items": {"type": "object", "description": "Projected DSP campaign metadata (serialized: datetime -> ISO-8601 string).", "properties": {"orderId": {"type": ["string", "null"], "description": "DSP order (campaign) id as a string; null when missing."}, "name": {"type": "string", "description": "Campaign name."}, "state": {"type": "string", "description": "Campaign state as stored by Amazon (e.g. ACTIVE, PAUSED, ARCHIVED)."}, "deliveryStatus": {"type": "string", "description": "Amazon delivery status (e.g. DELIVERING, NOT_DELIVERING)."}, "startDateTime": {"type": ["string", "null"], "description": "Flight start as stored (ISO-8601 string when a datetime)."}, "endDateTime": {"type": ["string", "null"], "description": "Flight end as stored (ISO-8601 string when a datetime)."}, "budget": {"type": ["number", "object", "string", "null"], "description": "Budget as stored on the document (see tool description)."}, "advertiserId": {"type": ["string", "number", "null"], "description": "DSP advertiser id as stored."}, "advertiserName": {"type": ["string", "null"], "description": "DSP advertiser name."}, "orderCurrency": {"type": ["string", "null"], "description": "Order currency code."}}, "required": ["orderId"]}}, "returned": {"type": "integer", "description": "Number of rows on this page."}, "total": {"type": "integer", "description": "Total campaigns matching the filters."}, "filters": {"type": "object", "description": "Echo of the request filters.", "properties": {"name_search": {"type": ["string", "null"], "description": "Case-insensitive name substring, or null."}, "state": {"type": ["array", "null"], "description": "State values filtered to, or null.", "items": {"type": "string", "description": "State value."}}, "delivery_status": {"type": ["array", "null"], "description": "Delivery statuses filtered to, or null.", "items": {"type": "string", "description": "Delivery status value."}}, "order_ids": {"type": ["array", "null"], "description": "Order ids filtered to, or null.", "items": {"type": "string", "description": "Order id."}}}, "required": ["name_search", "state", "delivery_status", "order_ids"]}, "pagination": {"type": "object", "description": "Simple page metadata.", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "page_size": {"type": "integer", "description": "Effective page size (1-200)."}, "has_more": {"type": "boolean", "description": "Whether a further page exists."}, "next_page": {"type": ["integer", "null"], "description": "Next page number, or null on the last page."}}, "required": ["page", "page_size", "has_more", "next_page"]}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}, "dspAdvertiserAccounts": {"type": "integer", "description": "Number of active DSP advertiser accounts the query was fenced to."}}, "required": ["campaigns", "returned", "total", "filters", "pagination", "account", "dspAdvertiserAccounts"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/create_amc_audience": {"post": {"operationId": "create_amc_audience", "tags": ["Amazon Marketing Cloud"], "summary": "Create AMC Audience", "description": "Tool name: `create_amc_audience` \u00b7 **Scope:** requires `tools:write`.\n\nCreate a rule-based (default) or lookalike AMC audience on the account's instance. Source: a `template_id` with its inputs, a `query_payload`, or raw `query` SQL. `activation` is `SPONSORED_ADS` (default) or `DSP` (fails if the instance has no DSP advertiser). `days` sets the lookback (default: the template's, or 90); `refresh_rate_days` 0\u201321 (7\u201321 for a lookalike; default 21); a lookalike also needs `lookalike_expected_reach`. Run `estimate_amc_audience_size` first when in doubt, or pass `dry_run: true` to get the resolved plan and SQL without creating anything. Amazon builds the audience asynchronously \u2014 follow up with `list_amc_audiences`.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "name": {"type": "string", "description": "Audience name (1\u2013100 characters)."}, "description": {"type": "string", "description": "Optional description (defaults to the template's)."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "template_id": {"type": "string", "description": "A recipe from get_amc_audience_templates. Give its inputs below when it needs them."}, "search_terms": {"description": "For a search-term recipe: the customer search terms (list or comma-separated).", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "asins": {"description": "For an ASIN-scoped recipe: the ASINs of the first row (list or comma-separated).", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "asins_b": {"description": "Cross-sell only: the ASINs of the second (excluded) row.", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "value": {"type": "number", "description": "For a recipe with an open threshold (high-value buyers): the order value."}, "query_payload": {"type": "object", "description": "Instead of a template: a rule-builder payload {conditions:[...], connectors:[...]} as the AMC audience agent produces."}, "query": {"type": "string", "description": "Instead of a template or payload: raw AMC audience SQL on the *_for_audiences tables."}, "days": {"type": "integer", "description": "Lookback window in days ending today (default: the template's, or 90)."}, "audience_type": {"type": "string", "enum": ["RULE_BASED", "LOOKALIKE"], "description": "Which minimum to grade against (default RULE_BASED: 2,000 users; LOOKALIKE seed: 500 to 500,000)."}, "time_window_start": {"type": "string", "description": "Optional explicit window start (ISO 8601 UTC) instead of days."}, "time_window_end": {"type": "string", "description": "Optional explicit window end (ISO 8601 UTC) instead of days."}, "time_window_relative": {"type": "boolean", "description": "Slide the window forward on each refresh (default true)."}, "refresh_rate_days": {"type": "integer", "description": "How often Amazon rebuilds it: 0\u201321 days (7\u201321 for a lookalike). Default 21."}, "lookalike_expected_reach": {"type": "string", "enum": ["MOST_SIMILAR", "SIMILAR", "BALANCED", "BROAD", "MOST_BROAD"], "description": "Lookalike only: how far from the seed to reach."}, "activation": {"type": "string", "enum": ["SPONSORED_ADS", "DSP"], "description": "Where the audience is activated (default SPONSORED_ADS)."}, "dry_run": {"type": "boolean", "description": "true = return the resolved plan and SQL without creating anything."}}, "required": ["amazon_account_id", "name"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "dry_run true: the resolved plan and SQL that would be sent to Amazon; nothing was created.", "properties": {"dryRun": {"type": "boolean", "description": "Always true on this branch."}, "wouldCreate": {"type": "object", "description": "The resolved create plan.", "properties": {"instanceId": {"type": ["string", "null"], "description": "Instance the audience would be created on."}, "instanceName": {"type": ["string", "null"], "description": "That instance's display name."}, "name": {"type": "string", "description": "Audience name (1-100 characters)."}, "description": {"type": "string", "description": "Audience description (the template's when none given)."}, "audienceType": {"type": "string", "description": "RULE_BASED or LOOKALIKE."}, "activatedIn": {"type": ["string", "null"], "description": "Sponsored Ads or Amazon DSP (else the advertiser's raw type)."}, "advertiserId": {"type": "string", "description": "Advertiser on the instance the audience is activated under."}, "timeWindowStart": {"type": "string", "description": "Window start, ISO 8601 UTC (e.g. 2026-07-23T00:00:00.000Z)."}, "timeWindowEnd": {"type": "string", "description": "Window end, ISO 8601 UTC."}, "timeWindowRelative": {"type": "boolean", "description": "Whether the window slides forward on each refresh."}, "refreshRateDays": {"type": "integer", "description": "How often Amazon rebuilds it (0-21 days)."}, "lookalikeExpectedReach": {"type": ["string", "null"], "description": "Lookalike reach level; null for rule-based."}, "templateId": {"type": ["string", "null"], "description": "Recipe used, or null for a query_payload / raw query."}, "query": {"type": "string", "description": "The AMC audience SQL that would be submitted."}}, "required": ["instanceId", "instanceName", "name", "description", "audienceType", "activatedIn", "advertiserId", "timeWindowStart", "timeWindowEnd", "timeWindowRelative", "refreshRateDays", "lookalikeExpectedReach", "templateId", "query"]}, "note": {"type": "string", "description": "States nothing was created and suggests estimating size first."}}, "required": ["dryRun", "wouldCreate", "note"]}, {"type": "object", "description": "Audience accepted by Amazon: Amazon's execution record, the plan that was sent, and a follow-up note.", "properties": {"created": {"type": "object", "description": "Amazon's audience execution as read back after the create (GET /amc/audiences/query/{id}), or a minimal PENDING stub with syncWarning when that read-back failed.", "properties": {"audienceExecutionId": {"type": "string", "description": "Amazon's execution id; use it with list_amc_audiences."}, "audienceId": {"type": ["string", "null"], "description": "Amazon's audience id (once assigned)."}, "audienceName": {"type": ["string", "null"], "description": "Audience name."}, "audienceDescription": {"type": ["string", "null"], "description": "Audience description."}, "status": {"type": ["string", "null"], "description": "Build status, typically PENDING right after creation."}, "statusReason": {"type": ["string", "null"], "description": "Amazon's reason when FAILED."}, "audienceType": {"type": ["string", "null"], "description": "RULE_BASED or LOOKALIKE."}, "audienceCount": {"type": ["number", "null"], "description": "Amazon's rounded size once built."}, "advertiserId": {"type": ["string", "null"], "description": "Advertiser the audience is activated under."}, "advertiserType": {"type": ["string", "null"], "description": "SPONSORED_ADS or DISPLAY."}, "dspAudienceId": {"type": ["string", "null"], "description": "Amazon's targetable audience id once built."}, "query": {"type": ["string", "null"], "description": "The audience SQL."}, "refreshRateDays": {"type": ["integer", "null"], "description": "Refresh cadence in days."}, "timeWindowStart": {"type": ["string", "null"], "description": "Window start (ISO 8601)."}, "timeWindowEnd": {"type": ["string", "null"], "description": "Window end (ISO 8601)."}, "timeWindowRelative": {"type": ["boolean", "null"], "description": "Whether the window is relative."}, "createTime": {"type": ["string", "null"], "description": "ISO 8601 creation time."}, "lastRefreshedTime": {"type": ["string", "null"], "description": "ISO 8601 last refresh time."}, "lookalikeAudienceExpectedReach": {"type": ["string", "null"], "description": "Lookalike reach level (lookalike only)."}, "syncWarning": {"type": "string", "description": "Present only when Amazon accepted the create but SellerMate could not load its details yet."}}, "required": []}, "plan": {"type": "object", "description": "The create plan that was sent (same shape as wouldCreate on the dry-run branch).", "properties": {"instanceId": {"type": ["string", "null"], "description": "Instance the audience was created on."}, "instanceName": {"type": ["string", "null"], "description": "That instance's display name."}, "name": {"type": "string", "description": "Audience name."}, "description": {"type": "string", "description": "Audience description."}, "audienceType": {"type": "string", "description": "RULE_BASED or LOOKALIKE."}, "activatedIn": {"type": ["string", "null"], "description": "Sponsored Ads or Amazon DSP."}, "advertiserId": {"type": "string", "description": "Advertiser the audience is activated under."}, "timeWindowStart": {"type": "string", "description": "Window start, ISO 8601 UTC."}, "timeWindowEnd": {"type": "string", "description": "Window end, ISO 8601 UTC."}, "timeWindowRelative": {"type": "boolean", "description": "Whether the window slides on refresh."}, "refreshRateDays": {"type": "integer", "description": "Refresh cadence in days."}, "lookalikeExpectedReach": {"type": ["string", "null"], "description": "Lookalike reach level; null for rule-based."}, "templateId": {"type": ["string", "null"], "description": "Recipe used, or null."}, "query": {"type": "string", "description": "The AMC audience SQL submitted."}}, "required": ["instanceId", "instanceName", "name", "description", "audienceType", "activatedIn", "advertiserId", "timeWindowStart", "timeWindowEnd", "timeWindowRelative", "refreshRateDays", "lookalikeExpectedReach", "templateId", "query"]}, "note": {"type": "string", "description": "Explains the asynchronous build and how to follow up."}}, "required": ["created", "plan", "note"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/estimate_amc_audience_size": {"post": {"operationId": "estimate_amc_audience_size", "tags": ["Amazon Marketing Cloud"], "summary": "Estimate AMC Audience Size", "description": "Tool name: `estimate_amc_audience_size` \u00b7 **Scope:** requires `tools:read`.\n\nCount how many shoppers an audience definition would contain before creating it. Amazon rejects a rule-based audience under 2,000 users (2,500 recommended) and a lookalike seed outside 500\u2013500,000, and only says so after building it. Give a `template_id` (plus its inputs), a `query_payload`, or raw `query` SQL, with optional `days` and `audience_type`. Returns an `estimateId` immediately; AMC takes one to five minutes, so poll `get_amc_audience_size_estimate`. Nothing is created.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "template_id": {"type": "string", "description": "A recipe from get_amc_audience_templates. Give its inputs below when it needs them."}, "search_terms": {"description": "For a search-term recipe: the customer search terms (list or comma-separated).", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "asins": {"description": "For an ASIN-scoped recipe: the ASINs of the first row (list or comma-separated).", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "asins_b": {"description": "Cross-sell only: the ASINs of the second (excluded) row.", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "value": {"type": "number", "description": "For a recipe with an open threshold (high-value buyers): the order value."}, "query_payload": {"type": "object", "description": "Instead of a template: a rule-builder payload {conditions:[...], connectors:[...]} as the AMC audience agent produces."}, "query": {"type": "string", "description": "Instead of a template or payload: raw AMC audience SQL on the *_for_audiences tables."}, "days": {"type": "integer", "description": "Lookback window in days ending today (default: the template's, or 90)."}, "audience_type": {"type": "string", "enum": ["RULE_BASED", "LOOKALIKE"], "description": "Which minimum to grade against (default RULE_BASED: 2,000 users; LOOKALIKE seed: 500 to 500,000)."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "A started (or reused) AMC size-estimate execution with the resolved instance, window and the audience SQL it counts.", "properties": {"estimate": {"type": "object", "description": "The estimate record; freshly started ones are PENDING, a reused identical one may already be RUNNING or SUCCEEDED.", "properties": {"estimateId": {"type": "string", "description": "Id to poll with get_amc_audience_size_estimate."}, "status": {"type": ["string", "null"], "description": "PENDING, RUNNING, SUCCEEDED, FAILED, REJECTED or CANCELLED."}, "audienceSize": {"type": ["integer", "null"], "description": "COUNT(DISTINCT user_id) once SUCCEEDED; null until then or when suppressed."}, "suppressed": {"type": ["boolean", "null"], "description": "True when AMC withheld the count (fewer than ~100 users)."}, "verdict": {"type": ["string", "null"], "description": "ok, borderline, too_small or too_large once graded."}, "minimum": {"type": ["integer", "null"], "description": "Minimum users graded against (2000 rule-based, 500 lookalike seed)."}, "recommended": {"type": ["integer", "null"], "description": "Recommended users (2500 rule-based, 500 lookalike seed)."}, "maximum": {"type": ["integer", "null"], "description": "Maximum users (500000 for a lookalike seed; null for rule-based)."}, "reason": {"type": ["string", "null"], "description": "AMC's reason when the execution ended in a non-success terminal status."}, "countSql": {"type": ["string", "null"], "description": "The COUNT workflow SQL that was submitted."}, "timeWindowStart": {"type": ["string", "null"], "description": "Window start, YYYY-MM-DDTHH:MM:SS (UTC)."}, "timeWindowEnd": {"type": ["string", "null"], "description": "Window end, YYYY-MM-DDTHH:MM:SS (UTC)."}, "createdAt": {"type": ["string", "null"], "description": "ISO 8601 datetime the estimate record was created."}, "updatedAt": {"type": ["string", "null"], "description": "ISO 8601 datetime of the last status update."}}, "required": ["estimateId", "status", "audienceSize", "suppressed", "verdict", "minimum", "recommended", "maximum", "reason", "countSql", "timeWindowStart", "timeWindowEnd", "createdAt", "updatedAt"]}, "instanceId": {"type": "string", "description": "Instance the estimate runs on (requested or default)."}, "instanceName": {"type": ["string", "null"], "description": "That instance's display name."}, "templateId": {"type": ["string", "null"], "description": "Recipe used, or null for a query_payload / raw query."}, "windowDays": {"type": "integer", "description": "Lookback window in days ending today (template default or 90)."}, "audienceSql": {"type": "string", "description": "The audience SQL the count was derived from."}, "note": {"type": "string", "description": "Polling guidance and the 2,000-user minimum reminder."}}, "required": ["estimate", "instanceId", "instanceName", "templateId", "windowDays", "audienceSql", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_audience_size_estimate": {"post": {"operationId": "get_amc_audience_size_estimate", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Audience Size Estimate", "description": "Tool name: `get_amc_audience_size_estimate` \u00b7 **Scope:** requires `tools:read`.\n\nPoll an estimate by `estimate_id`. Returns `status` (`PENDING` / `RUNNING` / `SUCCEEDED` / `FAILED`), `audienceSize`, `suppressed` (true when AMC withheld the number because the audience is under roughly 100 shoppers \u2014 not zero), a `verdict` (`ok` / `borderline` / `too_small` / `too_large`) with the thresholds it was graded against, and `sizeText`. Poll about once a minute until the status is terminal.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "estimate_id": {"type": "string", "description": "The estimateId returned by estimate_amc_audience_size."}, "instance_id": {"type": "string", "description": "The instanceId the estimate was started on (defaults to the account's default instance)."}}, "required": ["amazon_account_id", "estimate_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "The current state of a size estimate (refreshed from AMC while it is not terminal) with a ready-to-quote size line.", "properties": {"estimate": {"type": "object", "description": "The estimate record after the refresh.", "properties": {"estimateId": {"type": "string", "description": "The estimate id that was polled."}, "status": {"type": ["string", "null"], "description": "PENDING, RUNNING, SUCCEEDED, FAILED, REJECTED or CANCELLED."}, "audienceSize": {"type": ["integer", "null"], "description": "Distinct users counted once SUCCEEDED; null while running or when suppressed."}, "suppressed": {"type": ["boolean", "null"], "description": "True when AMC withheld the count (fewer than ~100 users): size unknown, not zero."}, "verdict": {"type": ["string", "null"], "description": "ok, borderline, too_small or too_large once graded."}, "minimum": {"type": ["integer", "null"], "description": "Minimum users graded against (2000 rule-based, 500 lookalike seed)."}, "recommended": {"type": ["integer", "null"], "description": "Recommended users (2500 rule-based, 500 lookalike seed)."}, "maximum": {"type": ["integer", "null"], "description": "Maximum users (500000 lookalike seed; null for rule-based)."}, "reason": {"type": ["string", "null"], "description": "AMC's reason on FAILED / REJECTED / CANCELLED."}, "countSql": {"type": ["string", "null"], "description": "The COUNT workflow SQL that was submitted."}, "timeWindowStart": {"type": ["string", "null"], "description": "Window start, YYYY-MM-DDTHH:MM:SS (UTC)."}, "timeWindowEnd": {"type": ["string", "null"], "description": "Window end, YYYY-MM-DDTHH:MM:SS (UTC)."}, "createdAt": {"type": ["string", "null"], "description": "ISO 8601 datetime the estimate was created."}, "updatedAt": {"type": ["string", "null"], "description": "ISO 8601 datetime of the last status update."}}, "required": ["estimateId", "status", "audienceSize", "suppressed", "verdict", "minimum", "recommended", "maximum", "reason", "countSql", "timeWindowStart", "timeWindowEnd", "createdAt", "updatedAt"]}, "sizeText": {"type": ["string", "null"], "description": "One ready-to-quote line ('About N shoppers \u2014 ...' or the suppressed wording) once SUCCEEDED; null otherwise."}, "instanceId": {"type": "string", "description": "Instance the estimate was read from."}, "note": {"type": "string", "description": "Still running / done / did-not-complete guidance for the caller."}}, "required": ["estimate", "sizeText", "instanceId", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_audience_templates": {"post": {"operationId": "get_amc_audience_templates", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Audience Templates", "description": "Tool name: `get_amc_audience_templates` \u00b7 **Scope:** requires `tools:read`.\n\nSellerMate's library of ready-made AMC audience recipes (cart abandoners, repeat viewers, high-value / new-to-brand / lapsed buyers, cross-sell, ad-fatigued non-clickers, \u2026). Each entry gives a `templateId`, what it selects, its default lookback window, the inputs it still needs (`search_terms`, `asins`, `value`), whether it suits a lookalike seed, and where it can be activated. Filter with `group` or fetch one by `template_id`; `include_payload` adds each recipe's rule payload. Needs no account id.", "x-permission-level": "read", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"template_id": {"type": "string", "description": "One recipe by id (returns its rule payload too)."}, "group": {"type": "string", "enum": ["Retarget", "Loyalty & growth", "Exclusion"], "description": "Only this group."}, "include_payload": {"type": "boolean", "description": "Include each recipe's rule payload (default false)."}}}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "Library listing (no template_id): the group names, the matching recipes, and a usage note.", "properties": {"groups": {"type": "array", "description": "All template groups in library order: Retarget, Loyalty & growth, Exclusion.", "items": {"type": "string", "description": "Group name."}}, "templates": {"type": "array", "description": "Recipes in library order, optionally limited to one group; payload only when include_payload is true.", "items": {"type": "object", "description": "One ready-made audience recipe.", "properties": {"templateId": {"type": "string", "description": "Recipe id to pass to create_amc_audience or estimate_amc_audience_size."}, "group": {"type": "string", "description": "Retarget, Loyalty & growth or Exclusion."}, "title": {"type": "string", "description": "Recipe title."}, "blurb": {"type": "string", "description": "One-line summary of who it selects."}, "description": {"type": "string", "description": "Full description, also the audience's default description."}, "suggestedName": {"type": "string", "description": "Suggested audience name."}, "windowDays": {"type": "integer", "description": "Lookback window the recipe assumes, in days (overridable)."}, "lookalikeSeed": {"type": "boolean", "description": "True when the recipe is a good lookalike seed."}, "adTypes": {"type": "array", "description": "Where the audience works: SPONSORED_ADS and/or DSP.", "items": {"type": "string", "description": "SPONSORED_ADS or DSP."}}, "worksIn": {"type": "string", "description": "Human label of adTypes, e.g. 'Sponsored Ads \u00b7 Amazon DSP' or 'Amazon DSP only'."}, "inputsNeeded": {"type": "array", "description": "Human descriptions of the inputs the recipe still needs (search_terms, asins/asins_b, value).", "items": {"type": "string", "description": "One input the caller must supply."}}, "payload": {"type": "object", "description": "Rule-builder payload (present only when include_payload is true).", "properties": {"conditions": {"type": "array", "description": "Condition rows joined by connectors.", "items": {"type": "object", "description": "One rule-builder condition row.", "properties": {"metric": {"type": "string", "description": "Metric, e.g. orders, add_to_cart, clicks, search_term."}, "operatorType": {"type": ["string", "null"], "description": "'total' (null for search_term rows)."}, "operator": {"type": ["string", "null"], "description": "Comparison operator such as '>=' (null for search_term rows)."}, "value": {"type": ["number", "null"], "description": "Threshold; null when the recipe leaves it open."}, "rangeMin": {"type": ["number", "null"], "description": "Range lower bound (unused by templates)."}, "rangeMax": {"type": ["number", "null"], "description": "Range upper bound (unused by templates)."}, "campaignFilter": {"type": "string", "description": "'all' or 'specific'."}, "campaigns": {"type": "array", "description": "Campaign scope when specific.", "items": {"type": "string"}}, "asinFilter": {"type": "string", "description": "'all' or 'specific'."}, "asins": {"type": "array", "description": "ASIN scope when specific (empty until supplied).", "items": {"type": "string"}}, "searchTermFilter": {"type": "string", "description": "'specific' (search-term rows)."}, "searchTerms": {"type": "array", "description": "Search terms (empty until supplied).", "items": {"type": "string"}}, "daysAgoMin": {"type": "integer", "description": "Optional per-row lookback lower bound in days."}, "daysAgoMax": {"type": "integer", "description": "Optional per-row lookback upper bound in days."}}, "required": ["metric", "operatorType", "operator", "value", "rangeMin", "rangeMax", "campaignFilter", "campaigns", "asinFilter", "asins", "searchTermFilter", "searchTerms"]}}, "connectors": {"type": "array", "description": "Connector between consecutive conditions: AND, OR or EXCLUDE.", "items": {"type": "string", "description": "AND, OR or EXCLUDE."}}}, "required": ["conditions", "connectors"]}}, "required": ["templateId", "group", "title", "blurb", "description", "suggestedName", "windowDays", "lookalikeSeed", "adTypes", "worksIn", "inputsNeeded"]}}, "note": {"type": "string", "description": "How to use a templateId with the create/estimate tools."}}, "required": ["groups", "templates", "note"]}, {"type": "object", "description": "Single-recipe lookup (template_id given): exactly one recipe, always with its payload; no groups or note.", "properties": {"templates": {"type": "array", "description": "Exactly one recipe, same item shape as the listing branch, payload always present.", "items": {"type": "object", "description": "The requested recipe (see the listing branch for every property).", "properties": {"templateId": {"type": "string", "description": "Recipe id."}, "group": {"type": "string", "description": "Template group."}, "title": {"type": "string", "description": "Recipe title."}, "blurb": {"type": "string", "description": "One-line summary."}, "description": {"type": "string", "description": "Full description."}, "suggestedName": {"type": "string", "description": "Suggested audience name."}, "windowDays": {"type": "integer", "description": "Assumed lookback window in days."}, "lookalikeSeed": {"type": "boolean", "description": "Good lookalike seed."}, "adTypes": {"type": "array", "description": "SPONSORED_ADS and/or DSP.", "items": {"type": "string"}}, "worksIn": {"type": "string", "description": "Human label of adTypes."}, "inputsNeeded": {"type": "array", "description": "Inputs the recipe still needs.", "items": {"type": "string"}}, "payload": {"type": "object", "description": "Rule-builder payload {conditions, connectors} (same shape as the listing branch)."}}, "required": ["templateId", "group", "title", "blurb", "description", "suggestedName", "windowDays", "lookalikeSeed", "adTypes", "worksIn", "inputsNeeded", "payload"]}}}, "required": ["templates"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_custom_attribution": {"post": {"operationId": "get_amc_custom_attribution", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Custom Attribution", "description": "Tool name: `get_amc_custom_attribution` \u00b7 **Scope:** requires `tools:read`.\n\nAMC Custom Attribution report: per-campaign conversions under a chosen attribution model, selected with `granularity` (`LAST_TOUCH` default, `FIRST_TOUCH`, `LINEAR`, `POSITION`). Metrics include impressions, clicks, `user_reach`, `users_that_converted`, `conversions`, `conversion_rate`, `total_units_sold` and `total_product_sales`, plus a pinned Total row. `month` is `YYYY-MM` from `get_amc_report_options` (default: latest available). Sortable, filterable via `filter_model`; `page` is 1-based (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "month": {"type": "string", "description": "Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month."}, "granularity": {"type": "string", "enum": ["LAST_TOUCH", "FIRST_TOUCH", "LINEAR", "POSITION"], "description": "Attribution MODEL (this report's granularity slot). LAST_TOUCH is the default."}, "sort_by": {"type": "string", "description": "Field to sort by. Defaults to the report's default sort."}, "sort_order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page": {"type": "integer", "description": "1-based page number. Defaults to 1 \u2014 increment to page through all rows (see the response's pagination block)."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits."}, "filter_model": {"type": "object", "description": "Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the AMC Custom Attribution report for one (attribution model, month): per-campaign rows, server-side grand totals for the pinned Total row, and a pagination block.", "properties": {"granularity": {"type": "string", "description": "The attribution model the rows are for: LAST_TOUCH, FIRST_TOUCH, LINEAR or POSITION."}, "month": {"type": ["string", "null"], "description": "Report month YYYY-MM (latest available when not requested); null when the account has no months."}, "sortBy": {"type": "string", "description": "Field the rows are sorted by (requested if whitelisted, else conversions)."}, "sortOrder": {"type": "string", "description": "asc or desc."}, "rows": {"type": "array", "description": "The requested page of campaign rows (report column names as stored by the AMC sync).", "items": {"type": "object", "description": "One campaign's attributed performance under the selected model.", "properties": {"campaign": {"type": ["string", "null"], "description": "Campaign name."}, "ad_product_type": {"type": ["string", "null"], "description": "Ad product type of the campaign (e.g. sponsored_products, dsp)."}, "attribution_model": {"type": ["string", "null"], "description": "Attribution model the row was computed under."}, "impressions": {"type": ["number", "null"], "description": "Impressions."}, "clicks": {"type": ["number", "null"], "description": "Clicks."}, "user_reach": {"type": ["number", "null"], "description": "Distinct users reached."}, "users_that_converted": {"type": ["number", "null"], "description": "Distinct users who converted."}, "conversions": {"type": ["number", "null"], "description": "Conversions attributed to the campaign under the model."}, "conversion_rate": {"type": ["number", "null"], "description": "Conversion rate as a 0-1 fraction."}, "total_units_sold": {"type": ["number", "null"], "description": "Units sold."}, "total_product_sales": {"type": ["number", "null"], "description": "Product sales in the account currency."}, "reportType": {"type": "string", "description": "Always CUSTOM_ATTRIBUTION."}, "granularity": {"type": "string", "description": "The attribution model (same as the top-level granularity)."}, "reportMonth": {"type": "string", "description": "Report month YYYY-MM."}, "instanceId": {"type": "string", "description": "AMC instance the row was synced from."}}, "required": ["reportType", "granularity"]}}, "totals": {"type": "object", "description": "Pinned Total row: column sums over the whole filtered slice; conversion_rate recomputed from the sums (numerator users_that_converted for last/first touch, conversions for linear/position, over user_reach).", "properties": {"impressions": {"type": "number", "description": "Sum of impressions."}, "clicks": {"type": "number", "description": "Sum of clicks."}, "user_reach": {"type": "number", "description": "Sum of user_reach."}, "users_that_converted": {"type": "number", "description": "Sum of users_that_converted."}, "conversions": {"type": "number", "description": "Sum of conversions."}, "total_units_sold": {"type": "number", "description": "Sum of total_units_sold."}, "total_product_sales": {"type": "number", "description": "Sum of total_product_sales."}, "conversion_rate": {"type": "number", "description": "Model numerator / sum of user_reach (0 when reach is 0)."}}, "required": ["impressions", "clicks", "user_reach", "users_that_converted", "conversions", "total_units_sold", "total_product_sales", "conversion_rate"]}, "pagination": {"type": "object", "description": "Page position over the filtered slice (always paginated on this surface; page defaults to 1, page_size to 100, max 500).", "properties": {"page": {"type": "integer", "description": "1-based page returned."}, "pageSize": {"type": "integer", "description": "Rows per page."}, "total": {"type": "integer", "description": "Rows in the whole filtered slice."}, "totalPages": {"type": "integer", "description": "Number of pages (0 when total is 0)."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}}, "required": ["granularity", "month", "sortBy", "sortOrder", "rows", "totals", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_path_to_conversion": {"post": {"operationId": "get_amc_path_to_conversion", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Path to Conversion", "description": "Tool name: `get_amc_path_to_conversion` \u00b7 **Scope:** requires `tools:read`.\n\nAMC Path to Conversion report: the ad-exposure paths shoppers took before purchasing, one row per path, grouped by `granularity` (`AD_TYPE` default or `CAMPAIGN`). Metrics include `path_occurrences`, impressions, `imp_total_cost`, `users_that_purchased`, `sales_amount`, `purchases`, `user_purchase_rate` and new-to-brand (`ntb_*`) columns, plus a pinned Total row. `month` is `YYYY-MM` (default: latest available). `page` is 1-based (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "month": {"type": "string", "description": "Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month."}, "granularity": {"type": "string", "enum": ["AD_TYPE", "CAMPAIGN"], "description": "Path grouping. AD_TYPE (default) groups paths by ad type; CAMPAIGN groups by campaign."}, "sort_by": {"type": "string", "description": "Field to sort by. Defaults to the report's default sort."}, "sort_order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page": {"type": "integer", "description": "1-based page number. Defaults to 1 \u2014 increment to page through all rows (see the response's pagination block)."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits."}, "filter_model": {"type": "object", "description": "Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the AMC Path to Conversion report for one (granularity, month): one row per ad-exposure path, server-side grand totals for the pinned Total row, and a pagination block.", "properties": {"granularity": {"type": "string", "description": "Path grouping the rows are for: AD_TYPE or CAMPAIGN."}, "month": {"type": ["string", "null"], "description": "Report month YYYY-MM (latest available when not requested); null when the account has no months."}, "sortBy": {"type": "string", "description": "Field the rows are sorted by (requested if whitelisted, else path_occurrences)."}, "sortOrder": {"type": "string", "description": "asc or desc."}, "rows": {"type": "array", "description": "The requested page of path rows (report column names as stored by the AMC sync).", "items": {"type": "object", "description": "One ad-exposure path and its outcomes.", "properties": {"path": {"type": ["string", "null"], "description": "Stringified array of [order, label] steps, e.g. '[[1, SP], [2, SD]]'."}, "path_occurrences": {"type": ["number", "null"], "description": "Users who took this path."}, "impressions": {"type": ["number", "null"], "description": "Impressions on the path."}, "imp_total_cost": {"type": ["number", "null"], "description": "Impression cost in the account currency."}, "users_that_purchased": {"type": ["number", "null"], "description": "Users on the path who purchased."}, "sales_amount": {"type": ["number", "null"], "description": "Sales in the account currency."}, "purchases": {"type": ["number", "null"], "description": "Purchases."}, "user_purchase_rate": {"type": ["number", "null"], "description": "users_that_purchased / path_occurrences as a 0-1 fraction."}, "ntb_users_that_purchased": {"type": ["number", "null"], "description": "New-to-brand users who purchased."}, "ntb_sales_amount": {"type": ["number", "null"], "description": "New-to-brand sales in the account currency."}, "ntb_purchases": {"type": ["number", "null"], "description": "New-to-brand purchases."}, "ntb_percentage": {"type": ["number", "null"], "description": "New-to-brand share of purchasers as a 0-1 fraction."}, "reportType": {"type": "string", "description": "Always PATH_TO_CONVERSION."}, "granularity": {"type": "string", "description": "AD_TYPE or CAMPAIGN (same as the top-level granularity)."}, "reportMonth": {"type": "string", "description": "Report month YYYY-MM."}, "instanceId": {"type": "string", "description": "AMC instance the row was synced from."}}, "required": ["reportType", "granularity"]}}, "totals": {"type": "object", "description": "Pinned Total row: column sums over the whole filtered slice, with the two rates recomputed from the sums.", "properties": {"path_occurrences": {"type": "number", "description": "Sum of path_occurrences."}, "impressions": {"type": "number", "description": "Sum of impressions."}, "imp_total_cost": {"type": "number", "description": "Sum of imp_total_cost."}, "users_that_purchased": {"type": "number", "description": "Sum of users_that_purchased."}, "sales_amount": {"type": "number", "description": "Sum of sales_amount."}, "purchases": {"type": "number", "description": "Sum of purchases."}, "ntb_users_that_purchased": {"type": "number", "description": "Sum of ntb_users_that_purchased."}, "ntb_sales_amount": {"type": "number", "description": "Sum of ntb_sales_amount."}, "ntb_purchases": {"type": "number", "description": "Sum of ntb_purchases."}, "user_purchase_rate": {"type": "number", "description": "Sum users_that_purchased / sum path_occurrences (0 when the denominator is 0)."}, "ntb_percentage": {"type": "number", "description": "Sum ntb_users_that_purchased / sum users_that_purchased (0 when the denominator is 0)."}}, "required": ["path_occurrences", "impressions", "imp_total_cost", "users_that_purchased", "sales_amount", "purchases", "ntb_users_that_purchased", "ntb_sales_amount", "ntb_purchases", "user_purchase_rate", "ntb_percentage"]}, "pagination": {"type": "object", "description": "Page position over the filtered slice (always paginated on this surface; page defaults to 1, page_size to 100, max 500).", "properties": {"page": {"type": "integer", "description": "1-based page returned."}, "pageSize": {"type": "integer", "description": "Rows per page."}, "total": {"type": "integer", "description": "Rows in the whole filtered slice."}, "totalPages": {"type": "integer", "description": "Number of pages (0 when total is 0)."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}}, "required": ["granularity", "month", "sortBy", "sortOrder", "rows", "totals", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_report_options": {"post": {"operationId": "get_amc_report_options", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Report Options", "description": "Tool name: `get_amc_report_options` \u00b7 **Scope:** requires `tools:read`.\n\nThe account's AMC setup \u2014 call this before any other AMC tool. Returns the linked AMC instances (`instanceId`, `instanceName`, which one is the default), the available months (`YYYY-MM`, newest first) for each monthly report (path to conversion, time to conversion, custom attribution), and the tentpole events (`eventId`, name, status) the overlap report needs. An empty instances list means no AMC instance is linked.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "Optional AMC instanceId to scope the available months/events to. Defaults to the account's default instance."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "The account's AMC setup for discovery: its instances, the instance the lookup was scoped to, the available months per monthly report, and its tentpole events.", "properties": {"instances": {"type": "array", "description": "Every AMC instance linked to the account; empty when none is linked.", "items": {"type": "object", "description": "One AMC instance row from the account's AMCInstances.", "properties": {"instanceId": {"type": "string", "description": "AMC instanceId to pass to the report and audience tools."}, "instanceName": {"type": ["string", "null"], "description": "Instance display name."}, "isDefault": {"type": "boolean", "description": "True on exactly one row: the account's default (self-owned or first) instance."}}, "required": ["instanceId", "instanceName", "isDefault"]}}, "instanceId": {"type": ["string", "null"], "description": "Instance the months and events were scoped to (requested id or the default); null when no instance is linked."}, "months": {"type": "object", "description": "Available report months (YYYY-MM, newest first) keyed by monthly report key.", "properties": {"path_to_conversion": {"type": "array", "description": "Months with Path to Conversion data; empty if none or the lookup failed.", "items": {"type": "string", "description": "YYYY-MM"}}, "time_to_conversion": {"type": "array", "description": "Months with Time to Conversion data; empty if none or the lookup failed.", "items": {"type": "string", "description": "YYYY-MM"}}, "custom_attribution": {"type": "array", "description": "Months with Custom Attribution data; empty if none or the lookup failed.", "items": {"type": "string", "description": "YYYY-MM"}}}, "required": ["path_to_conversion", "time_to_conversion", "custom_attribution"]}, "tentpole_events": {"type": "array", "description": "The account's active tentpole events (account-level, same for every instance); empty if none or the lookup failed.", "items": {"type": "object", "description": "One tentpole event summary.", "properties": {"eventId": {"type": "string", "description": "Event id to pass as event_id to get_amc_tentpole_overlap."}, "eventName": {"type": ["string", "null"], "description": "Event name, e.g. Prime Day 2026."}, "status": {"type": ["string", "null"], "description": "Sync lifecycle: WAITING, SYNCING, SYNCED or FAILED."}}, "required": ["eventId", "eventName", "status"]}}}, "required": ["instances", "instanceId", "months", "tentpole_events"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_tentpole_overlap": {"post": {"operationId": "get_amc_tentpole_overlap", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Tentpole Overlap", "description": "Tool name: `get_amc_tentpole_overlap` \u00b7 **Scope:** requires `tools:read`.\n\nAMC Tentpole Phase Overlap results for one tentpole event: strategy-path performance across the event's phases, one row per path. Requires `event_id` from `get_amc_report_options`. Metrics include impressions, `unique_viewers`, `unique_purchasers`, `dpv`, `sales`, `ntb_sales`, `ad_spend`, `roas` and rate columns; default sort is `sales`. `page` is 1-based (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "event_id": {"type": "string", "description": "Tentpole event id (from get_amc_report_options \u2192 tentpole_events)."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "sort_by": {"type": "string", "description": "Field to sort by. Defaults to 'sales'. Common: sales, roas, ad_spend, impressions, unique_purchasers."}, "sort_order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page": {"type": "integer", "description": "1-based page number. Defaults to 1 \u2014 increment to page through all rows."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits."}}, "required": ["amazon_account_id", "event_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the AMC Tentpole Phase Overlap results for one event on one instance: the event echoed back, one row per strategy path, and a pagination block (no server totals).", "properties": {"event": {"type": "object", "description": "The tentpole event the results belong to.", "properties": {"_id": {"type": "string", "description": "Event id (the event_id that was requested)."}, "eventName": {"type": ["string", "null"], "description": "Event name."}, "status": {"type": ["string", "null"], "description": "Sync lifecycle: WAITING, SYNCING, SYNCED or FAILED."}, "phases": {"type": ["array", "null"], "description": "The event's three chronological phases.", "items": {"type": "object", "description": "One phase.", "properties": {"name": {"type": "string", "description": "Phase name with its order prefix, e.g. '1 - Lead Up'."}, "startDate": {"type": "string", "description": "YYYY-MM-DD"}, "endDate": {"type": "string", "description": "YYYY-MM-DD"}}, "required": ["name", "startDate", "endDate"]}}, "source": {"type": ["string", "null"], "description": "PREDEFINED (from the catalog) or CUSTOM."}}, "required": ["_id", "eventName", "status", "phases", "source"]}, "sortBy": {"type": "string", "description": "Field the rows are sorted by (requested if whitelisted, else sales)."}, "sortOrder": {"type": "string", "description": "asc or desc."}, "rows": {"type": "array", "description": "The requested page of strategy-path rows (column names as stored by the AMC sync).", "items": {"type": "object", "description": "Performance of one phase sequence (strategy path) across the event.", "properties": {"tentpole_path": {"type": ["string", "null"], "description": "AMC array string of phases, e.g. '[1 - Lead Up, 3 - Lead Out]'."}, "duration_days": {"type": ["number", "null"], "description": "Days covered by the path."}, "impressions": {"type": ["number", "null"], "description": "Impressions."}, "unique_reach_purchase": {"type": ["number", "null"], "description": "Unique users reached (purchase basis)."}, "unique_reach_percentage": {"type": ["number", "null"], "description": "Share of reach as a 0-1 fraction."}, "unique_reach_dpv": {"type": ["number", "null"], "description": "Unique users reached (detail-page-view basis)."}, "unique_viewers": {"type": ["number", "null"], "description": "Unique detail-page viewers."}, "unique_purchasers": {"type": ["number", "null"], "description": "Unique purchasers."}, "unique_ntb_purchasers": {"type": ["number", "null"], "description": "Unique new-to-brand purchasers."}, "unique_ntb_purchasers_percentage": {"type": ["number", "null"], "description": "New-to-brand buyer share as a 0-1 fraction."}, "dpv": {"type": ["number", "null"], "description": "Detail page views."}, "sales": {"type": ["number", "null"], "description": "Sales in the account currency."}, "sales_percentage": {"type": ["number", "null"], "description": "Share of sales as a 0-1 fraction."}, "ntb_sales": {"type": ["number", "null"], "description": "New-to-brand sales in the account currency."}, "ad_spend": {"type": ["number", "null"], "description": "Ad spend in the account currency."}, "roas": {"type": ["number", "null"], "description": "Return on ad spend."}, "purchase_rate": {"type": ["number", "null"], "description": "Purchase rate as a 0-1 fraction."}, "ntb_rate": {"type": ["number", "null"], "description": "New-to-brand rate as a 0-1 fraction."}, "dpv_rate": {"type": ["number", "null"], "description": "Detail-page-view rate as a 0-1 fraction."}, "average_daily_impressions": {"type": ["number", "null"], "description": "Average daily impressions per user."}, "eventId": {"type": "string", "description": "Tentpole event id the row belongs to."}, "instanceId": {"type": "string", "description": "AMC instance the row was synced from."}}, "required": ["eventId"]}}, "pagination": {"type": "object", "description": "Page position over the event's rows (always paginated on this surface; page defaults to 1, page_size to 100, max 500).", "properties": {"page": {"type": "integer", "description": "1-based page returned."}, "pageSize": {"type": "integer", "description": "Rows per page."}, "total": {"type": "integer", "description": "Rows for the event on this instance."}, "totalPages": {"type": "integer", "description": "Number of pages (0 when total is 0)."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}}, "required": ["event", "sortBy", "sortOrder", "rows", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_amc_time_to_conversion": {"post": {"operationId": "get_amc_time_to_conversion", "tags": ["Amazon Marketing Cloud"], "summary": "Get AMC Time to Conversion", "description": "Tool name: `get_amc_time_to_conversion` \u00b7 **Scope:** requires `tools:read`.\n\nAMC Time to Conversion report: how long after ad exposure shoppers converted, as a latency distribution with one row per group \u00d7 time bucket, grouped by `granularity` (`AD_TYPE` default or `CAMPAIGN`). Metrics include `purchases`, `total_brand_purchases`, `avg_time_to_conversion_hours` and `avg_time_to_conversion_per_group`, plus a pinned Total row. `month` is `YYYY-MM` (default: latest available). `page` is 1-based (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "month": {"type": "string", "description": "Report month as YYYY-MM (from get_amc_report_options). Defaults to the latest available month."}, "granularity": {"type": "string", "enum": ["AD_TYPE", "CAMPAIGN"], "description": "Grouping of the latency distribution. AD_TYPE (default) groups by ad type; CAMPAIGN groups by campaign."}, "sort_by": {"type": "string", "description": "Field to sort by. Defaults to the report's default sort."}, "sort_order": {"type": "string", "enum": ["asc", "desc"], "description": "Sort direction. Defaults to 'desc'."}, "page": {"type": "integer", "description": "1-based page number. Defaults to 1 \u2014 increment to page through all rows (see the response's pagination block)."}, "page_size": {"type": "integer", "description": "Rows per page. Defaults to 100, max 500. Keep small for MCP transport limits."}, "filter_model": {"type": "object", "description": "Optional MUI-DataGrid filter model {items:[{field,operator,value}], logicOperator:'and'|'or'}. Only the report's whitelisted columns are applied."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the AMC Time to Conversion report for one (granularity, month): one row per group x latency bucket, server-side purchase totals for the pinned Total row, and a pagination block.", "properties": {"granularity": {"type": "string", "description": "Grouping the rows are for: AD_TYPE or CAMPAIGN."}, "month": {"type": ["string", "null"], "description": "Report month YYYY-MM (latest available when not requested); null when the account has no months."}, "sortBy": {"type": "string", "description": "Field the rows are sorted by (requested if whitelisted, else group_label)."}, "sortOrder": {"type": "string", "description": "asc or desc."}, "rows": {"type": "array", "description": "The requested page of latency-bucket rows (report column names as stored by the AMC sync).", "items": {"type": "object", "description": "Purchases for one group (ad type or campaign) in one time-to-conversion bucket.", "properties": {"group_label": {"type": ["string", "null"], "description": "Ad type or campaign the row belongs to."}, "time_to_conversion": {"type": ["string", "null"], "description": "Latency bucket with a sort-key prefix, e.g. '3 | < 1 MIN'."}, "purchases": {"type": ["number", "null"], "description": "Purchases that converted in this bucket."}, "total_brand_purchases": {"type": ["number", "null"], "description": "Brand purchases in this bucket."}, "avg_time_to_conversion_hours": {"type": ["number", "null"], "description": "Average hours from exposure to conversion in the bucket."}, "avg_time_to_conversion_per_group": {"type": ["number", "null"], "description": "Average time to conversion for the whole group."}, "reportType": {"type": "string", "description": "Always TIME_TO_CONVERSION."}, "granularity": {"type": "string", "description": "AD_TYPE or CAMPAIGN (same as the top-level granularity)."}, "reportMonth": {"type": "string", "description": "Report month YYYY-MM."}, "instanceId": {"type": "string", "description": "AMC instance the row was synced from."}}, "required": ["reportType", "granularity"]}}, "totals": {"type": "object", "description": "Pinned Total row: only the purchase counts are summed (the avg-time columns are averages, not totals).", "properties": {"purchases": {"type": "number", "description": "Sum of purchases over the whole filtered slice."}, "total_brand_purchases": {"type": "number", "description": "Sum of total_brand_purchases over the whole filtered slice."}}, "required": ["purchases", "total_brand_purchases"]}, "pagination": {"type": "object", "description": "Page position over the filtered slice (always paginated on this surface; page defaults to 1, page_size to 100, max 500).", "properties": {"page": {"type": "integer", "description": "1-based page returned."}, "pageSize": {"type": "integer", "description": "Rows per page."}, "total": {"type": "integer", "description": "Rows in the whole filtered slice."}, "totalPages": {"type": "integer", "description": "Number of pages (0 when total is 0)."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}}, "required": ["granularity", "month", "sortBy", "sortOrder", "rows", "totals", "pagination"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_amc_audiences": {"post": {"operationId": "list_amc_audiences", "tags": ["Amazon Marketing Cloud"], "summary": "List AMC Audiences", "description": "Tool name: `list_amc_audiences` \u00b7 **Scope:** requires `tools:read`.\n\nThe audiences built on one AMC instance (rule-based and lookalike): name, description, type, status (`SUCCEEDED` = usable; `FAILED` with Amazon's `statusReason`, usually the 2,000-user minimum; `PENDING` / `RUNNING` = still building), `audienceCount`, activation (Sponsored Ads or DSP), the Amazon audience id used for targeting, time window, refresh rate and SQL. Filters (AND-ed): `status`, `audience_type`, `name_query`, `audience_ids`. `instance_id` defaults to the account's default instance. Paginated \u2014 `page` is 1-based here (`page_size` 50, max 200).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "instance_id": {"type": "string", "description": "AMC instanceId (from get_amc_report_options). Defaults to the account's default instance."}, "status": {"description": "Only these statuses: SUCCEEDED, FAILED, PENDING, RUNNING. A list or a comma-separated string.", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "audience_type": {"description": "Only this type: RULE_BASED or LOOKALIKE. A list or a comma-separated string.", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "name_query": {"type": "string", "description": "Case-insensitive substring to match against the audience name or description."}, "audience_ids": {"description": "Exact audienceId or audienceExecutionId values, from a mention or an earlier result.", "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]}, "page": {"type": "integer", "description": "1-based page (default 1)."}, "page_size": {"type": "integer", "description": "Rows per page (default 50, max 200)."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "Normal result: one page of the instance's AMC audiences (filtered, newest first) with a summary and pagination block.", "properties": {"instanceId": {"type": "string", "description": "The instance the audiences were read from (requested or default)."}, "instanceName": {"type": ["string", "null"], "description": "That instance's display name."}, "instances": {"type": "array", "description": "Every AMC instance linked to the account.", "items": {"type": "object", "description": "One AMC instance row.", "properties": {"instanceId": {"type": "string", "description": "AMC instanceId."}, "instanceName": {"type": ["string", "null"], "description": "Instance display name."}, "isDefault": {"type": "boolean", "description": "True on the account's default instance."}}, "required": ["instanceId", "instanceName", "isDefault"]}}, "summary": {"type": "object", "description": "Counts over the instance's audiences before pagination.", "properties": {"total": {"type": "integer", "description": "All audiences on the instance, before filters."}, "matched": {"type": "integer", "description": "Audiences matching the request filters."}, "byStatus": {"type": "object", "description": "Count of all audiences per status (UNKNOWN when the row has none).", "additionalProperties": {"type": "integer", "description": "Number of audiences with this status."}}}, "required": ["total", "matched", "byStatus"]}, "audiences": {"type": "array", "description": "The requested page of matching audiences, newest createTime first.", "items": {"type": "object", "description": "One AMC audience as the AMC page shows it (Amazon's mirror row plus SellerMate fields).", "properties": {"audienceId": {"type": ["string", "null"], "description": "Amazon's audience id."}, "audienceExecutionId": {"type": ["string", "null"], "description": "Amazon's audience execution id (the create/update handle)."}, "name": {"type": ["string", "null"], "description": "Audience name."}, "description": {"type": ["string", "null"], "description": "Audience description."}, "type": {"type": ["string", "null"], "description": "RULE_BASED or LOOKALIKE."}, "status": {"type": ["string", "null"], "description": "Build status: SUCCEEDED, FAILED, PENDING or RUNNING."}, "statusReason": {"type": ["string", "null"], "description": "Amazon's reason when the build failed."}, "audienceCount": {"type": ["number", "null"], "description": "Amazon's rounded size; withheld under its privacy threshold."}, "activatedIn": {"type": ["string", "null"], "description": "Sponsored Ads or Amazon DSP (else the raw advertiserType)."}, "advertiserId": {"type": ["string", "null"], "description": "Advertiser the audience is activated under."}, "amazonAudienceId": {"type": ["string", "null"], "description": "Amazon's id for the built audience, used by SD/SB/DSP targeting."}, "instanceId": {"type": "string", "description": "Instance the audience belongs to."}, "instanceName": {"type": ["string", "null"], "description": "That instance's display name."}, "createTime": {"type": ["string", "null"], "description": "ISO 8601 datetime the audience was created."}, "lastRefreshedTime": {"type": ["string", "null"], "description": "ISO 8601 datetime of the last refresh."}, "refreshRateDays": {"type": ["integer", "null"], "description": "How often Amazon rebuilds it, in days."}, "timeWindowStart": {"type": ["string", "null"], "description": "ISO 8601 datetime: start of the lookback window."}, "timeWindowEnd": {"type": ["string", "null"], "description": "ISO 8601 datetime: end of the lookback window."}, "timeWindowRelative": {"type": ["boolean", "null"], "description": "Whether the window slides forward on each refresh."}, "lookalikeExpectedReach": {"type": ["string", "null"], "description": "Lookalike reach level (MOST_SIMILAR ... MOST_BROAD); null for rule-based."}, "builtWithRuleBuilder": {"type": "boolean", "description": "True when a SellerMate rule payload is stored for it."}, "query": {"type": ["string", "null"], "description": "The audience's AMC SQL."}}, "required": ["audienceId", "audienceExecutionId", "name", "description", "type", "status", "statusReason", "audienceCount", "activatedIn", "advertiserId", "amazonAudienceId", "instanceId", "instanceName", "createTime", "lastRefreshedTime", "refreshRateDays", "timeWindowStart", "timeWindowEnd", "timeWindowRelative", "lookalikeExpectedReach", "builtWithRuleBuilder", "query"]}}, "pagination": {"type": "object", "description": "Page position over the filtered audiences.", "properties": {"page": {"type": "integer", "description": "1-based page returned."}, "pageSize": {"type": "integer", "description": "Rows per page (1-200)."}, "totalMatched": {"type": "integer", "description": "Audiences matching the filters."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}}, "required": ["page", "pageSize", "totalMatched", "hasMore"]}}, "required": ["instanceId", "instanceName", "instances", "summary", "audiences", "pagination"]}, {"type": "object", "description": "Early return when the account has no AMC instance linked: empty lists plus a note (no instanceName, no pagination).", "properties": {"instances": {"type": "array", "description": "Always empty.", "items": {"type": "object"}}, "instanceId": {"type": "null", "description": "Always null."}, "audiences": {"type": "array", "description": "Always empty.", "items": {"type": "object"}}, "summary": {"type": "object", "description": "Zero counts.", "properties": {"total": {"type": "integer", "description": "Always 0."}, "byStatus": {"type": "object", "description": "Always empty.", "additionalProperties": {"type": "integer"}}}, "required": ["total", "byStatus"]}, "note": {"type": "string", "description": "Explains that an AMC instance must be connected first."}}, "required": ["instances", "instanceId", "audiences", "summary", "note"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_vendor_inventory": {"post": {"operationId": "get_vendor_inventory", "tags": ["Vendor Central"], "summary": "Get Vendor Inventory", "description": "Tool name: `get_vendor_inventory` \u00b7 **Scope:** requires `tools:read`.\n\nVendor Central on-hand inventory per ASIN: sellable (available) and unsellable units, with product name/image. Choose the `sourcing` (default) or `manufacturing` view. Returns `{connected: false}` with a connect URL if the account has no Vendor Central connection. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "inventory_type": {"type": "string", "enum": ["sourcing", "manufacturing"], "description": "Vendor inventory view. Defaults to 'sourcing'."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Optional: filter to specific ASINs."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Vendor Central on-hand inventory per ASIN (sellable/unsellable units) for the sourcing or manufacturing view, or a connect prompt when no Vendor Central account is linked.", "oneOf": [{"type": "object", "description": "No active Vendor Central account is linked to this Amazon account.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "message": {"type": "string", "description": "Explanation that Vendor Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Vendor Central can be connected."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "message", "connectUrl", "account"]}, {"type": "object", "description": "Vendor Central connected; one page of per-ASIN inventory rows.", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "inventoryType": {"type": "string", "description": "sourcing or manufacturing."}, "items": {"type": "array", "description": "Rows for this page (after optional asins filter).", "items": {"type": "object", "description": "Inventory summed across vendor accounts for one ASIN, with product name/image and tags.", "properties": {"asin": {"type": "string", "description": "ASIN."}, "itemName": {"type": "string", "description": "Item name from the vendor product listing; empty when unknown."}, "mainImage": {"type": ["string", "object", "null"], "description": "Main image as stored in the vendor product listing; empty string when unknown."}, "sellableOnHandInventoryUnits": {"type": "number", "description": "Sellable on-hand units."}, "unsellableOnHandInventoryUnits": {"type": "number", "description": "Unsellable on-hand units."}, "latestUpdated": {"type": ["string", "null"], "description": "last_updated_date of the first report row seen, stringified."}, "timeWindowStart": {"type": ["string", "null"], "description": "time_window_start of the first report row seen, stringified."}, "tags": {"type": "array", "description": "Active product tag assignments (tagsEntity rows joined with the tag).", "items": {"type": "object", "description": "One tagsEntity document plus joined tag fields; other stored fields pass through.", "properties": {"_id": {"type": "string", "description": "Tag assignment id."}, "tagId": {"type": "string", "description": "Tag id."}, "entity": {"type": "string", "description": "Entity key (the ASIN)."}, "value": {"type": ["string", "null"], "description": "Tag label."}, "color": {"type": ["string", "null"], "description": "Tag text colour."}, "bgColor": {"type": ["string", "null"], "description": "Tag background colour."}, "tagCreatedAt": {"type": ["string", "null"], "description": "Tag creation time, stringified."}}}}}, "required": ["asin", "itemName", "mainImage", "sellableOnHandInventoryUnits", "unsellableOnHandInventoryUnits", "latestUpdated", "timeWindowStart"]}}, "pagination": {"type": "object", "description": "Page metadata from the vendor _paginate helper (no cursor).", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total rows in the full set."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "inventoryType", "items", "pagination", "total", "account"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_vendor_sales_performance": {"post": {"operationId": "get_vendor_sales_performance", "tags": ["Vendor Central"], "summary": "Get Vendor Sales Performance", "description": "Tool name: `get_vendor_sales_performance` \u00b7 **Scope:** requires `tools:read`.\n\nVendor Central sales per ASIN over a date range: ordered units + ordered revenue (manufacturing view), shipped units + shipped revenue + shipped COGS + customer returns (sourcing view), and glance views. Note: vendor traffic is glance views only \u2014 sessions, page views, and conversion are not available for vendor accounts. Paginated; summary covers the full set.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "Start date in YYYY-MM-DD format."}, "end_date": {"type": "string", "description": "End date in YYYY-MM-DD format."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Optional: filter to specific ASINs."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id", "start_date", "end_date"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Vendor Central sales/traffic per ASIN over a date range (ordered, shipped, COGS, returns, glance views) with a full-set summary, or a connect prompt when no Vendor Central account is linked.", "oneOf": [{"type": "object", "description": "No active Vendor Central account is linked to this Amazon account.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "message": {"type": "string", "description": "Explanation that Vendor Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Vendor Central can be connected."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "message", "connectUrl", "account"]}, {"type": "object", "description": "Vendor Central connected; one page of per-ASIN rows sorted by shipped revenue desc.", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "data": {"type": "array", "description": "Rows for this page.", "items": {"type": "object", "description": "Metrics summed over the date range for one ASIN.", "properties": {"asin": {"type": "string", "description": "ASIN."}, "orderedUnits": {"type": "number", "description": "Ordered units (manufacturing/retail view)."}, "orderedRevenueAmount": {"type": "number", "description": "Ordered revenue, 2 decimals."}, "shippedUnits": {"type": "number", "description": "Shipped units (sourcing view)."}, "shippedRevenueAmount": {"type": "number", "description": "Shipped revenue, 2 decimals."}, "shippedCogsAmount": {"type": "number", "description": "Shipped cost of goods, 2 decimals."}, "customerReturns": {"type": "number", "description": "Customer returns (sourcing view only)."}, "glanceViews": {"type": "number", "description": "Glance views (the only traffic metric synced)."}, "itemName": {"type": "string", "description": "Item name from the vendor product listing; empty when unknown."}, "mainImage": {"type": ["string", "object", "null"], "description": "Main image as stored in the vendor product listing; empty string when unknown."}}, "required": ["asin", "orderedUnits", "orderedRevenueAmount", "shippedUnits", "shippedRevenueAmount", "shippedCogsAmount", "customerReturns", "glanceViews", "itemName", "mainImage"]}}, "summary": {"type": "object", "description": "Totals over the FULL result set (not just this page).", "properties": {"orderedUnits": {"type": "number", "description": "Sum of ordered units."}, "orderedRevenueAmount": {"type": "number", "description": "Sum of ordered revenue, 2 decimals."}, "shippedUnits": {"type": "number", "description": "Sum of shipped units."}, "shippedRevenueAmount": {"type": "number", "description": "Sum of shipped revenue, 2 decimals."}, "shippedCogsAmount": {"type": "number", "description": "Sum of shipped COGS, 2 decimals."}, "customerReturns": {"type": "number", "description": "Sum of customer returns."}, "glanceViews": {"type": "number", "description": "Sum of glance views."}, "asins": {"type": "integer", "description": "Number of ASINs in the full set."}}, "required": ["orderedUnits", "orderedRevenueAmount", "shippedUnits", "shippedRevenueAmount", "shippedCogsAmount", "customerReturns", "glanceViews", "asins"]}, "dateRange": {"type": "object", "description": "Echo of the requested date range.", "properties": {"start": {"type": "string", "description": "Start date, YYYY-MM-DD."}, "end": {"type": "string", "description": "End date, YYYY-MM-DD."}}, "required": ["start", "end"]}, "pagination": {"type": "object", "description": "Page metadata from the vendor _paginate helper (no cursor).", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total rows in the full set."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "data", "summary", "dateRange", "pagination", "total", "account"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_vendor_products": {"post": {"operationId": "list_vendor_products", "tags": ["Vendor Central"], "summary": "List Vendor Products", "description": "Tool name: `list_vendor_products` \u00b7 **Scope:** requires `tools:read`.\n\nVendor Central product catalog (ASIN, item name, image) \u2014 use it to discover ASINs for the other vendor tools. Paginated.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Optional: filter to specific ASINs."}, "page_size": {"type": "integer", "description": "Number of results per page. Defaults to 100. Max 500."}, "page": {"type": "integer", "description": "Page number (0-indexed). Defaults to 0."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Vendor Central product catalog (ASIN, item name, image), de-duplicated by ASIN and paginated, or a connect prompt when no Vendor Central account is linked.", "oneOf": [{"type": "object", "description": "No active Vendor Central account is linked to this Amazon account.", "properties": {"connected": {"type": "boolean", "description": "Always false in this branch."}, "message": {"type": "string", "description": "Explanation that Vendor Central must be connected."}, "connectUrl": {"type": "string", "description": "Platform URL where Vendor Central can be connected."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "message", "connectUrl", "account"]}, {"type": "object", "description": "Vendor Central connected; one page of catalog rows.", "properties": {"connected": {"type": "boolean", "description": "Always true."}, "products": {"type": "array", "description": "Rows for this page (after optional asins filter).", "items": {"type": "object", "description": "One vendor product listing (first occurrence per ASIN).", "properties": {"asin": {"type": "string", "description": "ASIN."}, "itemName": {"type": "string", "description": "Item name; empty string when unset."}, "mainImage": {"type": ["string", "object", "null"], "description": "Main image as stored in VendorProductListingV1; empty string when unset."}}, "required": ["asin", "itemName", "mainImage"]}}, "pagination": {"type": "object", "description": "Page metadata from the vendor _paginate helper (no cursor).", "properties": {"page": {"type": "integer", "description": "0-indexed page returned."}, "pageSize": {"type": "integer", "description": "Effective page size (1-500)."}, "total": {"type": "integer", "description": "Total rows in the full set."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether a further page exists."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "account": {"type": "object", "description": "The Amazon account the result is scoped to.", "properties": {"id": {"type": "string", "description": "Amazon account id."}, "name": {"type": "string", "description": "Account name; empty string when unset."}}, "required": ["id", "name"]}}, "required": ["connected", "products", "pagination", "total", "account"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/archive_memory_file": {"post": {"operationId": "archive_memory_file", "tags": ["Knowledge Files"], "summary": "Archive Memory File", "description": "Tool name: `archive_memory_file` \u00b7 **Scope:** requires `tools:write`.\n\nArchive (delete) a memory file by `fileId`: hidden from every list and tool; nothing is removed from storage. Needs a key with write scope.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"fileId": {"type": "string", "description": "The fileId from list_knowledge_and_memory_files."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["fileId", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Confirmation that a memory file was archived (hidden from the list and every memory-file tool).", "properties": {"status": {"type": "string", "enum": ["archived"], "description": "Always 'archived' on success."}, "fileId": {"type": "string", "description": "The archived file's id."}, "title": {"type": "string", "description": "The archived file's title; falls back to fileName."}, "message": {"type": "string", "description": "Human-readable confirmation that the file is hidden."}}, "required": ["status", "fileId", "title", "message"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_memory_file": {"post": {"operationId": "create_memory_file", "tags": ["Knowledge Files"], "summary": "Create Memory File", "description": "Tool name: `create_memory_file` \u00b7 **Scope:** requires `tools:write`.\n\nSave a new memory file (`md`, `txt` or `docx` from Markdown) with a `title`, `content` and optional `description`. Up to 100,000 characters; 50 files per account; a title already in use is refused. Needs a key with write scope.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string", "description": "Clear, specific human-readable title, e.g. 'Belt campaign bidding rules'. Max 200 characters."}, "file_type": {"type": "string", "enum": ["docx", "md", "txt"], "description": "'md' (Markdown), 'txt' (plain text) or 'docx' (Word, from Markdown content)."}, "content": {"type": "string", "description": "The full text of the file. Markdown for 'md' and 'docx'."}, "description": {"type": "string", "description": "One line on what the file contains and when it is useful (max 500 characters)."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["title", "file_type", "content", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Confirmation that a new memory file was saved, with its id and size figures.", "properties": {"status": {"type": "string", "enum": ["saved"], "description": "Always 'saved' on success."}, "fileId": {"type": "string", "description": "The new file's id."}, "title": {"type": "string", "description": "The saved title."}, "fileName": {"type": "string", "description": "Generated file name (title slug + extension)."}, "fileType": {"type": "string", "enum": ["md", "txt", "docx"], "description": "The file_type that was saved."}, "characters": {"type": "integer", "description": "Length of the submitted content in characters."}, "words": {"type": "integer", "description": "Whitespace-separated word count of the content."}, "sizeKB": {"type": "number", "description": "Stored file size in kilobytes, rounded to one decimal."}, "message": {"type": "string", "description": "Human-readable confirmation of where the file was saved."}}, "required": ["status", "fileId", "title", "fileName", "fileType", "characters", "words", "sizeKB", "message"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/find_in_knowledge_and_memory_files": {"post": {"operationId": "find_in_knowledge_and_memory_files", "tags": ["Knowledge Files"], "summary": "Find in Knowledge & Memory Files", "description": "Tool name: `find_in_knowledge_and_memory_files` \u00b7 **Scope:** requires `tools:read`.\n\nSearch up to 5 documents (`fileIds`) for 1\u201310 words or phrases (`find`): per file a match count, per-term counts and the top 10 matching lines with the text around them, numbered by line.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"fileIds": {"type": "array", "items": {"type": "string"}, "description": "1\u20135 fileIds from list_knowledge_and_memory_files."}, "find": {"type": "array", "items": {"type": "string"}, "description": "1\u201310 words, phrases or short sentences to look for (2\u2013200 characters each)."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["fileIds", "find", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Plain-text search results: for each requested file, its matching lines as numbered context blocks, or a per-file error.", "properties": {"find": {"type": "array", "items": {"type": "string", "description": "One search term."}, "description": "The de-duplicated, trimmed terms that were searched."}, "files": {"type": "array", "description": "One entry per requested fileId, in request order.", "items": {"type": "object", "description": "Search result for one file; has 'error' instead of matches when the file is missing, archived or tabular.", "properties": {"fileId": {"type": "string", "description": "The requested file id."}, "title": {"type": "string", "description": "File title; absent on a not-found error."}, "error": {"type": "string", "description": "Why this file was not searched (not found / archived / tabular); present only on failure."}, "version": {"type": "integer", "description": "The file's current version that was searched."}, "totalLines": {"type": "integer", "description": "Total lines in the document."}, "matchCount": {"type": "integer", "description": "Number of lines matching any term."}, "termCounts": {"type": "object", "description": "Matching-line count per term.", "additionalProperties": {"type": "integer", "description": "Lines matching this term."}}, "shown": {"type": "integer", "description": "Number of matching lines shown inside blocks."}, "blocks": {"type": "array", "description": "Context blocks around the top matches, in file order.", "items": {"type": "object", "description": "One contiguous stretch of numbered lines around one or more matches.", "properties": {"startLine": {"type": "integer", "description": "First line of the block (1-based)."}, "endLine": {"type": "integer", "description": "Last line of the block (1-based)."}, "matchLines": {"type": "array", "items": {"type": "integer", "description": "A matching line number."}, "description": "Line numbers inside the block that matched."}, "text": {"type": "string", "description": "Block text, each line as 'N| text', with ellipses at cut edges."}}, "required": ["startLine", "endLine", "matchLines", "text"]}}, "truncated": {"type": "boolean", "description": "True when matching lines exist beyond those shown."}, "moreMatchLines": {"type": "array", "items": {"type": "integer", "description": "A matching line number not shown."}, "description": "Up to 50 further matching line numbers; present only when truncated."}, "moreMatchCount": {"type": "integer", "description": "Count of matching lines not shown; present only when truncated."}, "note": {"type": "string", "description": "Hint to narrow terms or read around a line; present only when truncated."}}, "required": ["fileId"]}}, "note": {"type": "string", "description": "Hint on reading more around a block with get_knowledge_and_memory_file_content."}}, "required": ["find", "files", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_knowledge_and_memory_file_content": {"post": {"operationId": "get_knowledge_and_memory_file_content", "tags": ["Knowledge Files"], "summary": "Get Knowledge & Memory File Content", "description": "Tool name: `get_knowledge_and_memory_file_content` \u00b7 **Scope:** requires `tools:read`.\n\nRead one uploaded file's content by `fileId` (from `list_knowledge_and_memory_files`). Documents: the whole text, or pass `start_line` / `end_line` (at most 800 lines) for part of it. Tabular files return CSV text with a `totalRows` count and a `truncated` flag past the size cap.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"fileId": {"type": "string", "description": "The fileId from list_knowledge_and_memory_files."}, "version": {"type": "integer", "description": "Optional: an older version to read. Omit for the current version."}, "line_numbers": {"type": "boolean", "description": "Optional: prefix each line with 'N| ' (documents only)."}, "start_line": {"type": "integer", "description": "Optional: first line to read (1-based); negative = the last N lines. Documents only."}, "end_line": {"type": "integer", "description": "Optional: last line to read (inclusive); at most 800 lines per call."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["fileId", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "The content of one memory file: a whole document, a numbered line range of a document, or a tabular file as CSV text.", "oneOf": [{"type": "object", "description": "Whole-document read (fileKind 'document', no start_line / end_line).", "properties": {"fileId": {"type": "string", "description": "The requested file id."}, "title": {"type": "string", "description": "Human-readable title; falls back to fileName."}, "fileName": {"type": "string", "description": "Stored file name with extension."}, "fileKind": {"type": "string", "enum": ["document"], "description": "Always 'document' on this branch."}, "content": {"type": "string", "description": "Full extracted text; 'N| text' per line when line_numbers=true."}, "version": {"type": "integer", "description": "The version whose content was returned."}, "currentVersion": {"type": "integer", "description": "The file's current (latest) version number."}}, "required": ["fileId", "title", "fileName", "fileKind", "content", "version", "currentVersion"]}, {"type": "object", "description": "Line-range read of a document (start_line and/or end_line given).", "properties": {"fileId": {"type": "string", "description": "The requested file id."}, "title": {"type": "string", "description": "Human-readable title; falls back to fileName."}, "fileName": {"type": "string", "description": "Stored file name with extension."}, "fileKind": {"type": "string", "enum": ["document"], "description": "Always 'document' on this branch."}, "totalLines": {"type": "integer", "description": "Total number of lines in the document."}, "startLine": {"type": "integer", "description": "First line returned (1-based, inclusive)."}, "endLine": {"type": "integer", "description": "Last line returned (1-based, inclusive); at most 800 lines per call."}, "hasMore": {"type": "boolean", "description": "True when lines after endLine exist."}, "content": {"type": "string", "description": "The requested lines, each as 'N| text'."}, "version": {"type": "integer", "description": "The version whose content was returned."}, "currentVersion": {"type": "integer", "description": "The file's current (latest) version number."}, "note": {"type": "string", "description": "Guidance on reading the rest; present when the range is partial."}}, "required": ["fileId", "title", "fileName", "fileKind", "totalLines", "startLine", "endLine", "hasMore", "content", "version", "currentVersion"]}, {"type": "object", "description": "Tabular file (CSV / Excel first sheet) returned as CSV text, capped at 100,000 characters.", "properties": {"fileId": {"type": "string", "description": "The requested file id."}, "title": {"type": "string", "description": "Human-readable title; falls back to fileName."}, "fileName": {"type": "string", "description": "Stored file name with extension."}, "fileKind": {"type": "string", "enum": ["tabular"], "description": "Always 'tabular' on this branch."}, "totalRows": {"type": "integer", "description": "Number of data rows in the parsed table."}, "content": {"type": "string", "description": "The table as CSV text, cut at 100,000 characters."}, "version": {"type": "integer", "description": "The version whose content was returned."}, "currentVersion": {"type": "integer", "description": "The file's current (latest) version number."}, "truncated": {"type": "boolean", "description": "True when the CSV exceeded the cap; present only then."}, "truncatedNote": {"type": "string", "description": "Explains the truncation; present only when truncated."}}, "required": ["fileId", "title", "fileName", "fileKind", "totalRows", "content", "version", "currentVersion"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_knowledge_and_memory_file_details": {"post": {"operationId": "get_knowledge_and_memory_file_details", "tags": ["Knowledge Files"], "summary": "Get Knowledge & Memory File Details", "description": "Tool name: `get_knowledge_and_memory_file_details` \u00b7 **Scope:** requires `tools:read`.\n\nOne file's details by `fileId`: the list fields plus `currentVersion` and `lastEditedAt`; `include_history=true` adds its kept versions.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"fileId": {"type": "string", "description": "The fileId from list_knowledge_and_memory_files."}, "include_history": {"type": "boolean", "description": "Optional: also return the file's kept versions, newest first."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["fileId", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One memory file's metadata plus its current version, last edit time and (optionally) its kept version history.", "properties": {"fileId": {"type": "string", "description": "The file's id."}, "title": {"type": "string", "description": "Human-readable title; falls back to fileName."}, "fileName": {"type": "string", "description": "Stored file name with extension."}, "fileKind": {"type": "string", "enum": ["document", "tabular"], "description": "'document' (text) or 'tabular' (CSV / Excel)."}, "source": {"type": "string", "enum": ["upload", "ai_agent", "mcp"], "description": "Who created the file."}, "contentType": {"type": "string", "description": "MIME content type of the stored file."}, "fileSize": {"type": "integer", "description": "File size in bytes (0 when unknown)."}, "description": {"type": "string", "description": "User-written description; empty when none."}, "contextSnippet": {"type": "string", "description": "Column names (tabular) or opening lines (document); empty when none."}, "summary": {"type": "object", "description": "Dataset summary for tabular files; empty object otherwise.", "additionalProperties": {"description": "Summary field (see tool description)."}}, "tokenCount": {"type": "integer", "description": "Approximate token count of the content."}, "createdAt": {"type": "string", "description": "Creation time as a Python datetime string; empty when unknown."}, "lineCount": {"type": ["integer", "null"], "description": "Line count; documents saved since 2026-10-19 only."}, "charCount": {"type": "integer", "description": "Character count; documents saved since 2026-10-19 only."}, "currentVersion": {"type": "integer", "description": "The file's current (latest) version number; 1 for unversioned files."}, "lastEditedAt": {"type": ["string", "null"], "description": "Last edit time as a datetime string; null when never edited."}, "versions": {"type": "array", "description": "Kept versions, newest first; present only when include_history=true.", "items": {"type": "object", "description": "One kept version record (no S3 key, no diff body).", "properties": {"version": {"type": "integer", "description": "Version number (1..N)."}, "isCurrent": {"type": "boolean", "description": "True when this is the file's current version."}, "action": {"type": ["string", "null"], "description": "'create', 'update' or 'revert'."}, "changes": {"type": "array", "items": {"type": "string", "description": "'content', 'title' or 'description'."}, "description": "Which fields this version changed."}, "title": {"type": ["string", "null"], "description": "The file's title at this version."}, "description": {"type": "string", "description": "The file's description at this version."}, "fileName": {"type": ["string", "null"], "description": "File name at this version."}, "fileSize": {"type": "integer", "description": "File size in bytes at this version."}, "changeSummary": {"type": "string", "description": "One-line summary of the change; empty for v1."}, "diffStats": {"type": ["object", "null"], "description": "Lines added / removed versus the previous version; null for v1.", "properties": {"added": {"type": "integer", "description": "Lines added."}, "removed": {"type": "integer", "description": "Lines removed."}}}, "actor": {"type": ["string", "null"], "description": "Who made the change: upload, ai_agent, mcp or user."}, "createdAt": {"type": ["string", "null"], "description": "When the version was written, ISO 8601."}}, "required": ["version", "isCurrent", "action", "changes", "title", "description", "fileName", "fileSize", "changeSummary", "diffStats", "actor", "createdAt"]}}, "note": {"type": "string", "description": "Retention note (last 15 versions kept); present only with include_history."}}, "required": ["fileId", "title", "fileName", "fileKind", "source", "contentType", "fileSize", "description", "contextSnippet", "summary", "tokenCount", "createdAt", "currentVersion", "lastEditedAt"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_knowledge_and_memory_files": {"post": {"operationId": "list_knowledge_and_memory_files", "tags": ["Knowledge Files"], "summary": "List Knowledge & Memory Files", "description": "Tool name: `list_knowledge_and_memory_files` \u00b7 **Scope:** requires `tools:read`.\n\nList the knowledge-base / memory files uploaded to SellerMate for this account: `fileId`, title, file kind (document / tabular), size, description, context snippet, token count.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "All active knowledge-base and memory files on the account, with metadata and a count.", "properties": {"files": {"type": "array", "description": "One entry per active memory file on this account.", "items": {"type": "object", "description": "One memory file's metadata (no content).", "properties": {"fileId": {"type": "string", "description": "The file's id, used by the other memory-file tools."}, "title": {"type": "string", "description": "Human-readable title; falls back to fileName."}, "fileName": {"type": "string", "description": "Stored file name with extension."}, "fileKind": {"type": "string", "enum": ["document", "tabular"], "description": "'document' (text) or 'tabular' (CSV / Excel)."}, "source": {"type": "string", "enum": ["upload", "ai_agent", "mcp"], "description": "Who created the file."}, "contentType": {"type": "string", "description": "MIME content type of the stored file."}, "fileSize": {"type": "integer", "description": "File size in bytes (0 when unknown)."}, "description": {"type": "string", "description": "User-written description of the file; empty when none."}, "contextSnippet": {"type": "string", "description": "Column names (tabular) or opening lines (document); empty when none."}, "summary": {"type": "object", "description": "Dataset summary for tabular files; empty object otherwise.", "additionalProperties": {"description": "Summary field (see tool description)."}}, "tokenCount": {"type": "integer", "description": "Approximate token count of the content."}, "createdAt": {"type": "string", "description": "Creation time as a Python datetime string (e.g. '2026-10-19 10:11:12+00:00'); empty when unknown."}, "lineCount": {"type": ["integer", "null"], "description": "Line count; documents saved since 2026-10-19 only."}, "charCount": {"type": "integer", "description": "Character count; documents saved since 2026-10-19 only."}}, "required": ["fileId", "title", "fileName", "fileKind", "source", "contentType", "fileSize", "description", "contextSnippet", "summary", "tokenCount", "createdAt"]}}, "total": {"type": "integer", "description": "Number of entries in files."}}, "required": ["files", "total"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_memory_file": {"post": {"operationId": "update_memory_file", "tags": ["Knowledge Files"], "summary": "Update Memory File", "description": "Tool name: `update_memory_file` \u00b7 **Scope:** requires `tools:write`.\n\nChange a memory file by `fileId`: content (`mode` edit / append / replace \u2014 Markdown and text files), `title`, `description`, or `mode: \"revert\"` with a `version`. Each change is a new version (last 15 kept). Needs a key with write scope.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"fileId": {"type": "string", "description": "The fileId from list_knowledge_and_memory_files."}, "mode": {"type": "string", "enum": ["edit", "append", "replace", "revert"], "description": "How to change the content, or 'revert' to restore `version`. Omit when only the title / description change."}, "edits": {"type": "array", "description": "mode 'edit': all find/replace pairs OR all line ranges (not mixed).", "items": {"type": "object", "properties": {"find": {"type": "string", "description": "Exact text from the file; must match once (unless replace_all)."}, "replace_all": {"type": "boolean", "description": "Find/replace only: true changes every match (the user said all / everywhere)."}, "start_line": {"type": "integer", "description": "First line to replace (1-based)."}, "end_line": {"type": "integer", "description": "Last line to replace (inclusive)."}, "replace": {"type": "string", "description": "The new text (\"\" deletes it)."}}, "required": ["replace"]}}, "content": {"type": "string", "description": "mode 'append': text to add at the end. mode 'replace': the whole new file."}, "title": {"type": "string", "description": "New title \u2014 only when the user asks to rename. Leave empty otherwise."}, "description": {"type": "string", "description": "New description \u2014 only when the user asks to change it. Leave empty otherwise."}, "change_summary": {"type": "string", "description": "One line on what changed (max 200 characters)."}, "version": {"type": "integer", "description": "mode 'revert' only: the kept version to restore."}, "base_version": {"type": "integer", "description": "The `version` you read. Required for mode 'replace'; optional otherwise."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["fileId", "change_summary", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Confirmation that a memory file was changed (or an earlier version restored) as a new version, with the diff size.", "properties": {"status": {"type": "string", "enum": ["updated", "reverted"], "description": "'updated' for content/title/description changes; 'reverted' for mode 'revert'."}, "fileId": {"type": "string", "description": "The changed file's id."}, "title": {"type": "string", "description": "The file's title after the change."}, "version": {"type": "integer", "description": "The new version number written by this call."}, "changes": {"type": "array", "items": {"type": "string", "description": "'content', 'title' or 'description'."}, "description": "Which fields this version changed."}, "linesAdded": {"type": "integer", "description": "Lines added versus the previous version (0 when content unchanged)."}, "linesRemoved": {"type": "integer", "description": "Lines removed versus the previous version (0 when content unchanged)."}, "message": {"type": "string", "description": "Human-readable summary of what changed, including multi-match replace counts."}, "replacements": {"type": "array", "description": "One entry per find/replace edit applied; present only for mode 'edit' with find/replace edits.", "items": {"type": "object", "description": "How many places one find text matched.", "properties": {"find": {"type": "string", "description": "The find text, cut to 120 characters."}, "count": {"type": "integer", "description": "Number of matches in the file (1 unless replace_all)."}}, "required": ["find", "count"]}}}, "required": ["status", "fileId", "title", "version", "changes", "linesAdded", "linesRemoved", "message"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_automation": {"post": {"operationId": "create_automation", "tags": ["Automation & Dayparting"], "summary": "Create Automation", "description": "Tool name: `create_automation` \u00b7 **Scope:** requires `tools:write`.\n\nCreate an automation rule. Required: `automate_for` (the category, which fixes the valid condition fields, actions and scope), a `name` unique among the account's live automations, `conditions` (the if / else-if / else rule tree), `rule_schedule` (`{type: \"weekly\" | \"monthly\", days: [...]}`; Campaign rules also need `timeSlots`) and a scope \u2014 `selected_campaigns` (or `selected_campaign_tags`), or `selected_mapping` for Mapped Harvesting. Everything is validated against the rule editor's whitelists. For safety `status` defaults to `INACTIVE`, so a new rule does nothing until it is activated (here or via `update_automation`); each action's `isAutoExecute` defaults to true for Inventory and Campaign and false elsewhere, where the rule only reports what it would do. Campaign rules take `selected_campaigns` as `{campaignId, baseBudget}` objects. Omitted lookback, processing-time and notification fields get the editor's defaults, and the response lists which were defaulted.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"automate_for": {"type": "string", "description": "The automation category, one of: Keyword Targets, All Targets, Search Terms, Mapped Harvesting, Placements, Ad Products, Campaign, Inventory. Selects which condition fields, actions and scope fields are valid \u2014 see update_automation's per-category reference."}, "name": {"type": "string", "description": "Automation name. Must not match an existing live automation in the account."}, "description": {"type": "string"}, "status": {"type": "string", "enum": ["ACTIVE", "INACTIVE"], "description": "Defaults to 'INACTIVE' \u2014 the rule is created but does not run. Pass 'ACTIVE' to start it immediately; that requires a scope to be set."}, "conditions": {"type": "array", "description": "The if/else_if/else rule blocks: {id, type, condition, action}. Required. Each action takes isAutoExecute; omitted, it defaults to true for Inventory and Campaign and false elsewhere, matching the app. Nested condition groups require advancedMode true. See update_automation's description for the full structure and the valid fields/actions per category.", "items": {"type": "object", "additionalProperties": true}}, "rule_schedule": {"type": "object", "description": "When the rule runs. Required.", "properties": {"type": {"type": "string", "enum": ["weekly", "monthly"]}, "days": {"type": "array", "items": {"type": "string"}}, "timeSlots": {"type": "array", "items": {"type": "string"}, "description": "Campaign only, and required for it \u2014 the times of day the rule re-checks. Allowed: 1:00 AM, 2:00 AM, 3:00 AM, 4:00 AM, 5:00 AM, 6:00 AM, 7:00 AM, 8:00 AM, 9:00 AM, 10:00 AM, 11:00 AM, 12:00 PM, 1:00 PM, 2:00 PM, 3:00 PM, 4:00 PM, 5:00 PM, 6:00 PM, 7:00 PM, 8:00 PM, 9:00 PM, 10:00 PM, 11:00 PM."}}, "additionalProperties": true}, "rule_processing_time": {"type": "string", "description": "The single time of day the rule runs (7:00 AM-9:00 PM). Not used by Campaign, which uses rule_schedule.timeSlots."}, "selected_campaigns": {"type": "array", "items": {"type": ["string", "object"], "additionalProperties": true}, "description": "Campaign id strings; objects {campaignId, adGroupsIds} when campaign_adgroup_selection is true; objects {campaignId, baseBudget} for Campaign automations, which require objects."}, "selected_campaign_tags": {"type": "array", "items": {"type": "object", "additionalProperties": true}, "description": "Campaign tags scoping the rule; use with campaign_tag_selection."}, "campaign_adgroup_selection": {"type": "boolean"}, "campaign_tag_selection": {"type": "boolean"}, "selected_asins": {"type": "array", "items": {"type": "string"}, "description": "Inventory only \u2014 the ASINs the stock rule watches."}, "selected_mapping": {"type": "object", "description": "Mapped Harvesting only, and required for it \u2014 ONE existing harvesting mapping (a single object, never a list; from list_harvesting_mappings). For several mappings, create one automation per mapping.", "properties": {"mapping_id": {"type": "string"}, "mapping_name": {"type": "string"}}, "additionalProperties": true}, "todays_live_data": {"type": "boolean", "description": "Campaign only \u2014 evaluate against today's live performance instead of the closed lookback window."}, "lookback_period": {"type": "object", "description": "Defaults to {value: 7, unit: 'days'}. Not used by Inventory.", "properties": {"value": {"type": ["number", "string"], "description": "Days; must be > 0."}, "unit": {"type": "string", "enum": ["days"]}}}, "lookback_skip_days": {"type": ["number", "string"], "description": "Days to skip from today; must be >= 0. Defaults to 3."}, "exclude_list": {"type": ["object", "array"], "description": "Entities the rule must leave alone. Shape depends on the category: {phrase, exact} for Keyword Targets/Search Terms/Mapped Harvesting; {phrase, exact, asins} for All Targets; {asins: [...]} for Ad Products; a flat array of warehouse code strings for Inventory. Placements and Campaign have none. Defaults to the category's empty shape.", "items": {"type": "string"}}, "email_notification": {"type": "boolean"}, "email_addresses": {"type": "array", "items": {"type": "string"}, "maxItems": 5}, "advancedMode": {"type": "boolean"}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["automate_for", "name", "conditions", "rule_schedule", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["created"], "description": "Always 'created' on success."}, "automation_id": {"type": "string", "description": "The new automation's id, assigned by the server."}, "type": {"type": "string", "enum": ["Keyword Targets", "All Targets", "Search Terms", "Mapped Harvesting", "Placements", "Ad Products", "Campaign", "Inventory"], "description": "The category it was created as."}, "name": {"type": "string", "description": "The automation's name."}, "automation_status": {"type": "string", "description": "The rule's own status \u2014 'INACTIVE' unless 'ACTIVE' was requested."}, "defaulted_fields": {"type": "array", "items": {"type": "string"}, "description": "Fields not supplied by the caller, filled with the editor's defaults."}, "ignored_fields": {"type": "array", "items": {"type": "string"}, "description": "Fields sent that do not apply to this category (present only when any were sent)."}, "warnings": {"type": "array", "items": {"type": "string"}, "description": "Things the caller should know: that the rule is inactive or report-only, or what a Campaign rule wrote outside itself."}}, "required": ["status", "automation_id", "type", "name", "automation_status"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/create_dayparting": {"post": {"operationId": "create_dayparting", "tags": ["Automation & Dayparting"], "summary": "Create Dayparting", "description": "Tool name: `create_dayparting` \u00b7 **Scope:** requires `tools:write`.\n\nCreate a dayparting schedule of one `type`, passing the whole definition in `dayparting`. `bid` and `placement`: `name`, `state`, `slotInterval` (1, 4 or 6), `bidAllocation` (`allocationType` + `timeSlots`) and `selectedCampaigns` \u2014 per campaign with optional `targets` for bid, or one `{campaignId, placementType, basePlacementPercentage}` entry per campaign-placement pair for placement (Sponsored Products only). `budget` and `portfolio`: `name`, a non-empty `rules` list (`{days, hour, minute, action, budget}`) and `selectedCampaigns` (`{campaignId, baseBudget}`) or `selectedPortfolios` (`{portfolioId, baseBudget}`); these are rule-driven and take no time slots. `baseBidStrategy` says how covered targets without a base bid of their own get one. Base bids themselves are set with `update_target`.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "Which kind of dayparting to create (required): bid, budget, portfolio, or placement."}, "dayparting": {"type": "object", "description": "The full definition of the schedule to create. The valid/required fields depend on 'type' \u2014 see the tool description. Do not include the account id here; it is injected from the account in scope.", "additionalProperties": true}, "baseBidStrategy": {"type": "string", "enum": ["use_current_bid", "custom"], "description": "How to give covered targets a base bid when some have none of their own (auto-targeting expressions that bid at their ad group default). 'use_current_bid' adopts the bid each target already runs at, so spend is unchanged until the multipliers apply. 'custom' means you have already set your own values with update_target (its baseBid field) and this call should proceed. Only send this when the tool asked for it."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["type", "dayparting", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "description": "'created' on success, or 'elicitation_required' when more input is needed."}, "type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "The dayparting kind that was created."}, "dayparting_id": {"type": ["string", "null"], "description": "The new dayparting id."}, "result": {"type": "object", "description": "Service-specific result (e.g. created target ids for bid).", "additionalProperties": true}, "message": {"type": "string", "description": "When status='elicitation_required', a plain-language request for the missing input."}, "requestedSchema": {"type": "object", "description": "When status='elicitation_required', a JSON-Schema form of the fields to provide (MCP-elicitation shape).", "additionalProperties": true}, "missing": {"type": "array", "items": {"type": "string"}, "description": "When status='elicitation_required', the names of the still-missing required fields."}}, "required": ["status"], "additionalProperties": true}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_automation": {"post": {"operationId": "get_automation", "tags": ["Automation & Dayparting"], "summary": "Get Automation", "description": "Tool name: `get_automation` \u00b7 **Scope:** requires `tools:read`.\n\nFull definition of one automation by `automation_id`: its if / else-if / else rule blocks (conditions and actions), the campaigns, tags, ASINs or harvesting mapping it runs on, exclusions, schedule, lookback and notification settings.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"automation_id": {"type": "string", "description": "The automation id (from list_automations)."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["automation_id", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"automation": {"type": "object", "description": "The full automation document, including its rule(s) and scope.", "properties": {"_id": {"type": "string", "description": "Automation id."}, "name": {"type": "string"}, "automate_for": {"type": "string", "description": "Automation category (the 'type')."}, "status": {"type": "string", "description": "Automation status."}, "created_at": {"type": "string"}, "updated_at": {"type": "string"}, "amazon_account_id": {"type": "string", "description": "Owning account id."}, "workspace_id": {"type": "string"}, "selected_campaigns": {"type": "array", "description": "Campaigns the automation runs on. Plain campaign-id strings normally; objects when the rule uses ad-group selection, or for the Campaign category (which carries baseBudget).", "items": {"type": ["string", "object"], "additionalProperties": true}}, "selected_campaign_tags": {"type": "array", "description": "Campaign tags scoping the rule when campaign_tag_selection is on.", "items": {"type": "object", "additionalProperties": true}}, "selected_asins": {"type": "array", "description": "ASINs in scope (Inventory rules \u2014 plain ASIN strings or objects).", "items": {"type": ["string", "object"], "additionalProperties": true}}, "exclude_list": {"description": "Excluded keywords/ASINs/placements (shape varies by automate_for).", "type": ["object", "array", "null"]}, "conditions": {"type": "array", "description": "The if/else_if/else rule blocks the automation evaluates, each with its condition tree and action. Pass these to update_automation to change the logic.", "items": {"type": "object", "additionalProperties": true}}, "variables": {"type": "array", "description": "Variables defined on this rule. A condition with valueType='variable' references one by its `name`. update_automation cannot create or change these.", "items": {"type": "object", "additionalProperties": true}}}, "additionalProperties": true}}, "required": ["automation"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_dayparting": {"post": {"operationId": "get_dayparting", "tags": ["Automation & Dayparting"], "summary": "Get Dayparting", "description": "Tool name: `get_dayparting` \u00b7 **Scope:** requires `tools:read`.\n\nFull definition of one dayparting schedule by `type` + `dayparting_id`: for `bid` / `placement` the time-slot allocation and the covered campaigns with their targets or placement entries; for `budget` / `portfolio` the rules and the covered campaigns or portfolios with their base budgets.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "Which kind of dayparting the id refers to (required): bid, budget, portfolio, or placement."}, "dayparting_id": {"type": "string", "description": "The dayparting id (from list_daypartings)."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["type", "dayparting_id", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "The dayparting kind that was fetched."}, "dayparting": {"type": "object", "description": "The dayparting document with its covered campaigns/targets/portfolios.", "properties": {"_id": {"type": "string", "description": "Dayparting id."}, "name": {"type": "string"}, "type": {"type": "string", "description": "bid | placement | budget."}, "scope": {"type": "string", "description": "campaign | portfolio (budget collection only)."}, "state": {"type": "string", "description": "State (bid/placement)."}, "status": {"type": "string", "description": "Status (budget/portfolio)."}, "amazonAccountId": {"type": "string", "description": "Account id (bid/placement)."}, "amazon_account_id": {"type": "string", "description": "Account id (budget/portfolio)."}, "selectedCampaigns": {"type": "array", "items": {"type": "object", "description": "A campaign covered by the dayparting, with its targets (bid/placement) or budget (budget).", "properties": {"campaignId": {"type": "string"}, "campaignName": {"type": ["string", "null"]}, "campaignBudget": {"description": "Campaign budget object or number.", "type": ["object", "number", "null"]}, "targetingType": {"type": ["string", "null"]}, "state": {"type": ["string", "null"]}, "targets": {"type": "array", "items": {"type": "object", "description": "A target the dayparting adjusts (bid type). From TargetingDaypartingTargetsData.", "properties": {"id": {"type": "string", "description": "Dayparting-target row id."}, "targetId": {"type": "string", "description": "Underlying keyword/product target id."}, "type": {"type": "string", "description": "Target type."}, "state": {"type": "string", "description": "Target state (e.g. enabled)."}, "adGroupId": {"type": "string"}, "campaignId": {"type": "string"}, "baseBid": {"type": ["number", "null"], "description": "Base bid before dayparting."}, "bid": {"type": ["number", "null"], "description": "Current bid (or ad-group default)."}}, "additionalProperties": true}}}, "additionalProperties": true}}, "selectedPortfolios": {"type": "array", "description": "Portfolios covered (portfolio type).", "items": {"type": "object", "additionalProperties": true}}, "bidAllocation": {"type": "object", "additionalProperties": true, "description": "Hourly bid allocation. Shape: {allocationType, timeSlots}. timeSlots is keyed FIRST by the allocationType, then by the DAY or SEGMENT the slots belong to -- never by the slot's position. allocationType 'daily' -> timeSlots.daily.daily; 'all_days' -> timeSlots.all_days.<weekday>, one list per day (monday ... sunday); 'weekdays_weekend' -> timeSlots.weekdays_weekend.weekdays and .weekend; 'custom_date' -> timeSlots.custom_date.<MM-DD-YYYY>. Each list holds one entry per slot: {label, startTime, endTime, bidMultiplier}. A list must hold EXACTLY 24/slotInterval slots, each exactly slotInterval hours wide, contiguous and in order from 00:00:00 round to 00:00:00 -- the web app lays the schedule out as a fixed grid of equal rows and maps stored slots onto it BY POSITION, so compressed or uneven slots are drawn against the wrong hours. To hold one multiplier across several hours, repeat it: a 5-hour block at 0.7 is five 1-hour slots of 0.7, not one 5-hour slot. Every bucket the allocationType defines must be present and full (all 7 weekdays for all_days; both weekdays and weekend for weekdays_weekend) -- a missing bucket is never scheduled and those hours silently keep their base bid. startTime/endTime MUST be 24-hour HH:MM:SS on a whole hour -- \"09:00:00\", not \"9am\", \"09:00\" or \"09:30:00\". The dayparting Lambda parses them with a fixed %H:%M:%S format, so a slot missing the seconds does not run. Use \"24:00:00\" for a slot that ends at midnight. label is NOT free text: it MUST be exactly \"<h> <am|pm> to <h> <am|pm>\" matching the times on that same slot -- \"8 am to 9 am\" for 08:00:00-09:00:00, \"12 am to 1 am\" for 00:00:00-01:00:00, \"11 pm to 12 am\" for 23:00:00-00:00:00 (12-hour clock, no leading zero, lowercase). The web app rebuilds each slot time by splitting the label on \" to \", so a descriptive label like \"Night -30%\" silently destroys the schedule the first time a user opens it in the UI. Put any description in the dayparting name instead. bidMultiplier is a RATIO applied to the target's base bid -- 1.25 is +25%, 0.8 is -20%, 1.0 leaves the bid alone. It is NOT a percentage: 125 would mean a 125x bid and is rejected. Example (slotInterval 12, all_days): {\"allocationType\": \"all_days\", \"timeSlots\": {\"all_days\": {\"monday\": [{\"label\": \"12 am to 12 pm\", \"startTime\": \"00:00:00\", \"endTime\": \"12:00:00\", \"bidMultiplier\": 0.8}, {\"label\": \"12 pm to 12 am\", \"startTime\": \"12:00:00\", \"endTime\": \"24:00:00\", \"bidMultiplier\": 1.25}], \"tuesday\": [...]}}}"}}, "additionalProperties": true}}, "required": ["type", "dayparting"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_hourly_performance": {"post": {"operationId": "get_hourly_performance", "tags": ["Automation & Dayparting"], "summary": "Get Hourly Performance", "description": "Tool name: `get_hourly_performance` \u00b7 **Scope:** requires `tools:read`.\n\nHourly advertising performance at `level` `campaign` or `keyword` (target level): rows bucketed by `group_by` (default `[\"hour\"]`; also `timestamp` for each hour of each day, `weekday`, `date`, and the entity dimensions `campaign`, `keyword`, `ad_group`), each with cost, clicks, impressions, sales, conversions, units, ACOS, ROAS, CTR, CVR and CPC, plus a totals row. Narrow with `campaign_ids` or `keyword_ids`. Always pass `start_date` / `end_date`: hourly data is rebuilt one whole local day at a time by a batch job, so today is normally empty and the range should end at yesterday or earlier. Hours are in the account timezone.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"level": {"type": "string", "enum": ["campaign", "keyword"], "description": "Granularity (required): 'campaign' or 'keyword' (target-level)."}, "start_date": {"type": "string", "description": "Start date YYYY-MM-DD. Should always be passed \u2014 omitting it (with end_date) defaults to today, which usually has no rows yet."}, "end_date": {"type": "string", "description": "End date YYYY-MM-DD. Defaults to start_date; omitting both defaults to today. End at yesterday or earlier for the most recent complete data."}, "group_by": {"type": "array", "items": {"type": "string", "enum": ["ad_group", "campaign", "date", "hour", "keyword", "timestamp", "weekday"]}, "description": "How to bucket rows (default ['hour']). Time dims (both levels): 'hour' (0-23), 'weekday', 'date', 'timestamp' (each hour of each day). Entity dims: 'campaign' (both levels); 'keyword' and 'ad_group' (keyword level only). Combine e.g. ['weekday','hour'] for a day-of-week x hour pattern."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional. Restrict to these campaign IDs (valid for both levels)."}, "keyword_ids": {"type": "array", "items": {"type": "string"}, "description": "Optional. Restrict to these target IDs. Only valid when level='keyword'."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["level", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"level": {"type": "string", "enum": ["campaign", "keyword"]}, "timezone": {"type": "string", "description": "Account timezone used for hour/weekday bucketing."}, "startDate": {"type": "string"}, "endDate": {"type": "string"}, "groupBy": {"type": "array", "items": {"type": "string"}}, "isToday": {"type": "boolean", "description": "True when the range includes today. Today's hours are normally NOT aggregated yet, so such a range is usually missing its most recent day(s) \u2014 not a real zero."}, "rowCount": {"type": "integer", "description": "Total buckets before any truncation."}, "truncated": {"type": "boolean", "description": "True if more rows exist than were returned."}, "rows": {"type": "array", "items": {"type": "object", "description": "One grouped bucket, ready to read aloud.", "properties": {"label": {"type": "string", "description": "Human-readable label for the bucket, e.g. '14:00' or 'Monday 14:00'."}, "hour": {"type": "integer", "description": "Hour 0-23 (present when grouped by hour)."}, "weekday": {"type": "string", "description": "Weekday name (present when grouped by weekday)."}, "date": {"type": "string", "description": "'YYYY-MM-DD' (present when grouped by date)."}, "time": {"type": "string", "description": "'YYYY-MM-DD HH:00' (present when grouped by timestamp)."}, "campaignId": {"type": "string"}, "targetId": {"type": "string"}, "adGroupId": {"type": "string"}, "cost": {"type": ["number", "null"]}, "clicks": {"type": ["number", "null"]}, "impressions": {"type": ["number", "null"]}, "sales": {"type": ["number", "null"], "description": "attributed_sales_14d"}, "conversions": {"type": ["number", "null"], "description": "attributed_conversions_14d"}, "unitsOrdered": {"type": ["number", "null"], "description": "attributed_units_ordered_14d"}, "acos": {"type": ["number", "null"], "description": "cost/sales; null if no sales"}, "roas": {"type": ["number", "null"], "description": "sales/cost; null if no cost"}, "ctr": {"type": ["number", "null"], "description": "clicks/impressions; null if no impressions"}, "cvr": {"type": ["number", "null"], "description": "conversions/clicks; null if no clicks"}, "cpc": {"type": ["number", "null"], "description": "cost/clicks; null if no clicks"}}, "required": ["label"], "additionalProperties": true}}, "totals": {"type": "object", "description": "Aggregate metrics across the whole range.", "properties": {"cost": {"type": ["number", "null"]}, "clicks": {"type": ["number", "null"]}, "impressions": {"type": ["number", "null"]}, "sales": {"type": ["number", "null"], "description": "attributed_sales_14d"}, "conversions": {"type": ["number", "null"], "description": "attributed_conversions_14d"}, "unitsOrdered": {"type": ["number", "null"], "description": "attributed_units_ordered_14d"}, "acos": {"type": ["number", "null"], "description": "cost/sales; null if no sales"}, "roas": {"type": ["number", "null"], "description": "sales/cost; null if no cost"}, "ctr": {"type": ["number", "null"], "description": "clicks/impressions; null if no impressions"}, "cvr": {"type": ["number", "null"], "description": "conversions/clicks; null if no clicks"}, "cpc": {"type": ["number", "null"], "description": "cost/clicks; null if no clicks"}}, "additionalProperties": true}, "note": {"type": "string", "description": "Guidance on timezone, data lag and null metrics."}}, "required": ["level", "timezone", "startDate", "endDate", "groupBy", "rows", "totals"], "additionalProperties": true}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_automations": {"post": {"operationId": "list_automations", "tags": ["Automation & Dayparting"], "summary": "List Automations", "description": "Tool name: `list_automations` \u00b7 **Scope:** requires `tools:read`.\n\nAutomation (rule) inventory for an account: id, name, category (`automate_for`), status, created / updated time and how many campaigns each covers. Pass `type` to filter to one category (`Keyword Targets`, `All Targets`, `Search Terms`, `Mapped Harvesting`, `Placements`, `Ad Products`, `Campaign`, `Inventory`). Deleted automations are never included; dayparting schedules are listed by `list_daypartings`. Paginated (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["Keyword Targets", "Inventory", "Search Terms", "Placements", "All Targets", "Ad Products", "Campaign", "Mapped Harvesting"], "description": "Optional. Filter to a single automation category (automate_for). Omit to list automations of all types."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "description": "Results per page. Defaults to 100. Max 500."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": ["string", "null"], "description": "The automation category filtered on, or null when unfiltered."}, "automations": {"type": "array", "description": "The page of automations for the account.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Automation id."}, "name": {"type": "string", "description": "Automation name."}, "type": {"type": "string", "description": "Automation category (automate_for)."}, "status": {"type": "string", "description": "Automation status."}, "createdAt": {"type": "string", "description": "Creation timestamp."}, "updatedAt": {"type": "string", "description": "Last update timestamp."}, "numSelectedCampaigns": {"type": "integer", "description": "Campaigns covered."}}, "required": ["id", "name", "type", "status"], "additionalProperties": true}}, "pagination": {"type": "object", "properties": {"total": {"type": "integer", "description": "Total automations after filtering."}, "page": {"type": "integer", "description": "Current page (0-indexed)."}, "pageSize": {"type": "integer", "description": "Results per page."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether more pages exist."}}, "required": ["total", "page", "pageSize", "totalPages", "hasMore"], "additionalProperties": false}, "next_step": {"type": "string", "description": "Hint: call get_automation for full details of a listed automation."}}, "required": ["type", "automations", "pagination"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_daypartings": {"post": {"operationId": "list_daypartings", "tags": ["Automation & Dayparting"], "summary": "List Daypartings", "description": "Tool name: `list_daypartings` \u00b7 **Scope:** requires `tools:read`.\n\nDayparting schedule inventory for one `type` \u2014 `bid` (time-based target bid adjustments), `placement` (placement bid adjustments), `budget` (campaign budget adjustments) or `portfolio` (portfolio budget adjustments): each schedule's id, name, state / status, creation time and how many campaigns, targets or portfolios it covers.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "Which kind of dayparting to list (required): bid, budget, portfolio, or placement."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["type", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "The dayparting kind that was listed."}, "daypartings": {"type": "array", "description": "The matching dayparting schedules.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Dayparting id."}, "name": {"type": "string", "description": "Schedule name."}, "type": {"type": "string", "description": "Dayparting kind."}, "state": {"type": "string", "description": "State (bid/placement)."}, "scope": {"type": "string", "description": "campaign or portfolio (budget/portfolio)."}, "status": {"type": "string", "description": "Status (budget/portfolio)."}, "createdAt": {"type": "string", "description": "Creation timestamp."}, "numCampaigns": {"type": "integer", "description": "Campaigns covered (bid/placement)."}, "targetCount": {"type": "integer", "description": "Targets covered (bid/placement)."}, "allocationType": {"type": ["string", "null"], "description": "Allocation type (bid/placement)."}, "numSelected": {"type": "integer", "description": "Campaigns/portfolios covered (budget/portfolio)."}}, "required": ["id", "name", "type"], "additionalProperties": true}}, "total": {"type": "integer", "description": "Number of schedules returned."}, "next_step": {"type": "string", "description": "Hint: call get_dayparting for full details of a listed schedule."}}, "required": ["type", "daypartings", "total"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/preview_automation": {"post": {"operationId": "preview_automation", "tags": ["Automation & Dayparting"], "summary": "Preview Automation", "description": "Tool name: `preview_automation` \u00b7 **Scope:** requires `tools:read`.\n\nDry run of a saved automation by `automation_id`: the entities (campaigns, keywords, targets, ads, \u2026) it would act on right now and the action each would get, computed over the rule's current lookback window without applying anything. `would_act_on` is the total match count. Use it before setting a rule ACTIVE. Paginated (`page_size` 50, max 200).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"automation_id": {"type": "string", "description": "The automation id (from list_automations)."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "page": {"type": "integer", "description": "Zero-based page number. Default 0."}, "page_size": {"type": "integer", "description": "Rows per page. Default 50, max 200."}}, "required": ["automation_id", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Dry run of a saved automation: one page of the entities it would act on right now, with nothing applied.", "properties": {"automation_id": {"type": "string", "description": "The automation id as passed in."}, "name": {"type": ["string", "null"], "description": "The automation's name."}, "type": {"type": ["string", "null"], "description": "The automation's category (automate_for)."}, "status": {"type": ["string", "null"], "description": "The automation's own status, e.g. ACTIVE or INACTIVE."}, "would_act_on": {"type": "integer", "description": "Total number of entities the rule would act on."}, "rows": {"type": "array", "description": "The current page of recommendation-shaped preview rows from the preview service.", "items": {"type": "object", "description": "One entity the rule would act on and its action; shape is set by the external preview service.", "additionalProperties": {"description": "Preview row field (see tool description)."}}}, "pagination": {"type": "object", "description": "Page metadata over the full preview set.", "properties": {"page": {"type": "integer", "description": "Zero-based page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page used."}, "total": {"type": "integer", "description": "Size of the full preview set."}, "totalPages": {"type": "integer", "description": "Number of pages at this page size."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "note": {"type": "string", "description": "Reminder that this was a dry run."}, "message": {"type": "string", "description": "Message from the preview service; present only when it sent one."}}, "required": ["automation_id", "name", "type", "status", "would_act_on", "rows", "pagination", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/update_automation": {"post": {"operationId": "update_automation", "tags": ["Automation & Dayparting"], "summary": "Update Automation", "description": "Tool name: `update_automation` \u00b7 **Scope:** requires `tools:write`.\n\nChange an existing automation by `automation_id`; `updates` holds only the fields to change (omitted fields keep their value). Editable everywhere: `name`, `description`, `status` (`ACTIVE` / `INACTIVE`; cannot archive), `conditions`, `rule_schedule` and notification settings; most categories also take `selected_campaigns`, `selected_campaign_tags`, `rule_processing_time`, `lookback_period`, `lookback_skip_days` and `exclude_list`; Inventory takes `selected_asins`, Mapped Harvesting `selected_mapping`, Campaign `todays_live_data` and `rule_schedule.timeSlots`. The category itself cannot change, and a field the category does not have is reported back, never stored. Activating requires a scope in the same call. `AI Agent` automations cannot be edited here.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"automation_id": {"type": "string", "description": "The automation id to update (from list_automations)."}, "updates": {"type": "object", "description": "ONLY the fields to change. Do not include _id, automate_for, amazon_account_id, or workspace_id \u2014 these are not editable here. Which of the properties below apply depends on the automation's category; sending one the category does not have is ignored and reported back.", "properties": {"name": {"type": "string"}, "description": {"type": "string"}, "status": {"type": "string", "description": "'ACTIVE' or 'INACTIVE'. 'INCOMPLETE' is accepted and normalised to 'INACTIVE'. This tool cannot archive an automation."}, "selected_campaigns": {"type": "array", "items": {"type": ["string", "object"], "additionalProperties": true}, "description": "Campaign id strings, or {campaignId, adGroupsIds}."}, "selected_campaign_tags": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "campaign_adgroup_selection": {"type": "boolean"}, "campaign_tag_selection": {"type": "boolean"}, "selected_asins": {"type": "array", "items": {"type": "string"}, "description": "Inventory only \u2014 the ASINs the stock rule watches."}, "selected_mapping": {"type": "object", "description": "Mapped Harvesting only \u2014 the ONE saved harvesting mapping this rule runs through (a single object, never a list). Must already exist on the account; list_harvesting_mappings lists them. For several mappings, create one automation per mapping.", "properties": {"mapping_id": {"type": "string"}, "mapping_name": {"type": "string"}}, "additionalProperties": true}, "todays_live_data": {"type": "boolean", "description": "Campaign only \u2014 evaluate against today's live performance instead of the closed lookback window."}, "rule_schedule": {"type": "object", "properties": {"type": {"type": "string", "enum": ["weekly", "monthly"]}, "days": {"type": "array", "items": {"type": "string"}}, "timeSlots": {"type": "array", "items": {"type": "string"}, "description": "Campaign only \u2014 the times of day the rule re-checks. Required (non-empty) for Campaign automations."}}, "additionalProperties": true}, "rule_processing_time": {"type": "string", "description": "The single time of day the rule runs. Not used by Campaign automations, which use rule_schedule.timeSlots instead."}, "lookback_period": {"type": "object", "properties": {"value": {"type": ["number", "string"], "description": "Days to look back; must be > 0."}, "unit": {"type": "string", "enum": ["days"]}}}, "lookback_skip_days": {"type": ["number", "string"], "description": "Days to skip from today; must be >= 0."}, "exclude_list": {"type": ["object", "array"], "description": "Entities the rule must leave alone. The SHAPE depends on the category: {phrase, exact} comma-separated strings for Keyword Targets and Search Terms/Mapped Harvesting; {phrase, exact, asins} for All Targets; {asins: [...]} (a real array) for Ad Products; a flat array of warehouse code strings for Inventory. Placements and Campaign have none.", "items": {"type": "string"}}, "conditions": {"type": "array", "description": "The full if/else_if/else rule block tree \u2014 see tool description.", "items": {"type": "object", "additionalProperties": true}}, "email_notification": {"type": "boolean"}, "email_addresses": {"type": "array", "items": {"type": "string"}, "maxItems": 5}, "advancedMode": {"type": "boolean"}}, "additionalProperties": true}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["automation_id", "updates", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "enum": ["updated", "unchanged"], "description": "'updated' when the automation was written; 'unchanged' when every requested value was already set and no write was needed."}, "automation_id": {"type": "string", "description": "The updated automation id."}, "type": {"type": "string", "enum": ["Keyword Targets", "All Targets", "Search Terms", "Mapped Harvesting", "Placements", "Ad Products", "Campaign", "Inventory"], "description": "The automation's category, read from the stored document."}, "updated_fields": {"type": "array", "items": {"type": "string"}, "description": "Which fields were actually written."}, "ignored_fields": {"type": "array", "items": {"type": "string"}, "description": "Fields sent in 'updates' that are not editable on this automation's category (present only when any were sent)."}, "note": {"type": "string", "description": "Present only when ignored_fields is non-empty."}}, "required": ["status", "automation_id", "type", "updated_fields"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/update_dayparting": {"post": {"operationId": "update_dayparting", "tags": ["Automation & Dayparting"], "summary": "Update Dayparting", "description": "Tool name: `update_dayparting` \u00b7 **Scope:** requires `tools:write`.\n\nChange an existing dayparting schedule by `type` + `dayparting_id`; `updates` holds only the fields to change. Sent lists replace: a campaign's `targets` (bid) is its complete desired set, and `selectedCampaigns` (placement) and `rules` (budget / portfolio) replace the whole list, so read the current definition with `get_dayparting` and edit it. Pause or archive via `state` (bid / placement) or `status` (budget / portfolio). A `baseBid` sent here is ignored \u2014 set base bids with `update_target`.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "Which kind of dayparting the id refers to (required): bid, budget, portfolio, or placement."}, "dayparting_id": {"type": "string", "description": "The dayparting id to update (from list_daypartings)."}, "updates": {"type": "object", "description": "The fields to change on this dayparting. Only include the fields you want to modify; the rest are left as-is. The valid fields depend on 'type' \u2014 see the tool description. Do not include the id or the account id here.", "additionalProperties": true}, "baseBidStrategy": {"type": "string", "enum": ["use_current_bid", "custom"], "description": "How to give covered targets a base bid when some have none of their own (auto-targeting expressions that bid at their ad group default). 'use_current_bid' adopts the bid each target already runs at, so spend is unchanged until the multipliers apply. 'custom' means you have already set your own values with update_target (its baseBid field) and this call should proceed. Only send this when the tool asked for it."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["type", "dayparting_id", "updates", "amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "description": "'updated' on success, or 'elicitation_required' when more input is needed."}, "type": {"type": "string", "enum": ["bid", "budget", "portfolio", "placement"], "description": "The dayparting kind that was updated."}, "dayparting_id": {"type": "string", "description": "The updated dayparting id."}, "result": {"type": "object", "description": "Service-specific result (e.g. affected target ids for bid).", "additionalProperties": true}, "message": {"type": "string", "description": "When status='elicitation_required', a plain-language request for the missing input."}, "requestedSchema": {"type": "object", "description": "When status='elicitation_required', a JSON-Schema form of the fields to provide (MCP-elicitation shape).", "additionalProperties": true}, "missing": {"type": "array", "items": {"type": "string"}, "description": "When status='elicitation_required', the names of the still-missing required fields."}}, "required": ["status"], "additionalProperties": true}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/dismiss_recommendations": {"post": {"operationId": "dismiss_recommendations", "tags": ["Insights & Alerts"], "summary": "Dismiss Recommendations", "description": "Tool name: `dismiss_recommendations` \u00b7 **Scope:** requires `tools:write`.\n\nMove open recommendations out of the queue \u2014 the app's Ignore / Mark as read / Action not required buttons. Pass up to 50 `recommendation_ids` from `list_recommendations` and a `status` (`ignored` default, `action_not_required`, `mark_as_read`). Only recommendations still `new` are changed; others are reported as skipped. Nothing is applied to Amazon \u2014 to act on a recommendation, make the equivalent change with the normal write tools.", "x-permission-level": "write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "recommendation_ids": {"type": "array", "items": {"type": "string"}, "description": "Recommendation ids from list_recommendations (max 50)."}, "status": {"type": "string", "enum": ["ignored", "action_not_required", "mark_as_read"], "description": "Target state. Default 'ignored'."}}, "required": ["amazon_account_id", "recommendation_ids"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "Per-recommendation outcome of moving open recommendations out of the queue, with an overall status and counts.", "properties": {"status": {"type": "string", "enum": ["success", "partial_success", "no_change", "failed"], "description": "Overall outcome across all requested ids."}, "applied": {"type": "boolean", "description": "True when at least one recommendation was dismissed."}, "summary": {"type": "object", "description": "Counts of per-id outcomes.", "properties": {"total": {"type": "integer", "description": "Number of distinct ids processed."}, "dismissed": {"type": "integer", "description": "Ids whose state was changed."}, "unchanged": {"type": "integer", "description": "Ids already in the target state."}, "skipped": {"type": "integer", "description": "Ids not in state 'new' or changed concurrently."}, "failed": {"type": "integer", "description": "Invalid ids, not found in this account, or errors."}}, "required": ["total", "dismissed", "unchanged", "skipped", "failed"]}, "results": {"type": "array", "description": "One outcome per distinct requested id, in request order.", "items": {"type": "object", "description": "Outcome for one recommendation id.", "properties": {"id": {"type": "string", "description": "The requested recommendation id."}, "status": {"type": "string", "enum": ["dismissed", "unchanged", "skipped", "failed"], "description": "What happened to this id."}, "state": {"type": "string", "description": "Its state after the call (dismissed / unchanged) or current state (skipped)."}, "error": {"type": "string", "description": "Why it was skipped or failed; present only then."}}, "required": ["id", "status"]}}, "note": {"type": "string", "description": "Reminder that nothing was applied to Amazon."}}, "required": ["status", "applied", "summary", "results", "note"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "422": {"$ref": "#/components/responses/PolicyViolation"}}}}, "/public/v1/tools/get_activity_log": {"post": {"operationId": "get_activity_log", "tags": ["Insights & Alerts"], "summary": "Get Activity Log", "description": "Tool name: `get_activity_log` \u00b7 **Scope:** requires `tools:read`.\n\nThe account's activity log \u2014 the audit trail of changes actually made to campaigns, keywords, targets and ads, newest first, with old value, new value and the source that made it (`Bulk Action`, `Dayparting`, `AI Recommendation`, `AI Agent`, `MCP`, `Automation`, \u2026). Filter by `sources`, `change_types` (e.g. `Bid Change`, `Budget Change`, `State Change`), `campaign_ids` (max 200), `targeting_values`, `changed_by_ids` (or `system`), `status` (`error` = changes that failed to apply) and `search`. `mode: \"summary\"` returns no rows \u2014 just the total and counts by source, change type, status, entity and the 10 busiest days \u2014 so call it first to size a query. Without `start_date` / `end_date` the last 7 full days ending yesterday (account timezone) are used; only about the last 30 days are retained, and the newest few hours may not be processed yet. On this API rows come back as JSON objects (`format: \"toon\"` gives the compact columnar text instead). Paginated (`page_size` 100, max 500).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"start_date": {"type": "string", "description": "Start of the window, ISO date (e.g. '2026-08-01'). Pair with end_date."}, "end_date": {"type": "string", "description": "End of the window, ISO date, inclusive. Pair with start_date."}, "sources": {"type": "array", "items": {"type": "string", "enum": ["Bulk Action", "Bulk Action: Single", "Dayparting", "Activity Log", "AI Recommendation", "AI Agent", "MCP", "Automation", "Other"]}, "description": "Only changes from these sources. Use ['Automation'] for automation activity."}, "change_types": {"type": "array", "items": {"type": "string"}, "description": "Only these change types, e.g. 'Bid Change', 'Budget Change', 'State Change', 'Add Keyword', 'Add Negative Keyword', 'Campaign Creation'."}, "campaign_ids": {"type": "array", "items": {"type": "string"}, "description": "Restrict to these campaigns (max 200). From list_campaigns."}, "targeting_values": {"type": "array", "items": {"type": "string"}, "description": "Restrict to these ASINs or keyword texts."}, "changed_by_ids": {"type": "array", "items": {"type": "string"}, "description": "User ids, or the literal 'system' for automated changes."}, "status": {"type": "string", "enum": ["success", "error"], "description": "Only successful, or only failed, changes."}, "search": {"type": "string", "description": "Free-text search over campaigns/targets. Ignored when campaign_ids or targeting_values is already set."}, "mode": {"type": "string", "enum": ["summary", "rows"], "description": "'rows' (default) returns the page of change rows. 'summary' returns no rows at all \u2014 the total plus counts by source, change type, status, entity and the 10 busiest days in the window (not every day), for exactly the same filters. Use it to size a query before fetching it. 'page' and 'page_size' have no effect on a summary, though an invalid value for either is still a validation error. Summary counts are not all reusable as filters: every source label it reports can be passed back in 'sources', but a few change-type labels are display-only and are rejected as 'change_types'."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "description": "Rows per page (rows mode only). Defaults to 100, max 500. An over-max value is clamped, not rejected, and the reduction is stated in 'summary'."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"logs": {"type": ["array", "string"], "description": "ROWS MODE ONLY \u2014 absent from a summary. The page of change rows, newest first. An array of row objects when format='json'; a single TOON-encoded string ('logs[N]{col,...}:' header followed by one comma-separated line per row) when format='toon' (the default). 'items' below describes one row's fields either way.", "items": {"type": "object", "description": "One change: what was changed, from what to what, by whom, and when.", "properties": {"date_time": {"type": ["string", "null"], "description": "When the change landed (ISO 8601 UTC)."}, "source": {"type": ["string", "null"], "description": "What made the change \u2014 see the sources list."}, "change_type": {"type": ["string", "null"], "description": "Human label, e.g. 'Bid Change', 'Budget Change'."}, "type": {"type": ["string", "null"], "description": "Machine log type, e.g. 'keyword_bid_update'."}, "entity": {"type": ["string", "null"], "description": "Entity kind that was changed."}, "change_on": {"type": ["string", "null"], "description": "The specific thing changed \u2014 keyword text, ASIN, placement."}, "campaign_id": {"type": ["string", "null"]}, "campaign_name": {"type": ["string", "null"]}, "ad_group_id": {"type": ["string", "null"]}, "ad_group_name": {"type": ["string", "null"]}, "campaign_state": {"type": ["string", "null"]}, "old_value": {"type": ["string", "null"], "description": "Value before the change."}, "new_value": {"type": ["string", "null"], "description": "Value after the change."}, "changed_by": {"type": ["string", "null"], "description": "User name, or 'System' for automated changes."}, "changed_by_id": {"type": ["string", "null"], "description": "User id when a person made the change."}, "status": {"type": ["string", "null"], "description": "'success' or 'error'."}, "action": {"type": ["string", "null"]}, "action_group": {"type": ["string", "null"], "description": "Groups rows written by one operation, so related changes can be read together."}, "operation_type": {"type": ["string", "null"]}, "isAutoExecute": {"type": ["boolean", "null"], "description": "For Automation rows: true when the rule applied the change itself, false when it only raised it for a person to approve."}, "dayparting_type": {"type": ["string", "null"]}, "dayparting_id": {"type": ["string", "null"]}, "trigger_id": {"type": ["string", "null"]}, "target_id": {"type": ["string", "null"]}, "ad_id": {"type": ["string", "null"]}, "action_source": {"type": ["string", "null"]}, "source_doc_id": {"type": ["string", "null"]}}, "additionalProperties": true}}, "summary": {"type": "string", "description": "Plain-language read on this page (rows mode) or on the whole matched set (summary mode), or why it is empty. Also states when a default date window was applied. The only key both modes always return."}, "mode": {"type": "string", "enum": ["summary", "rows"], "description": "SUMMARY MODE ONLY \u2014 echoes back that this is a summary, not rows."}, "total": {"type": "integer", "description": "SUMMARY MODE ONLY \u2014 total rows matching the filters. In rows mode the equivalent lives at pagination.total, on page 0."}, "dateRange": {"type": "string", "description": "SUMMARY MODE ONLY \u2014 the window the counts cover, '<start>..<end>' inclusive. Shows the defaulted window when no dates were given."}, "bySource": {"type": "object", "description": "SUMMARY MODE ONLY \u2014 matching rows per source, busiest first.", "additionalProperties": {"type": "integer"}}, "byChangeType": {"type": "object", "description": "SUMMARY MODE ONLY \u2014 matching rows per change type, busiest first. A few of these labels are display-only and cannot be passed back as a 'change_types' filter; that is a validation error, not an empty result.", "additionalProperties": {"type": "integer"}}, "byStatus": {"type": "object", "description": "SUMMARY MODE ONLY \u2014 matching rows per status ('success' / 'error'), busiest first.", "additionalProperties": {"type": "integer"}}, "byEntity": {"type": "object", "description": "SUMMARY MODE ONLY \u2014 matching rows per entity kind, busiest first.", "additionalProperties": {"type": "integer"}}, "busiestDays": {"type": "object", "description": "SUMMARY MODE ONLY \u2014 matching rows per day for the 10 busiest days in the window, busiest first. Not the whole window.", "additionalProperties": {"type": "integer"}}, "pageBreakdown": {"type": "object", "description": "Counts for the CURRENT PAGE only \u2014 not totals across the result.", "properties": {"bySource": {"type": "object", "additionalProperties": {"type": "integer"}}, "byChangeType": {"type": "object", "additionalProperties": {"type": "integer"}}}, "additionalProperties": false}, "searchResolvedTo": {"type": "object", "description": "Present only when 'search' was used \u2014 what it resolved to.", "properties": {"campaignIds": {"type": "integer", "description": "Campaigns the search matched."}, "targetingValues": {"type": "integer", "description": "Targets the search matched."}}, "additionalProperties": false}, "pagination": {"type": "object", "description": "ROWS MODE ONLY \u2014 absent from a summary, which has no page.", "properties": {"page": {"type": "integer", "description": "Current page (0-indexed)."}, "pageSize": {"type": "integer", "description": "Rows per page."}, "returned": {"type": "integer", "description": "Rows on this page."}, "hasMore": {"type": "boolean", "description": "Whether more pages exist."}, "nextPage": {"type": ["integer", "null"], "description": "Next page number, or null."}, "total": {"type": "integer", "description": "Total matching rows. Only present on page 0."}}, "required": ["page", "pageSize", "returned", "hasMore"], "additionalProperties": false}}, "required": ["summary"], "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_ai_performance_summary": {"post": {"operationId": "get_ai_performance_summary", "tags": ["Insights & Alerts"], "summary": "Get AI Performance Summary", "description": "Tool name: `get_ai_performance_summary` \u00b7 **Scope:** requires `tools:read`.\n\nThe latest AI-written summary of the account's advertising performance \u2014 the summary card on the SellerMate Home dashboard: a short narrative plus structured insights and positive / negative / neutral pointers when available. Generated periodically: check `generated_at`; `available: false` means none has been generated yet.", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "The latest AI-written summary of the account's ad performance, or a flag that none exists yet.", "oneOf": [{"type": "object", "description": "No summary has been generated for this account yet.", "properties": {"available": {"type": "boolean", "enum": [false], "description": "Always false on this branch."}, "note": {"type": "string", "description": "Explains that no summary exists yet."}}, "required": ["available", "note"]}, {"type": "object", "description": "The latest summary document.", "properties": {"available": {"type": "boolean", "enum": [true], "description": "Always true on this branch."}, "generated_at": {"type": ["string", "null"], "description": "When the summary was generated (created_at), ISO 8601."}, "summary": {"type": ["string", "null"], "description": "The narrative summary text."}, "summary_v2": {"type": "object", "description": "Structured summary; present only when the document has one.", "properties": {"insights": {"type": "array", "items": {"description": "One insight (see tool description)."}, "description": "Structured insights list."}, "pointers": {"type": "object", "description": "Pointers grouped by sentiment.", "properties": {"positive": {"type": "array", "items": {"description": "One positive pointer (see tool description)."}, "description": "Positive pointers."}, "negative": {"type": "array", "items": {"description": "One negative pointer (see tool description)."}, "description": "Negative pointers."}, "neutral": {"type": "array", "items": {"description": "One neutral pointer (see tool description)."}, "description": "Neutral pointers."}}}}}, "start_date": {"type": "string", "description": "First day the summary covers; present when stored."}, "end_date": {"type": "string", "description": "Last day the summary covers; present when stored."}}, "required": ["available", "generated_at", "summary"]}]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/get_fired_alerts": {"post": {"operationId": "get_fired_alerts", "tags": ["Insights & Alerts"], "summary": "Get Fired Alerts", "description": "Tool name: `get_fired_alerts` \u00b7 **Scope:** requires `tools:read`.\n\nThe alerts that have fired on an account, newest first \u2014 the Alerts page's event log. Each row has when it fired, the automation (alert) name and category, the entity it fired on, a description of the matched condition and the metric snapshot it fired on. `start_date` / `end_date` are inclusive account-local days (default: the last 7 days including today; max window 90 days); `automation_name` is a case-insensitive partial match. To see how an alert rule is configured use `list_automations` / `get_automation`. Paginated (`page_size` 50, max 200).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "start_date": {"type": "string", "description": "First day, YYYY-MM-DD (inclusive)."}, "end_date": {"type": "string", "description": "Last day, YYYY-MM-DD (inclusive)."}, "automation_name": {"type": "string", "description": "Only alerts whose automation name contains this text (case-insensitive)."}, "page": {"type": "integer", "description": "Zero-based page number. Default 0."}, "page_size": {"type": "integer", "description": "Rows per page. Default 50, max 200."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of alerts that fired on the account in a date window, newest first.", "properties": {"alerts": {"type": "array", "description": "The current page of fired-alert rows; empty fields are dropped from each row.", "items": {"type": "object", "description": "One fired alert; which entity fields appear depends on the automation's category.", "properties": {"id": {"type": "string", "description": "Alert log id (Mongo _id as a string)."}, "fired_at": {"type": "string", "description": "When the alert fired (timestamp_publishing), ISO 8601."}, "automation_name": {"type": "string", "description": "Name of the automation (alert rule) that fired."}, "alert_category": {"type": "string", "description": "The alert's category."}, "entity_type": {"type": "string", "description": "Entity type derived from automate_for; 'Other' when unmapped."}, "entity_label": {"type": "string", "description": "Label of the entity the alert fired on."}, "condition": {"type": "string", "description": "Ready-made description of the matched conditions."}, "campaign_name": {"type": "string", "description": "Campaign name, when the alert concerns a campaign."}, "campaign_id": {"type": ["string", "integer"], "description": "Campaign id as stored on the document."}, "ad_group_name": {"type": "string", "description": "Ad group name, when applicable."}, "keyword_text": {"type": "string", "description": "Keyword text, when applicable."}, "targeting_value": {"type": "string", "description": "Targeting value, when applicable."}, "ad_asin": {"type": "string", "description": "Advertised ASIN, when applicable."}, "date_range": {"description": "The lookback range the alert evaluated (shape as stored; see tool description)."}, "metrics": {"type": "object", "description": "Metric snapshot the alert fired on (data_obj); shape varies by category.", "additionalProperties": {"description": "One metric value (see tool description)."}}}, "required": ["id"]}}, "pagination": {"type": "object", "description": "Page metadata over the full filtered set.", "properties": {"page": {"type": "integer", "description": "Zero-based page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page used."}, "total": {"type": "integer", "description": "Size of the full filtered set."}, "totalPages": {"type": "integer", "description": "Number of pages at this page size."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "dateRange": {"type": "object", "description": "The inclusive account-local day window that was queried.", "properties": {"start": {"type": "string", "description": "First day, YYYY-MM-DD."}, "end": {"type": "string", "description": "Last day, YYYY-MM-DD."}}, "required": ["start", "end"]}}, "required": ["alerts", "pagination", "total", "dateRange"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_recommendations": {"post": {"operationId": "list_recommendations", "tags": ["Insights & Alerts"], "summary": "List Recommendations", "description": "Tool name: `list_recommendations` \u00b7 **Scope:** requires `tools:read`.\n\nThe recommendations SellerMate has generated for an account, newest first: suggested bid changes, keywords / targets to add or negate, and similar actions, each with the entity it concerns. `statuses` defaults to `[\"new\"]` (also `executed`, `executed_from_outside`, `ignored`, `action_not_required`, `mark_as_read`, `error`); `source` is `ai` (default) or `automation`. `executed` history defaults to the last 30 days unless `start_date` + `end_date` are given. The result carries `byState` and `byCategory` counts over the whole match, then one page of rows. Read-only. Paginated (`page_size` 50, max 200).", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}, "statuses": {"type": "array", "items": {"type": "string", "enum": ["executed", "executed_from_outside", "new", "action_not_required", "ignored", "mark_as_read", "error"]}, "description": "Recommendation states to include. Default ['new']."}, "source": {"type": "string", "enum": ["ai", "automation"], "description": "'ai' (default) or 'automation' (proposed by automation rules)."}, "start_date": {"type": "string", "description": "First day, YYYY-MM-DD. Give with end_date."}, "end_date": {"type": "string", "description": "Last day, YYYY-MM-DD. Give with start_date."}, "ad_products": {"type": "array", "items": {"type": "string"}, "description": "Only recommendations on these keyword texts or ASINs."}, "page": {"type": "integer", "description": "Zero-based page number. Default 0."}, "page_size": {"type": "integer", "description": "Rows per page. Default 50, max 200."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "description": "One page of the account's recommendations feed (newest first) with state / category counts over the whole match.", "properties": {"recommendations": {"type": "array", "description": "The current page of recommendation rows; empty fields are dropped from each row.", "items": {"type": "object", "description": "One recommendation; core fields lifted to the top, everything else under details.", "properties": {"id": {"type": "string", "description": "Recommendation id (Mongo _id as a string)."}, "state": {"type": "string", "enum": ["executed", "executed_from_outside", "new", "action_not_required", "ignored", "mark_as_read", "error"], "description": "Current recommendation state."}, "category": {"type": "string", "description": "Recommendation category (recommendation_category on the document)."}, "action": {"type": "string", "description": "The suggested action text."}, "created_at": {"type": "string", "description": "When it was published (timestamp_publishing), ISO 8601."}, "campaign_id": {"type": "string", "description": "Amazon campaign id, always stringified."}, "campaign_name": {"type": "string", "description": "Campaign name."}, "ad_group_id": {"type": "string", "description": "Amazon ad group id, always stringified."}, "ad_group_name": {"type": "string", "description": "Ad group name."}, "keyword_text": {"type": "string", "description": "Keyword text the recommendation concerns."}, "ad_asin": {"type": "string", "description": "Advertised ASIN the recommendation concerns."}, "targeted_asin": {"type": "string", "description": "Targeted ASIN the recommendation concerns."}, "current_bid": {"type": "number", "description": "The entity's current bid."}, "rule_id": {"type": "string", "description": "Automation rule id that generated it (source 'automation')."}, "reason": {"type": "string", "description": "Why it was recommended, HTML stripped, cut to 300 characters."}, "details": {"type": "object", "description": "Remaining non-empty document fields (tenant ids and large blobs removed).", "additionalProperties": {"description": "Extra recommendation field (see tool description)."}}}, "required": ["id"]}}, "pagination": {"type": "object", "description": "Page metadata over the full matched set.", "properties": {"page": {"type": "integer", "description": "Zero-based page number returned."}, "pageSize": {"type": "integer", "description": "Rows per page used."}, "total": {"type": "integer", "description": "Size of the full matched set."}, "totalPages": {"type": "integer", "description": "Number of pages at this page size."}, "hasMore": {"type": "boolean", "description": "True when a later page exists."}, "nextCursor": {"type": ["string", "null"], "description": "Opaque base64 token for the next page; null on the last page."}}, "required": ["page", "pageSize", "total", "totalPages", "hasMore", "nextCursor"]}, "total": {"type": "integer", "description": "Same as pagination.total."}, "byState": {"type": "object", "description": "Row count per state over the whole match, largest first.", "additionalProperties": {"type": "integer", "description": "Rows in this state."}}, "byCategory": {"type": "object", "description": "Row count per category over the whole match, largest first.", "additionalProperties": {"type": "integer", "description": "Rows in this category."}}, "source": {"type": "string", "enum": ["ai", "automation"], "description": "Which feed was listed."}, "dateRange": {"type": "object", "description": "The explicit window applied; present only when start_date / end_date were given.", "properties": {"start": {"type": "string", "description": "First day, YYYY-MM-DD."}, "end": {"type": "string", "description": "Last day, YYYY-MM-DD."}}, "required": ["start", "end"]}, "executedDateRange": {"type": "object", "description": "Default 30-day window applied to 'executed' rows only; present when no explicit window and 'executed' was requested.", "properties": {"start": {"type": "string", "description": "First day, YYYY-MM-DD."}, "end": {"type": "string", "description": "Last day (today), YYYY-MM-DD."}}, "required": ["start", "end"]}}, "required": ["recommendations", "pagination", "total", "byState", "byCategory", "source"]}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}, "/public/v1/tools/list_harvesting_mappings": {"post": {"operationId": "list_harvesting_mappings", "tags": ["Other"], "summary": "List Harvesting Mappings", "description": "Tool name: `list_harvesting_mappings` \u00b7 **Scope:** requires `tools:read`.\n\nList the saved harvesting mappings for a specific Amazon account \u2014 the source ad group -> destination ad gr\u2026", "x-permission-level": "read", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"mapping_id": {"type": "string", "description": "Optional. Return this one mapping in full instead of the list."}, "name": {"type": "string", "description": "Optional. Partial, case-insensitive filter on the mapping name."}, "page": {"type": "integer", "minimum": 0, "description": "Page number (0-indexed). Defaults to 0."}, "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "description": "Results per page. Defaults to 100. Max 500."}, "amazon_account_id": {"type": "string", "description": "The Amazon account ID (from get_user_context). Auto-filled when your API key is restricted to a single Amazon account."}}, "required": ["amazon_account_id"]}}}}, "responses": {"200": {"description": "Tool result.", "content": {"application/json": {"schema": {"type": "object", "properties": {"mappings": {"type": "array", "description": "The page of mappings (list mode).", "items": {"type": "object", "properties": {"mapping_id": {"type": "string", "description": "Pass as selected_mapping.mapping_id."}, "mapping_name": {"type": "string", "description": "Mapping name."}, "numSourceAdGroups": {"type": "integer", "description": "Source ad groups mapped."}, "numDestinations": {"type": "integer", "description": "Destination ad groups across all sources."}, "automationCount": {"type": "integer", "description": "Automations that reference this mapping."}, "createdAt": {"type": "string", "description": "Creation timestamp."}, "updatedAt": {"type": "string", "description": "Last update timestamp."}}, "required": ["mapping_id", "mapping_name"], "additionalProperties": true}}, "mapping": {"type": "object", "description": "One mapping in full (mapping_id mode).", "additionalProperties": true}, "pagination": {"type": "object", "properties": {"total": {"type": "integer", "description": "Total mappings after filtering."}, "page": {"type": "integer", "description": "Current page (0-indexed)."}, "pageSize": {"type": "integer", "description": "Results per page."}, "totalPages": {"type": "integer", "description": "Total number of pages."}, "hasMore": {"type": "boolean", "description": "Whether more pages exist."}}, "required": ["total", "page", "pageSize", "totalPages", "hasMore"], "additionalProperties": false}, "next_step": {"type": "string", "description": "Hint: how to use a mapping in create_automation."}}, "additionalProperties": false}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}}}}}, "components": {"securitySchemes": {"ApiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key, e.g. `sm_live_\u2026`"}, "BearerAuth": {"type": "http", "scheme": "bearer", "description": "The same API key sent as a Bearer token."}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "string"}}, "required": ["error"]}, "PolicyError": {"type": "object", "description": "A workspace policy rejected the write.", "properties": {"error": {"type": "string"}, "rule": {"type": "string"}, "scope": {"type": "string"}, "message": {"type": "string"}}, "required": ["error"]}, "AuthError": {"type": "object", "description": "Authentication / rate-limit failure envelope.", "properties": {"status": {"type": "integer"}, "message": {"type": "string"}}}, "ToolResult": {"type": "object", "description": "The tool's raw result. Tools that declare a result schema show it on their page instead of this placeholder; for the rest the exact shape is tool-specific \u2014 see the tool's description. Report tools return rows plus a `pagination` block and full-set `summary`.", "additionalProperties": true}}, "responses": {"BadRequest": {"description": "Invalid or missing arguments.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "Unauthorized": {"description": "Auth failed \u2014 always the generic `Invalid API key`.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthError"}}}}, "Forbidden": {"description": "Key scope doesn't permit this tool, or the account isn't allowed for this key.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "NotFound": {"description": "Unknown tool.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "PolicyViolation": {"description": "A workspace policy rejected the write.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PolicyError"}}}}, "RateLimited": {"description": "Rate limit exceeded or failed-auth lockout. Honor `Retry-After`.", "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthError"}}}}, "InternalError": {"description": "Internal error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}