---
title: Get Brand
api: GET /brands/{brand_id}
description: "Retrieve a brand's full context including identity, competitors, brand pages, technical audit, and voice profile."
---

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

Returns the full brand context. The response includes every field the pipeline has populated so far — brand identity (from enrichment), crawled pages, competitors, technical audit results, and voice profile.

## Path parameters

<ParamField path="brand_id" type="string" required>
  The brand UUID returned from `POST /brands`.
</ParamField>

## Response

```json
{
  "id": "ea502f67-338b-47e4-a245-5c4eea8bd8d2",
  "domain": "yourdomain.com",
  "name": "Your Brand",
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-07T10:28:00Z",

  "competitors": [
    {
      "domain": "competitor1.com",
      "type": "business",
      "tier": "direct",
      "confidence": 0.82,
      "reason_codes": ["same_jtbd", "shared_icp"],
      "source_tags": ["tavily_research"],
      "evidence": ["https://example.com/article"]
    }
  ],

  "description": "What your company does, extracted from crawl.",
  "positioning": "Where you sit in the category.",
  "icp": "Target customer profile.",
  "services": ["service 1", "service 2"],
  "capabilities": ["capability 1", "capability 2"],
  "differentiators": ["why you are different"],
  "terminology": ["priority_term", "house_term"],
  "product_category": "marketing-intelligence",
  "business_model": "saas",

  "voice_profile": {
    "tone": ["direct", "anti-hype"],
    "banned_phrases": [],
    "preferred_patterns": []
  },

  "brand_identity": { "additional_identity_fields": "..." },

  "brand_context": null,
  "technical_context": null,
  "llm_context": null,

  "brand_pages": [
    { "url": "https://yourdomain.com/", "title": "Home", "word_count": 842 }
  ]
}
```

### `competitors` — array of `Competitor` objects

Each element is a full `Competitor` object, not a bare domain string:

| Field | Type | Notes |
|---|---|---|
| `domain` | `string` | Normalized (lowercased, protocol and `www.` stripped, trailing slashes removed). |
| `type` | `"business" \| "serp" \| "content"` | Unknown values normalize to `"business"`. |
| `tier` | `"direct" \| "adjacent" \| "content"` | Unknown values normalize to `"adjacent"`. |
| `confidence` | `float` | 0.0–1.0. |
| `reason_codes` | `string[]` | Why this competitor was added (e.g. `same_jtbd`, `shared_icp`). |
| `source_tags` | `string[]` | Which system surfaced it (e.g. `tavily_research`, `manual`). |
| `evidence` | `string[]` | URLs / quotes supporting the classification. |

`PATCH /brands/{id}` accepts **either** full `Competitor` objects **or** bare strings — bare strings are auto-upgraded with default `type="business"`, `tier="adjacent"`, `confidence=0`.

### Context fields are nullable

`brand_context`, `technical_context`, and `llm_context` are typed as `object | null` with **no guaranteed schema**. They are `null` until the corresponding enrichment runs:

| Field | Populated by |
|---|---|
| `brand_context` | `POST /brands/{id}/enrich/brand` (may contain trust signals, certifications, testimonials — exact keys depend on what the crawl surfaced) |
| `technical_context` | `POST /brands/{id}/enrich/technical` (typically `health_score`, `pages_crawled`, `issues_count`, `crawl_date`) |
| `llm_context` | `POST /brands/{id}/enrich/llm` (typically per-platform citation counts) |

Treat the inner shape as advisory. The pipeline may add, rename, or reshape keys without a breaking change to the brand response — your consumer should tolerate unknown keys and `null`.

### `terminology`

`list[str]`, not a dict. Each entry is a canonical term the brand prefers to use in drafts.

## Field notes

| Field | Populated by |
|-------|--------------|
| `description`, `positioning`, `icp`, `services`, `capabilities`, `differentiators`, `terminology`, `product_category`, `business_model`, `voice_profile`, `brand_identity`, `brand_context`, `brand_pages` | `POST /brands/{id}/enrich/brand` |
| `technical_context` | `POST /brands/{id}/enrich/technical` |
| `llm_context` | `POST /brands/{id}/enrich/llm` |
| `competitors` | `POST /brands/{id}/discover-competitors` or `PATCH /brands/{id}` |

Freshly created brands have most fields empty or null until the enrichment endpoints run.

## Errors

| Status | Meaning |
|---|---|
| `404` | Brand not found, or not owned by the caller. |
| `422` | `brand_id` is not a valid UUID. |

## Example

<CodeGroup>
```bash cURL
curl -H "X-API-Key: $BM_API_KEY" \
  https://api.boringmarketing.com/brands/$BRAND_ID
```

```python Python
brand = httpx.get(
    f"https://api.boringmarketing.com/brands/{brand_id}",
    headers={"X-API-Key": api_key},
).json()
print(f"Pages crawled: {len(brand.get('brand_pages') or [])}")
```
</CodeGroup>