Skip to content

AdCP brand.json

The Ad Context Protocol (AdCP) puts a brand’s identity in one file, brand.json, at https://{domain}/.well-known/brand.json: its names, logos, colors, fonts and voice, for ad tech and agents. It is the open format Artbucket follows to publish a brand for machines, and it reads it back to start a brand.

  • BrandHub serves each public brand as a Brand Canonical Document, at /{org}/{brand}/brand.json, from its latest release (@{n} for another). A private or never-released brand has none.
  • A verified domain answers /.well-known/brand.json with an Authoritative Location Redirect to that document (below).
  • A new brand can be made from any domain’s brand.json (the import).

The document is drawn from the release’s rules, by key. Only the default context is read, but for logos, whose context versions are logos of their own. Where a field lists several keys, the first the brand has wins.

brand.json From
$schema https://adcontextprotocol.org/schemas/v3/brand.json
version The release number, as a string: "4"
last_updated When it was released
id The brand’s slug, - as _: acme_tools
names [{ "en": name }]: one name, in English
url https:// and the brand’s domain (its Settings, or the one it was made from), else the organization’s verified domain
house_domain The organization’s verified domain, when it proved one
description brand.description, brand.mission or brand.promise (text)
tagline brand.tagline or brand.slogan (text)
industries brand.industries (list)
disclaimers Each legal.disclaimer (text), as { text }
brand.json From
colors.{name} Every color rule under color., by the rest of its key in snake case: color.primary is primary, color.darkBlue is dark_blue. Six-digit hex: an alpha channel is dropped
colors.background Also from color.background, color.paper or color.white, when no rule is named background
colors.text Also from color.ink, color.text or color.black, when no rule is named text
visual_guidelines.colorways[] Each color whose spec.pair names another: { name: "{pair}_on_{color}", foreground: pair, background: color }
visual_guidelines.restrictions[] The entries of color.never (and neverDo, dont, donts, avoid, misuse) lists, with logo, type and imagery ones
brand.json From
fonts.{name} Every font rule under type., by the rest of its key in snake case: { family, files[], opentype_features, fallbacks }, from its family, its font files (on BrandHub, those it hands out: shown, not handed out), spec.features and spec.fallback
fonts.primary The same as type.heading, type.display, type.primary or type.headline
fonts.secondary The same as type.body, type.text, type.sans or type.secondary
visual_guidelines.type_scale.{role} A face with a size or a weight in its value, by spec.role: display and headline are heading, subhead is subheading, body, caption, button is cta; or by its name, when it is one of those. { font, size, weight, line_height, letter_spacing, text_transform } from its size (px), weight, spec.lineHeight, spec.tracking (in em) and spec.case

Every image of every logo.* rule, context versions included, is one logos[] entry; rules named like a do or a don’t (logo.never, logo.always) are not logos.

brand.json From
id The rest of the key, the context, and a number from the second image on: mark, primary_dark_background, mark_2
url The file, at the rendition the rule names: /a/{id}/w_512,f_png, signed for a day
variant logo.primary is primary; a key containing wordmark is wordmark; a lockup is full-lockup; a key containing mark, icon or symbol is icon; any other secondary
background dark-bg when the context says dark, or the key says dark, reversed, inverse or white
orientation stacked when the key says stack or vertical; else from the file’s size: horizontal past 1.25:1, vertical past 1:1.25, square between
slots An icon in the default context: favicon, app_icon, profile_mark
width, height The file’s
usage The rule’s usage
tags The rule’s key, and its context: how the import puts it back
visual_guidelines.logo_placement.min_clear_space logo.clearSpace, logo.minClearSpace or logo.margin: a number with its unit and spec.of (“1x the mark’s height”), or the text
visual_guidelines.logo_placement.min_height logo.minSize or logo.minHeight, the same way (“24px”; px when no unit)
visual_guidelines.restrictions[] The entries of logo.never and the like
brand.json From
tone.voice tone.voice or voice.voice (text)
tone.attributes tone.attributes, tone.pillars, tone.traits (lists, joined)
tone.dos tone.always, tone.do, tone.dos
tone.donts tone.avoid, tone.never, tone.dont, tone.donts
visual_guidelines.spacing.scale space.scale or spacing.scale (list): its first six steps as xs, sm, md, lg, xl, 2xl, numbers in px
assets[] Every image of every imagery.* rule: { asset_id, asset_type: "image", url, name, description, width, height, format, tags }, its description from the rule’s usage

What AdCP has no field for stays one link away, under ext.artbucket:

"ext": {
"artbucket": {
"release": 4,
"rules": "https://hub.example.com/acme/acme/rules.json",
"tokens": "https://hub.example.com/acme/acme/tokens?format=json",
"llms": "https://hub.example.com/acme/acme/llms.txt",
"guidelines": "https://press.acme.com"
}
}

rules is every rule, losslessly (rules.json); guidelines the portal BrandHub links as the brand’s guidelines, else its BrandHub page.

  • Colors: print values (cmyk, pantone, ral, rgb), tints, gradients (the solid is kept), groups and weights, each color’s label and usage, alpha, and every context version.
  • Type: a bare type scale (AdCP’s scale is by role), spec.license, spec.source and spec.download, and the weight and style of each file.
  • Logos: visual do’s (logo.always): AdCP has none.
  • Everything else: every rule outside the keys above, the brand’s pages and theme, and brand.audience. They are in rules.json.

A brand that holds these rules fills every field the export writes. The complete example holds them all.

To fill Write
description, tagline, industries brand.description and brand.tagline (text), brand.industries (list)
url, house_domain The brand’s domain in its Settings, and a verified domain for the organization
colors color.primary, color.secondary, color.accent, color.background, color.ink
colorways spec.pair on the grounds: color.primary paired with the color set on it
fonts, primary, secondary type.heading and type.body, with their font files
type_scale A size and a weight in each face’s value, and spec.role, lineHeight, tracking, case
logos logo.primary, logo.mark and logo.wordmark with their images, and a dark-background version of each with its reversed file
logo_placement logo.clearSpace (number, spec.unit: x, spec.of) and logo.minSize (number, spec.unit: px)
restrictions logo.never (and color.never) lists
tone tone.voice (text), tone.attributes, tone.always, tone.avoid (lists)
spacing space.scale, six numbers
assets imagery.* rules with images, their usage as the description
disclaimers legal.disclaimer

Then release the brand and make it public on BrandHub: the document is the release’s, so a change shows once it is released.

The export of the complete example’s release 4, with its organization’s verified domain acme.com:

{
"$schema": "https://adcontextprotocol.org/schemas/v3/brand.json",
"version": "4",
"house_domain": "acme.com",
"id": "acme",
"names": [{ "en": "Acme" }],
"url": "https://acme.com",
"description": "Acme makes hand tools for people who fix things.",
"tagline": "Tools that last.",
"industries": ["tools", "hardware"],
"logos": [
{ "id": "primary", "url": "https://assets.example.com/a/1b7e...?s=...", "variant": "primary", "orientation": "horizontal", "width": 480, "height": 120, "tags": ["logo.primary"] },
{ "id": "primary_dark_background", "url": "https://assets.example.com/a/9c40...?s=...", "variant": "primary", "orientation": "horizontal", "background": "dark-bg", "width": 480, "height": 120, "tags": ["logo.primary", "dark-background"] },
{ "id": "mark", "url": "https://assets.example.com/a/2f88.../w_512,f_png?s=...", "variant": "icon", "orientation": "square", "slots": ["favicon", "app_icon", "profile_mark"], "width": 512, "height": 512, "tags": ["logo.mark"] }
],
"colors": { "primary": "#1f6feb", "background": "#ffffff", "ink": "#0d1117", "text": "#0d1117" },
"fonts": {
"heading": { "family": "Inter", "files": [{ "url": "https://assets.example.com/a/6f1c...?s=..." }], "fallbacks": ["Helvetica", "Arial", "sans-serif"] },
"body": { "family": "Inter", "files": [{ "url": "https://assets.example.com/a/77d2...?s=..." }] },
"primary": { "family": "Inter", "files": [{ "url": "https://assets.example.com/a/6f1c...?s=..." }], "fallbacks": ["Helvetica", "Arial", "sans-serif"] },
"secondary": { "family": "Inter", "files": [{ "url": "https://assets.example.com/a/77d2...?s=..." }] }
},
"tone": {
"voice": "Plain and warm, like a friend who knows tools.",
"attributes": ["plain", "warm", "exact"],
"dos": ["Name the tool", "Say what it does"],
"donts": ["Jargon", "Exclamation marks"]
},
"visual_guidelines": {
"logo_placement": { "min_clear_space": "1x the mark's height", "min_height": "24px" },
"colorways": [
{ "name": "background_on_primary", "foreground": "#ffffff", "background": "#1f6feb" },
{ "name": "ink_on_background", "foreground": "#0d1117", "background": "#ffffff" }
],
"type_scale": {
"heading": { "font": "heading", "size": "40px", "weight": "700", "line_height": "1.1", "letter_spacing": "-0.02em" },
"body": { "font": "body", "size": "16px", "weight": "400", "line_height": "1.5" }
},
"spacing": { "scale": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px", "2xl": "48px" } },
"restrictions": ["Stretch or squash it", "Recolor it", "Set it on a busy photo"]
},
"assets": [
{ "asset_id": "examples", "asset_type": "image", "url": "https://assets.example.com/a/4a09...?s=...", "name": "workshop.jpg", "width": 2400, "height": 1600, "format": "jpeg", "tags": ["imagery.examples"] }
],
"disclaimers": [{ "text": "Acme is a trademark of Acme Tools Ltd." }],
"last_updated": "2026-09-30T10:00:00.000Z",
"ext": {
"artbucket": {
"release": 4,
"rules": "https://hub.example.com/acme/acme/rules.json",
"tokens": "https://hub.example.com/acme/acme/tokens?format=json",
"llms": "https://hub.example.com/acme/acme/llms.txt",
"guidelines": "https://press.acme.com"
}
}
}

File URLs are signed for a day: an agent that keeps the document should fetch it again rather than keep its URLs.

To have agents that read your domain find the brand, host one file at https://{domain}/.well-known/brand.json, an Authoritative Location Redirect. The brand’s Sharing tab gives it:

{"$schema":"https://adcontextprotocol.org/schemas/v3/brand.json","authoritative_location":"https://hub.example.com/acme/acme/brand.json"}

A domain the organization verified, serving the app or one of its portals, answers /.well-known/brand.json itself, from the organization’s public, released brands (on a portal’s domain, those the portal shows):

  • the one whose domain the host proves, else the only one, else the default one, as an Authoritative Location Redirect to it on BrandHub;
  • with several and none of those, a House Portfolio of them all, inline: { "$schema", "version": "1", "house": { "domain", "name" }, "brands": [...] }.

Any other host answers 404.

The public Brand Agent Score reads a domain’s /.well-known/brand.json (or the brand.json its llms.txt links) for its rules. An Authoritative Location Redirect there is followed once, over https, so the one-line file above is enough for the score to read the brand on BrandHub.

New brand, From a domain in the app, or POST /api/v1/brands with domain (or the document itself as brandJson), makes a brand from a brand.json: making one has the steps. It is the export run backwards, so a document Artbucket wrote comes back as it was, as far as the document says it.

brand.json Rule
names The brand’s name: the English one, else the document’s default_language, else the first
id The brand’s slug, _ as -
url, else the primary website in properties, else the domain read The brand’s domain
description brand.description
tagline brand.tagline
industries brand.industries
target_audience brand.audience
colors.{role} color.{role} in camel case (dark_blue is color.darkBlue); an array gives color.{role}, color.{role}2, … background and text only when they add a color
visual_guidelines.colorways The ground color’s spec.pair: by name for the export’s own {pair}_on_{color}, else by matching hexes
fonts.{role} type.{role}: the first family of the stack, the rest and fallbacks as spec.fallback, opentype_features as spec.features, each file ingested. primary and secondary only when they add a face
visual_guidelines.type_scale.{role} The face’s size and weight, and spec.role, lineHeight, tracking, case
logos By their tags when the export wrote them (key and context); else logo.primary, logo.secondary, logo.mark (icon), logo.wordmark, logo.lockup (full-lockup) by variant, dark-bg ones in the dark-background context; each image ingested
logo_placement.min_height, min_clear_space logo.minSize, logo.clearSpace: a number with its unit and spec.of, or text
restrictions logo.never
tone.voice, attributes, dos, donts tone.voice, tone.attributes, tone.always, tone.avoid; a tone that is a string is the voice
spacing.scale space.scale, from xs to 2xl
assets (images) By their tags when they name an imagery.* rule, else imagery.library; each image ingested
disclaimers legal.disclaimer, joined
  • Localized fields (AdCP 3.2’s tagline, tone.*, an asset’s name and description) are read in English, else in the document’s default_language, else as their plain value; never whichever translation comes first. A localized list is taken whole.
  • Documents of other shapes: an Authoritative Location Redirect is followed once, exactly; a House Portfolio offers each of its brands, and its brand_refs are read at their own domains, ten at most; a document that only points at its house, or only names a brand agent, makes no brand and says why.
  • Dropped: what has no place in the rules (keller_type, house_domain, trademarks, agents, brand_agent, contact, privacy_policy_url, visual_guidelines.photography, motion, graphic_style, the other logo_placement fields, colors that aren’t six-digit hex, assets that aren’t images) is listed in the answer’s dropped, by its path. A logo or font file that won’t fetch is listed in skipped. Neither refuses the brand.

The document is fetched as the protocol says: over https only, from public hosts, at most 512 KB and 20 seconds, redirected only to the domain’s exact www twin and back.