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

# Brands

> Save brand guidelines for future pre-tests.

Ad Score uses brand guidelines to check how a creative uses colors, logos and taglines. Before creating a brand, look it up under `brands` in `GET /adscore/catalog` or `adscore_get_catalog` with `adscore:read`. Each entry includes an `id` and `readiness` flags for the available guidelines.

## Permission to save

Saving requires `brands:write` and a current Editor or Administrator role in the workspace. When you connect, the connector already requests `brands:write` along with the Ad Score permissions. The permission comes with the role: on the Unite consent screen, you only choose the workspace. For Editors and Administrators, the list of what the app will be able to do includes **Create and complete brands**, and the connection gets `brands:write` with the rest. Viewers never receive the permission and connect read only. Depending on your settings, the app may ask for confirmation before saving.

A connection made earlier, or by an app that did not request `brands:write`, does not gain the permission on its own: an automatic refresh keeps the previous permissions. If the app calls a brand tool without the permission, the response is [`insufficient_scope`](https://docs.myunite.ai/en/errors#insufficient_scope) and asks for the permissions the connection already has plus `brands:write`. When you connect again with that request, Ad Score stays available and brands can be saved. You can use a guide you already have in a presentation without this permission. For the API, ask an administrator for a key with the brand scope.

## Create or complete a brand

| Operation | API | Tool |
| - | - | - |
| Create | `POST /api/v1/brands` | `unite_create_brand` |
| Complete | `PATCH /api/v1/brands/{id}` | `unite_update_brand` with `brandId` |

Set `source` to `brand_book` for the official guidelines, `user` for information the person supplied, or `web` for web research. Prefer the official guidelines. You can research and present a proposal. Before **saving** web research, show the proposed values, ask the person to confirm them, then send `userConfirmed: true`.

Creation requires `name`. To complete a brand, send at least one brand field. This example adds a color and tagline from the brand book of the fictional brand Brisa:

```bash theme={null}
curl -X PATCH "https://myunite.ai/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"brand_book","colors":["#176B60"],"taglines":["Brisa up close"]}'
```

Use three- or six-digit hex colors. For a logo, pass `logoUploadId`. For other visual assets, send `distinctiveAssets` with an `uploadId` and a `description` per item. Use PNG, JPEG, WebP or GIF images of up to 8 MB each, uploaded to the same workspace. [File uploads](https://docs.myunite.ai/en/uploads.md)

An update fills gaps and preserves saved values. Repeating the same colors or taglines does not duplicate them. If you supply a different logo when the brand already has one, the response keeps the current logo and lists the disagreement in `conflicts`. Other compatible additions may have been saved in the same call. Review conflicts in the editor at `brand.url`.

## Use the brand in the next pre-test

The response includes the saved `brand`, guideline availability in `readiness`, available checks in `enabledChecks` and checks enabled by this write in `newlyEnabledChecks`. Pass `brand.id` as `brandId` when creating the next pre-test. Saving guidelines uses no analysis quota.

`POST` returns `201` on creation and `200` on replay. To retry with an explicit key, keep the same body and `Idempotency-Key` (tool argument `idempotencyKey`). Without an explicit key, identical calls using the same credential also replay the creation. `PATCH` returns `200`. [Error codes](https://docs.myunite.ai/en/errors.md)


## Related topics

- [Get the catalog of channels, formats and brands](https://docs.myunite.ai/api-reference/catalog/get-the-catalog-of-channels-formats-and-brands.md)
- [Errors](https://docs.myunite.ai/en/errors.md)
- [Results](https://docs.myunite.ai/en/results.md)
- [MCP for AI agents](https://docs.myunite.ai/en/mcp-server.md)
- [OOH pre-test](https://docs.myunite.ai/en/pretests/ooh.md)


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