> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating brand identity

> Migrate AdCP brand identity from beta.3 to rc.1. Replaces inline brand_manifest objects with BrandRef references resolved via brand.json or the community registry.

# Migrating brand identity

AdCP 3.0 rc.1 replaces inline `brand_manifest` objects with lightweight brand references (`BrandRef`). Brand data is resolved at execution time from `/.well-known/brand.json` or the community brand registry.

## What changed

| beta.3 | rc.1 | Notes |
| - | - | - |
| `brand_manifest` (inline object) | `brand` (`BrandRef`) | Reference resolved at execution time |
| Brand data passed in every request | Brand data fetched once from `brand.json` | Caching recommended (24h TTL) |
| No standard identity format | `/.well-known/brand.json` specification | Four variants: House Portfolio, Brand Agent, House Redirect, Authoritative Location |

## BrandRef schema

A brand reference identifies a brand by domain and optional `brand_id`:

```json theme={null}
{
  "$schema": "https://adcontextprotocol.org/schemas/3.3.0-beta.0/core/brand-ref.json",
  "domain": "nova-brands.com",
  "brand_id": "spark"
}
```

* `domain` (required) — Domain where `/.well-known/brand.json` is hosted, or the brand's operating domain
* `brand_id` (optional) — Brand identifier within a house portfolio. Omit for single-brand domains.

For single-brand domains:

```json theme={null}
{
  "domain": "acme-corp.com"
}
```

## Where brand appears

| Task | Required? | Purpose |
| - | - | - |
| `create_media_buy` | Yes | Campaign identity — immutable once set |
| `get_products` | No | Discovery context. Required when `catalog` is provided |
| `build_creative` | No | Resolves to colors, logos, tone for creative generation |

`brand` does not appear on `update_media_buy` (immutable from creation), `sync_creatives` (scoped to account), or `sync_catalogs` (scoped to account).

## Before and after

**beta.3 — inline brand\_manifest on create\_media\_buy:**

```json test=false theme={null}
{
  "brand_manifest": {
    "name": "Spark",
    "domain": "spark.nova-brands.com",
    "logo_url": "https://spark.nova-brands.com/logo.png",
    "industries": ["technology.hardware"]
  },
  "account": { "account_id": "acct_nova" },
  "start_time": "2025-04-01T00:00:00Z",
  "end_time": "2025-04-30T23:59:59Z"
}
```

**rc.1 — brand reference:**

```json test=false theme={null}
{
  "brand": {
    "domain": "nova-brands.com",
    "brand_id": "spark"
  },
  "account": { "account_id": "acct_nova" },
  "start_time": "2025-04-01T00:00:00Z",
  "end_time": "2025-04-30T23:59:59Z"
}
```

The seller resolves `nova-brands.com` + `spark` to the full brand identity (logos, colors, tone, properties) via the Brand Protocol.

## Resolution flow

Given a `BrandRef`, the resolution is:

1. Fetch `https://{domain}/.well-known/brand.json`
2. If it's a **House Redirect** (has `house` field), follow to the house domain (max 3 redirects)
3. If it's a **House Portfolio**, look up the brand by `brand_id` in the `brands` array
4. If it's a **Brand Agent**, call the MCP agent for dynamic brand data
5. If it's an **Authoritative Location**, follow the `location` URL

Sellers cache resolved brand data (recommended 24-hour TTL for validated files, 1 hour for failed lookups).

## Migration steps

**1. Replace brand\_manifest with brand**

In all task requests (`create_media_buy`, `get_products`, `build_creative`), replace the `brand_manifest` object with a `brand` BrandRef: `{ "domain": "...", "brand_id": "..." }`.

**2. Host brand.json**

Publish `/.well-known/brand.json` on the brand's domain. Choose a variant: House Portfolio for multi-brand companies, Brand Agent for dynamic data, or single-brand for simple cases.

**3. Register in brand registry**

If the brand domain doesn't host `brand.json`, register it in the community brand registry so sellers can resolve it.

**4. Update seller resolution**

Seller agents must resolve `BrandRef` to full brand data at execution time. Implement caching and handle all four `brand.json` variants.

**5. Remove inline brand data**

Remove any code that constructs or parses `brand_manifest` objects. Brand data is no longer passed inline.

**6. Validate against schema**

Run requests against `brand-ref.json` schema. The `domain` field requires a valid lowercase domain pattern.

> **[Brand identity](/dist/docs/3.3.0-beta.0/brand-protocol/brand-json)**
>
> Full reference for brand.json variants, the brand registry, and BrandRef resolution.

***

**Related:** [Channels](/dist/docs/3.3.0-beta.0/reference/migration/channels) | [Catalogs](/dist/docs/3.3.0-beta.0/reference/migration/catalogs) | [Brand Protocol](/dist/docs/3.3.0-beta.0/brand-protocol) | [AdCP 3.0 overview](/dist/docs/3.3.0-beta.0/reference/whats-new-in-v3)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.