SellerMate Public API

Every request must carry your API key, sent either way:

1X-API-Key: sm_live_xxxxxxxxxxxxxxxxxxxx
Copy

or

1Authorization: Bearer sm_live_xxxxxxxxxxxxxxxxxxxx
Copy

• Keys look like sm_live_….
• A workspace admin creates a key in the SellerMate web app (Profile → API Keys). The full key is shown once, at creation — store it securely; it can’t be retrieved later.
• A key is scoped to a single workspace, can be limited to specific Amazon accounts, and can be revoked at any time (revocation takes effect immediately).

Three independent checks apply to every call — all must pass:

Per-key rate limit: default 120 requests/minute. Exceeding it returns 429 with a Retry-After header (seconds) — honor it before retrying.

Failed-auth lockout: repeated invalid-key attempts from one IP are locked out (429 + Retry-After). Don’t retry on a 401 — a bad key won’t start working.

Response shapes

• Success: the tool’s result object, returned directly (no wrapper).
• Auth / rate-limit errors: { "status": <code>, "message": "..." }
• Tool errors: { "error": "..." } (policy violations also include rule, scope, message).

Status codes

Every tool is invoked the same way: POST /public/v1/tools/{tool_name} with a JSON object of arguments. A few rules apply across all tools, so each tool below only lists what’s unique to it.

• Account selection. workspace_id is taken from your key automatically. If your key is limited to one Amazon account, amazon_account_id is filled in for you too; if your key spans multiple accounts, pass amazon_account_id to choose one. Call get_user_context to list the accounts (and their accountType: seller / vendor / agency) your key can use. (get_marketplace_summary takes a list, amazon_account_ids, to span accounts.)
• Dates are YYYY-MM-DD strings (start_date, end_date). Exception: get_sqp_report uses integer month + year.
• Pagination. Report/list tools return a pagination block — { page, pageSize, total, totalPages, hasMore, nextCursor } — alongside the rows. Pass page (0-indexed, default 0) and page_size (default 100, max 500) to walk pages. summary/totals always cover the full result set, not the page. (Catalog tools use limit/offset instead — noted inline.)
• Sorting (performance tools): sort_field (a metric) + sort_direction (asc|desc, default desc).
• Common metrics: cost (spend), attributedSales14d (sales), impressions, clicks, purchases (orders), acos, roas, ctr, cpc, cvr.
• Authoritative schema: GET /public/v1/tools/{name} returns the live JSON Schema for any tool — the source of truth if this page ever lags the API.

GET /public/v1/tools

List the tools your key can use (filtered to its scope). Each entry includes the tool’s JSON Schema — handy for discovery and codegen.

1curl -s https://api.sellermate.ai/public/v1/tools -H "X-API-Key: sm_live_..."
Copy

GET /public/v1/tools/{name}

Return the JSON Schema for one tool. 404 if unknown or outside your scope.

POST /public/v1/tools/{name}

Invoke a tool. Body = the tool’s arguments. Returns the raw tool result.

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_campaign_performance \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \
3  -d '{"start_date":"2026-05-01","end_date":"2026-05-31"}'
Copy

GET /public/v1/openapi.json

Machine-readable OpenAPI 3.1 spec for the whole API — one documented operation per tool, generated live from the same registry the API serves. No auth required. Import it into Postman or Insomnia, or feed it to a codegen. Rendered as a browsable reference at /api-docs/reference.

The full tool catalog — every tool’s parameters, JSON schema, scope (R tools:read / W tools:write), and sample requests in curl, Python, and Node — lives in the interactive reference. It’s generated from the live API, so it always matches what your key can actually call, including tools added after this page was written.

• Account arguments: workspace_id is never sent (bound to your key); amazon_account_id is auto-filled for single-account keys — see §4.
• Your key is the filter: GET /public/v1/tools returns exactly the tools your key’s scopes allow — the reference shows the full catalog.

Discover your accounts

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_user_context \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" -d '{}'
Copy

1{
2  "user": { "id": "...", "name": "API Key: Reporting" },
3  "workspaces": [{
4    "id": "<workspace_id>", "name": "Acme",
5    "accounts": [
6      { "id": "<amazon_account_id>", "name": "Acme US", "accountType": "seller",
7        "country": "US", "currency": "USD", "marketplace": "ATVPDKIKX0DER" }
8    ]
9  }]
10}
Copy

Campaign performance (paginated)

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_campaign_performance \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \
3  -d '{"amazon_account_id":"<id>","start_date":"2026-05-01","end_date":"2026-05-31","page_size":50}'
Copy

1{
2  "data": [ { "campaignName": "...", "cost": 1234.5, "attributedSales14d": 5678.9, "acos": 21.7, "roas": 4.6 } ],
3  "summary": { "...": "full-set totals" },
4  "pagination": { "page": 0, "pageSize": 50, "total": 190, "totalPages": 4, "hasMore": true, "nextCursor": "..." },
5  "dateRange": { "start": "2026-05-01", "end": "2026-05-31" }
6}
Copy

Vendor sales by ASIN

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/get_vendor_sales_performance \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \
3  -d '{"amazon_account_id":"<vendor_account_id>","start_date":"2026-05-01","end_date":"2026-05-31"}'
Copy

1{
2  "connected": true,
3  "data": [
4    { "asin": "B0XXXXXXX1", "itemName": "...",
5      "orderedUnits": 1240, "orderedRevenueAmount": 38760.00,
6      "shippedUnits": 1180, "shippedRevenueAmount": 36890.00, "shippedCogsAmount": 21500.00,
7      "customerReturns": 14, "glanceViews": 90250 }
8  ],
9  "summary": { "orderedRevenueAmount": 38760.00, "shippedRevenueAmount": 36890.00, "glanceViews": 90250, "asins": 1 },
10  "pagination": { "page": 0, "pageSize": 100, "total": 1, "hasMore": false }
11}
Copy

Update a campaign budget (requires tools:write)

1curl -s -X POST https://api.sellermate.ai/public/v1/tools/update_campaign \
2  -H "X-API-Key: sm_live_..." -H "Content-Type: application/json" \
3  -d '{"updates":[{"campaign_id":"<id from list_campaigns>","budget":25.0}],"_reasoning":"Scaling a winner"}'
Copy

Outcomes: applied → { "status":"success", "applied":true, ... }; blocked by policy → 422 { "error":"Policy violation …", "rule":"maxBudget" }; needs approval → { "status":"pending_approval", "applied":false, "rollback_token":"…" }.

Python quickstart

1import requests
2
3BASE, KEY = "https://api.sellermate.ai", "sm_live_..."
4H = {"X-API-Key": KEY, "Content-Type": "application/json"}
5
6def call(tool, **args):
7    r = requests.post(f"{BASE}/public/v1/tools/{tool}", headers=H, json=args, timeout=120)
8    r.raise_for_status()
9    return r.json()
10
11ctx = call("get_user_context")
12account_id = ctx["workspaces"][0]["accounts"][0]["id"]
13perf = call("get_campaign_performance", amazon_account_id=account_id,
14            start_date="2026-05-01", end_date="2026-05-31")
15print(perf["summary"])
Copy

• Per-call batch cap: write tools accept at most 50 items in updates per call.
• One-time secret: an API key’s value is shown only at creation; lost keys must be revoked and recreated.
• Revocation is immediate: a revoked key returns 401 on the next call.
• SP-API / Vendor tools return { "connected": false, "connectUrl": … } when the required Seller/Vendor Central connection is missing — that’s a normal response, not an error.
• Discovery is authoritative: GET /public/v1/tools (and /tools/{name}) always reflects the live set of tools and parameters available to your key.