---
title: "Edit a competitor"
method: PATCH
path: "/api/mcp/projects/{projectId}/competitors/{competitorId}"
tags: ["Competitors"]
---

# Edit a competitor

`PATCH /api/mcp/projects/{projectId}/competitors/{competitorId}`

## Request

- Base URL: `https://app.searchable.com`
- URL: `https://app.searchable.com/api/mcp/projects/{projectId}/competitors/{competitorId}`
- Auth: HTTP bearer

Edit a tracked competitor as the in-app competitor sheet does: rename it, change its website domain, make it a direct or a SERP competitor, and add or remove the other names it goes by (name variations), which is how its mentions are recognised in AI answers. Changing the domain, or making it direct, re-matches its past mentions in the background. Everything is checked before anything is written: a variation that is another competitor's name is refused with 409 `conflict` (merge the two in the app instead), and removing a name the competitor does not have is refused with 400. A name confirmed as another competitor's variation moves to this one. A body with no fields changes nothing and answers with the competitor and its name variations. Requires the `competitor:match` capability and a manage-tier role, as in the app. A pitch project that is not currently active refuses with 409 `INACTIVE_PITCH_PROMPT_MUTATION`.

## Path parameters

- `projectId` string, uuid, required
- `competitorId` string, uuid, required

## Request body

- UpdateCompetitorRequest
  - `name` string: The competitor's new name.
  - `domain` string: Its website domain, e.g. example.com.
  - `isDirectCompetitor` boolean: true makes it a direct competitor, explicitly tracked; false makes it a SERP competitor, one that appears when AI results mention it.
  - `addVariations` string[]: Other names it goes by, to add.
  - `removeVariations` string[]: Name variations to remove. Each must be one it has.

## Response `200`

Competitor updated.

- UpdateCompetitorResponse
  - `success` boolean, required
  - `competitor` object, required
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `domain` string, nullable, required
    - `isDirectCompetitor` boolean, required
  - `variations` string[], required: Its name variations after the edit.
  - `added` object[], required: The variations added. movedFrom names the competitor a confirmed variation moved off.
    - `name` string, required
    - `movedFrom` object, nullable, required
      - `id` string, uuid, required
      - `name` string, nullable, required
  - `removed` string[], required: The variations removed.

## Other responses

- `400`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `401`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `403`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `404`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `409`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `429`: Rate limited. Usually the per-API-key REST limit (600 requests/minute); on Google-backed endpoints it can also relay an upstream Google rate limit. `Retry-After` (seconds) is present when the limit was applied by Searchable's own rate limiter; it may be absent when an upstream provider rate-limits.

## Changes

- **2026-11-03** `28a5e2a65cd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/searchable/apis/searchable-rest-api/changes/api/mcp/projects/:projectId/competitors/:competitorId/patch.md)

---

[API](https://skmtc.dev/searchable/apis/searchable-rest-api.md) - [All operations](https://skmtc.dev/searchable/apis/searchable-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/searchable/apis/searchable-rest-api/revisions/a1cc70e46e73?raw)