Skip to content

A brand from a domain

The Ad Context Protocol puts a brand’s identity at https://{domain}/.well-known/brand.json: its names, logos, colors, fonts and voice, for ad tech and agents. Artbucket reads that file to start a brand, and writes it for every public brand on BrandHub (/{org}/{brand}/brand.json).

In the app: New brand, Start here, From a domain, type the domain and Look it up. It shows what it found, each brand of a house with its colors, faces and logos, and what it leaves out; pick one and Create brand. Over the API:

Terminal window
# What it holds, before making anything
curl -H "Authorization: Bearer $KEY" 'https://assets.example.com/api/v1/brand-json?domain=acme.com'
# Make it, release it and list it on BrandHub in one call
curl -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
-d '{"domain": "acme.com", "publish": {"note": "From acme.com'"'"'s brand.json"}, "visibility": "public"}' \
https://assets.example.com/api/v1/brands

POST /api/v1/brands takes domain, or the document itself as brandJson (then domain, if given, says where it came from), with brand to pick one of a house’s brands by its AdCP id (the one at domain, or the only one, when left out), and name and slug to override the document’s. MCP’s create_brand takes the same. The file is read 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. An Authoritative Location Redirect is followed once, exactly, and a House Portfolio’s brand_refs are read at their own domains, ten at most.

What becomes what is the export’s mapping run backwards: colors, faces and their files, logos by variant, voice, spacing, imagery and disclaimers become rules, and each logo, font file and image is ingested into the library. What has no place in the rules is left out and listed in the answer’s dropped; a file that won’t fetch is listed in skipped, rather than refusing the brand. AdCP brand.json has the table, field by field.

A brand made from a brand.json keeps its domain: the document’s own url, else its primary website, else the domain it was read from (lower-cased, without www). A brand made from a template keeps the template brand’s (firefox.com, rust-lang.org, blender.org). Any brand’s can be set or cleared on its Settings tab, under Name and address, or with PATCH /api/v1/brands/{slug} and {"domain": "acme.com"}. Its BrandHub listing shows it, index.json lists it, and its brand.json gives it as url. A domain names a brand, it proves nothing: several brands, in several organizations, may name the same one, and only a domain the organization verified shows as verified.

Whoever proves a listing’s domain can claim it: see Claim by domain.

Every public brand’s brand.json on BrandHub is a Brand Canonical Document. For agents that read your domain to find it, host the one-line Authoritative Location Redirect the Sharing tab gives at https://{domain}/.well-known/brand.json. A verified domain that serves Artbucket (the app or a portal) answers that address itself. Your domain says what it answers, and the export what the document holds.