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

# Resolve brand

> Look up a brand profile on the AAO registry by domain

`POST /api/v2/storefront/resolve-brand`

Looks up a brand profile on agenticadvertising.org by domain using a fresh,
authoritative registry read. Returns the brand name, logo URL, and profile
metadata when found. When no profile exists, returns `resolved: false` plus a
`builderUrl` where the brand can register one. This endpoint never substitutes
Brandfetch or website-inferred identity.

## Request

```bash curl theme={null}
curl -X POST https://api.apostra.com/api/v2/storefront/resolve-brand \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "northwind.example" }'
```

## Parameters

| Field | Type | Required | Notes |
| - | - | - | - |
| `domain` | string | Yes | Brand domain to resolve. Must be a valid domain (e.g. `"northwind.example"`) |

## Response

```json Resolved theme={null}
{
  "resolved": true,
  "domain": "northwind.example",
  "brandName": "Northwind Athletics",
  "logoUrl": "https://cdn.agenticadvertising.org/logos/northwind.png",
  "logoBackground": "light-bg",
  "manifestUrl": "https://northwind.example/.well-known/brand-manifest.json",
  "manifest": {},
  "registryEntry": {},
  "authorizedOperators": [],
  "houseBrand": {
    "houseName": "Acme House",
    "houseDomain": "acme.example",
    "architecture": "branded_house",
    "brands": []
  }
}
```

```json Not resolved theme={null}
{
  "resolved": false,
  "domain": "newbrand.example.com",
  "error": "Brand profile not found",
  "builderUrl": "https://agenticadvertising.org/brand"
}
```

| Field | Type | Description |
| - | - | - |
| `resolved` | boolean | Whether a brand profile was found |
| `domain` | string | The domain that was resolved |
| `brandName` | string | Brand display name. Present when resolved |
| `logoUrl` | string \| null | Brand logo URL, or `null` when none is published |
| `logoBackground` | `"dark-bg"` \| `"light-bg"` \| `"transparent-bg"` \| null | Hint for the UI on which background the logo renders well. Present when resolved and a logo exists |
| `manifestUrl` | string | URL of the resolved brand.json |
| `manifest` | object | The resolved brand.json body |
| `registryEntry` | object \| null | Raw AAO registry entry, or `null` |
| `authorizedOperators[]` | array | Operators authorized to transact for this brand |
| `houseBrand` | object \| null | House-brand metadata when the brand is a house brand of the operator: `{ houseName, houseDomain, architecture?, brands[] }`. Absent or `null` when not a house brand |
| `warning` | string | Advisory message, when present |
| `error` | string | Resolution error message, when present |
| `builderUrl` | string | Set when `resolved` is `false` — URL where the brand can register a profile |

## Errors

* `400 VALIDATION_ERROR` — `domain` missing or empty.
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `503 SERVICE_UNAVAILABLE` — the AAO registry could not complete the required
  fresh lookup. Retry later; the Storefront's currently persisted identity is
  left unchanged.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Storefront tasks" href="/v2/storefront/tasks" icon="list-check">
    All core storefront operations.
  </Card>

  <Card title="Discover agents" href="/v2/storefront/tasks/discover-agents" icon="magnifying-glass">
    Find the agents authorized for an operator domain.
  </Card>

  <Card title="Buyer instructions" href="/v2/storefront/buyer-instructions/overview" icon="user-gear">
    Scope discounts and notes by buyer brand domain.
  </Card>
</CardGroup>


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