---
title: Update Family Keywords
api: PATCH /brands/{brand_id}/families/{family_id}/keywords
description: "Replace the keyword list on a specific topic family."
---

> **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.

Replaces the keyword list on a single topic family. Useful when you want to hand-curate which keywords roll up under a family before re-running synthesis.

## Path parameters

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

<ParamField path="family_id" type="string" required>
  The family UUID. Get it from `GET /brands/{brand_id}/families`.
</ParamField>

## Request body

<ParamField body="keywords" type="object[]" required>
  The full keyword list to store on the family. This replaces the existing list — it is not a merge. The store accepts arbitrary dicts and only `keyword` is required; round-trip the same shape the discovery pipeline emits to keep downstream synthesis happy. The discovery pipeline writes keys like `keyword`, `google_vol` (DataForSEO monthly volume), `kd`, `intent`, `aio_present`, `content_exists`, `brand_position` — note `google_vol` is the canonical volume field, not `volume`.
</ParamField>

## Response

```json
{
  "family_id": "family-uuid",
  "keyword_count": 47
}
```

## Example

```bash
curl -X PATCH \
  -H "X-API-Key: $BM_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.boringmarketing.com/brands/$BRAND_ID/families/$FAMILY_ID/keywords \
  -d '{
    "keywords": [
      {"keyword": "ai marketing tools", "google_vol": 12000, "kd": 34},
      {"keyword": "best ai marketing software", "google_vol": 4800, "kd": 28}
    ]
  }'
```

<Tip>
After editing keywords on one or more families, run `POST /brands/{id}/synthesize` (30s) to re-score opportunities against the new keyword set without re-running discovery.
</Tip>