---
title: Update Brand
api: PATCH /brands/{brand_id}
description: "Update a brand's name or competitor list."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.boringmarketing.com/llms.txt). Append `.md` to any page URL for its markdown version.

Partially update a brand. Only `name` and `competitors` are mutable via this endpoint — everything else (identity, brand_context, technical_context, etc.) is populated by the enrichment endpoints.

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID.
</ParamField>

## Request body

All fields are optional. Include only what you want to change.

<ParamField body="name" type="string">
  Updated brand display name.
</ParamField>

<ParamField body="competitors" type="Competitor[] | string[]">
  Replace the full competitor list. Accepts either an array of `Competitor` objects (`{domain, type, tier, confidence, reason_codes, source_tags, evidence}`) or an array of bare domain strings. Bare strings are auto-upgraded to `Competitor` objects with `type="business"`, `tier="adjacent"`, `confidence=0.0`. See [`GET /brands/{id}`](https://docs.boringmarketing.com/api-reference/brands/get) for the full `Competitor` shape.
</ParamField>

## Response

```json
{
  "id": "ea502f67-338b-47e4-a245-5c4eea8bd8d2",
  "domain": "yourdomain.com",
  "name": "Your Brand",
  "competitors": [
    {
      "domain": "competitor1.com",
      "type": "business",
      "tier": "direct",
      "confidence": 0.0,
      "reason_codes": [],
      "source_tags": [],
      "evidence": []
    }
  ],
  "updated_at": "2026-04-07T10:35:00Z"
}
```

<Note>
**409 Conflict** is returned (with an `X-Running-Run-Id` header) if a pipeline-modifying run is currently active for the brand. The blocking run kinds are: `full`, `discovery`, `brand_enrichment`, `llm_enrichment`, `scoring`, `competitor_discovery`. Non-blocking kinds — `technical_enrichment`, `brief`, `execution`, and `synthesize` — do not reject PATCH. Active runs older than 15 minutes are auto-expired and do not count as active.
</Note>

## Errors

| Status | Meaning |
|---|---|
| `404` | Brand not found, or not owned by the caller. |
| `409` | Pipeline-modifying run in progress — see the note above. Header: `X-Running-Run-Id`. |
| `422` | `brand_id` is not a valid UUID, or request body failed validation. |

## Example

<CodeGroup>
```bash cURL
curl -X PATCH \
  https://api.boringmarketing.com/brands/$BRAND_ID \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BM_API_KEY" \
  -d '{
    "competitors": ["competitor1.com", "competitor2.com"]
  }'
```

```python Python
resp = httpx.patch(
    f"https://api.boringmarketing.com/brands/{brand_id}",
    headers={"X-API-Key": api_key},
    json={"competitors": ["competitor1.com", "competitor2.com"]},
)
```
</CodeGroup>

<Tip>
After updating competitors, re-run scoring with `POST /brands/{id}/score` to refresh the action queue with the new context.
</Tip>