bulk_update_competitor_status

bulk_update_competitor_status is the write tool of the competitor set. It updates the status of one or more competitors in a single call, up to 50 per batch. Use it to act on the auto-detection queue surfaced by list_competitors: confirm real competitors, reject noise, or reset previously dismissed entries to SUGGESTED. On an e-commerce project (see update_project_settings), it also moves an entity between the three groups the AI sorts into: competitor brands, retailers (where the buyer is sent: Amazon, pharmacies, marketplaces) and products (product names).

When to use

Use it when the user gives a moderation instruction such as "confirm all the competitors I see here", "reject these three brand-name false positives", or "reset Otterly back to suggested for re-review". On an e-commerce project, it also handles "Amazon is a retailer, not a competitor". It is the right tool for any agent that triages the suggestion queue automatically based on rules. Pair with list_competitors (filter status: ["SUGGESTED"]) to fetch the candidates first.

Requires member role minimum, customer role rejected.

Input

Each update needs status, kind, or both:

• kind: "COMPETITOR" confirms the entity as a competitor (status CONFIRMED).
• kind: "RETAILER" or "PRODUCT" moves it out of the competitors: its verdict is set and its status becomes SUGGESTED, never CONFIRMED. It works on a rejected entity too. These two values need an e-commerce project, otherwise the item fails with not_ecommerce.

Response

The response carries updated/failed counts and a per-item results array. Per-item errors do not block the rest of the batch: valid updates still apply, and success flips to false only to flag that at least one item failed.

{
  "success": true,
  "updated": 2,
  "failed": 0,
  "results": [
    {
      "competitorId": "clxcomp001",
      "status": "success",
      "competitor": {
        "id": "clxcomp001",
        "canonicalName": "Otterly",
        "status": "CONFIRMED",
        "verdict": "COMPETITOR",
        "updatedAt": "2026-04-26T10:15:00.000Z"
      }
    },
    {
      "competitorId": "clxcomp002",
      "status": "success",
      "competitor": {
        "id": "clxcomp002",
        "canonicalName": "Amazon",
        "status": "SUGGESTED",
        "verdict": "RETAILER",
        "updatedAt": "2026-04-26T10:15:00.000Z"
      }
    }
  ]
}

Each competitor carries its new status and verdict (null when the entity has never been judged).

If a competitor ID is invalid or belongs to another project, the entry returns status: "error" with an error code (competitor_not_found) and a message. A RETAILER or PRODUCT kind on a project that is not e-commerce returns not_ecommerce. In both cases, success is set to false for the whole batch. Other valid updates still apply.

Tips and patterns

• Always read success and the per-item results[].status to detect partial failures.
• Batch up to the 50-item limit to minimise round trips. If the list is bigger, paginate.
• Confirm a customer user gracefully: catch the role-rejection error and route the request to a higher-privileged member.
• To clean an e-commerce project, list entities with list_competitors and filters.verdict, then send the wrong ones back with kind.
• Resetting to SUGGESTED re-injects the competitor into the moderation queue; do not use it as a soft-delete.

Related tools

• list_competitors: list the candidates to act on (use filters.status: ["SUGGESTED"]).
• list_competitor_sources: inspect a competitor's footprint before deciding to confirm or reject.
• update_project_settings: turn on e-commerce mode so RETAILER and PRODUCT are accepted.