# Competitors

The brands you track alongside your own. The competitor ids returned here are the `actor_id` values the metrics endpoints report against.

### GET `/dimensions/competitors`

Lists competitors for the project.

### GET `/dimensions/competitors/:id`

Get detailed information about a competitor including matching names and app store IDs.

### POST `/competitors`

Add a competitor with its own citation URL matching rule. Honours the per-plan max competitors cap.

**Body (JSON):**

- `project_id` required
- `brand_name` required
- `domain` required, URL is normalised
- `matching_names` optional array
- `citation_match_mode` `domain`, `host` or `path_prefix`; default `domain`
- `citation_match_path` required for `path_prefix`

### PATCH/DELETE `/competitors/:id`

Update a competitor (brand_name, website domain or host, matching_names, color, citation URL matching) or delete it. Name, website and citation-rule changes re-run historical matching in the background (`processing: true` for a few minutes, edits blocked meanwhile). Deleting is irreversible and purges the competitor data in the background.

**PATCH body:**

- `project_id` required
- `brand_name`
- `domain` website domain or host; a full URL is normalised
- `matching_names` full replacement array
- `color` hex
- `citation_match_mode`
- `citation_match_path`

**DELETE:** `project_id` + `:id` in URL.

Full access. Cancel anytime.