---
title: "Update alternative names"
method: PATCH
path: "/api/mcp/projects/{projectId}/brand-profile/alternative-names"
tags: ["Brand"]
---

# Update alternative names

`PATCH /api/mcp/projects/{projectId}/brand-profile/alternative-names`

## Request

- Base URL: `https://app.searchable.com`
- URL: `https://app.searchable.com/api/mcp/projects/{projectId}/brand-profile/alternative-names`
- Auth: HTTP bearer

Add, remove or replace the project's alternative names: other names the brand goes by (a former, local or shortened name), which count as the brand in every report. This is the app's Knowledge Base → Profile → Alternative names. Send `add` and/or `remove`, or `replace` on its own to set the whole list. Answers already collected follow the change. An added name's mentions under Other companies move to the brand. A removed name's brand mentions move to a competitor of that name, which is created if the project has none. Both moves run in the background, and a paused project queues neither. A name is matched ignoring case. Adding a name the project already has changes nothing and lists it in `alreadyPresent`. Removing a name it lacks returns 404 `not_found` and changes nothing. A project holds up to 25 names, each up to 120 characters. Adding needs the Member role; removing needs Owner, Super admin or Admin, since it creates competitors. Requires the `knowledge:manage` capability. A pitch project that is not currently active refuses with 409 `INACTIVE_PITCH_PROMPT_MUTATION`. The list reads back as `profile.alternativeNames` on the brand profile.

## Path parameters

- `projectId` string, uuid, required

## Request body

- UpdateAlternativeNamesRequest: The change to make: `add` and/or `remove`, or `replace` on its own.
  - `add` string[]: Names to add. A name the project already has is left as it is.
  - `remove` string[]: Names to remove, matched ignoring case. Each must be one of the project's alternative names.
  - `replace` string[]: The whole list the project should have; names not in it are removed. An empty list removes every name. Not combined with add or remove.

## Response `200`

Alternative names updated.

- UpdateAlternativeNamesResponse
  - `success` boolean, required
  - `alternativeNames` string[], required: The project's alternative names after the change.
  - `added` string[], required: Names this request added.
  - `removed` string[], required: Names this request removed, as they were saved.
  - `alreadyPresent` string[], required: Names asked for that the project already had; nothing changed for them.

## 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/brand-profile/alternative-names/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)