> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/tools/brands.md).

# Brands

Set up and edit the brand Ava writes for, and its media.

### brand\_list

List the account's brands (id, name, url, primary flag). Use it to pick a brand\_id for research and drafting; call brand\_get for full details.

* **Permission:** Read brands (`brands:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_list`

#### Input

No input: send `{}`.

#### Output

| Field                       | Type             | Description                               |
| --------------------------- | ---------------- | ----------------------------------------- |
| `brands`                    | array of objects |                                           |
| `brands[].brand_id`         | string           |                                           |
| `brands[].name`             | string           |                                           |
| `brands[].url`              | string           |                                           |
| `brands[].product_category` | string           |                                           |
| `brands[].is_primary`       | boolean          |                                           |
| `brands[].updated_at`       | string           | ISO-8601 timestamp                        |
| `next_steps`                | array of strings | Short hints naming the next tool to call. |

### brand\_get

Read a brand profile; pass sections to fetch only part of it (identity, audience, products, sources, visual, market). Use before drafting to check claims and audience (fix gaps with brand\_update), and before producing to check the visual section's media\_readiness: below good, videos get no B-roll and AI-generated product shots, so ask the user for real media (brand\_media\_upload\_url, brand\_media\_add) or make clips with broll\_create.

* **Permission:** Read brands (`brands:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_get`

#### Input

| Field      | Type             | Required | Description                                                                                               |
| ---------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `brand_id` | string           | Yes      | Brand id from brand\_list or whoami.                                                                      |
| `sections` | array of strings |          | Omit for the full profile. Each one of `identity`, `audience`, `products`, `sources`, `visual`, `market`. |

#### Output

| Field                                      | Type             | Description                                                                                                                                                                                                                                              |
| ------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`                                 | string           |                                                                                                                                                                                                                                                          |
| `name`                                     | string           |                                                                                                                                                                                                                                                          |
| `is_primary`                               | boolean          | True when this is the account's default brand.                                                                                                                                                                                                           |
| `name_pronunciation`                       | string           |                                                                                                                                                                                                                                                          |
| `url`                                      | string           |                                                                                                                                                                                                                                                          |
| `product_category`                         | string           |                                                                                                                                                                                                                                                          |
| `industry`                                 | string           |                                                                                                                                                                                                                                                          |
| `brief`                                    | string           | Research summary of the brand, its offer and positioning.                                                                                                                                                                                                |
| `differentiator`                           | string           |                                                                                                                                                                                                                                                          |
| `target_audience`                          | string           |                                                                                                                                                                                                                                                          |
| `tone`                                     | array of strings |                                                                                                                                                                                                                                                          |
| `competitors`                              | array of strings |                                                                                                                                                                                                                                                          |
| `customer_insights`                        | array of objects |                                                                                                                                                                                                                                                          |
| `customer_insights[].id`                   | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].kind`                 | string           | One of `need`, `objection`, `desired_outcome`, `switching_trigger`, `customer_language`.                                                                                                                                                                 |
| `customer_insights[].summary`              | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].creative_use`         | string           | How a hook or script should use this finding.                                                                                                                                                                                                            |
| `customer_insights[].footage_suggestion`   | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].status`               | string           | One of `active`, `excluded`.                                                                                                                                                                                                                             |
| `customer_insights[].evidence`             | array of objects |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].source_id` | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].url`       | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].quote`     | string           |                                                                                                                                                                                                                                                          |
| `products`                                 | array of objects |                                                                                                                                                                                                                                                          |
| `products[].name`                          | string           |                                                                                                                                                                                                                                                          |
| `products[].description`                   | string           |                                                                                                                                                                                                                                                          |
| `claims`                                   | array of objects |                                                                                                                                                                                                                                                          |
| `claims[].id`                              | string           |                                                                                                                                                                                                                                                          |
| `claims[].text`                            | string           | Verbatim first-party claim copy.                                                                                                                                                                                                                         |
| `claims[].product_name`                    | string           |                                                                                                                                                                                                                                                          |
| `claims[].status`                          | string           | Only approved claims are used in drafted ad copy. One of `suggested`, `approved`, `rejected`.                                                                                                                                                            |
| `claims[].evidence`                        | object           |                                                                                                                                                                                                                                                          |
| `claims[].evidence.url`                    | string           |                                                                                                                                                                                                                                                          |
| `claims[].evidence.quote`                  | string           |                                                                                                                                                                                                                                                          |
| `sources`                                  | array of objects |                                                                                                                                                                                                                                                          |
| `sources[].id`                             | string           |                                                                                                                                                                                                                                                          |
| `sources[].url`                            | string           |                                                                                                                                                                                                                                                          |
| `sources[].title`                          | string           |                                                                                                                                                                                                                                                          |
| `sources[].category`                       | string           | One of `website`, `app_store`, `reviews`, `discussion`, `social`, `web`.                                                                                                                                                                                 |
| `sources[].excerpt`                        | string           |                                                                                                                                                                                                                                                          |
| `sources[].collected_at`                   | string           |                                                                                                                                                                                                                                                          |
| `sources[].published_at`                   | string           |                                                                                                                                                                                                                                                          |
| `media`                                    | array of objects |                                                                                                                                                                                                                                                          |
| `media[].media_id`                         | string           | Stable id of this item (derived from its url); pass to brand\_media\_update, brand\_media\_remove, broll\_create or campaign\_update.featured\_media\_ids.                                                                                               |
| `media[].url`                              | string           |                                                                                                                                                                                                                                                          |
| `media[].name`                             | string           |                                                                                                                                                                                                                                                          |
| `media[].type`                             | string           | Explicit file type when set; kind is the resolved one. One of `image`, `video`.                                                                                                                                                                          |
| `media[].kind`                             | string           | video = B-roll Ava can cut in; image = product or scene visual; logo = brand mark or icon (never placed as B-roll or a product shot). One of `video`, `image`, `logo`.                                                                                   |
| `media[].label`                            | string           | Semantic media category: broll, product, lifestyle, screenshot, logo, ...                                                                                                                                                                                |
| `media[].description`                      | string           | Owner guidance on when/how to use the asset.                                                                                                                                                                                                             |
| `media[].analysis`                         | string           | Machine description of what is visible.                                                                                                                                                                                                                  |
| `media[].analyzed`                         | boolean          | True once Ava has analyzed it. Productions use only analyzed media; brand\_media\_add analyzes what it imports.                                                                                                                                          |
| `media_readiness`                          | object           | Whether the brand has the media good videos need (visual section). Below good, ask the user for real product videos and photos before producing.                                                                                                         |
| `media_readiness.level`                    | string           | good = 3+ analyzed videos and 3+ analyzed product, lifestyle, screenshot or hero images; none = no analyzed media besides logos; thin = anything between. Below good, videos get no B-roll or AI-generated product shots. One of `none`, `thin`, `good`. |
| `media_readiness.videos_analyzed`          | integer          | Analyzed B-roll videos Ava can place. Value at least 0.                                                                                                                                                                                                  |
| `media_readiness.product_images_analyzed`  | integer          | Analyzed product, lifestyle, screenshot and hero images (not logos, icons, team, partner or social). Value at least 0.                                                                                                                                   |
| `media_readiness.logos`                    | integer          | Value at least 0.                                                                                                                                                                                                                                        |
| `media_readiness.unanalyzed`               | integer          | Items not analyzed yet; productions skip them. Value at least 0.                                                                                                                                                                                         |
| `media_readiness.message`                  | string           | One line for the user, as Studio words it, e.g. that Ava will not place B-roll.                                                                                                                                                                          |
| `media_readiness.next_steps`               | array of strings | What would raise the level, for only what is short: product photos or B-roll clips to add (brand\_media\_upload\_url, brand\_media\_add, with the label to set), and broll\_create only when analyzed B-roll is short; empty when good.                  |
| `colors`                                   | array of objects |                                                                                                                                                                                                                                                          |
| `colors[].hex`                             | string           |                                                                                                                                                                                                                                                          |
| `colors[].name`                            | string           |                                                                                                                                                                                                                                                          |
| `market`                                   | object           |                                                                                                                                                                                                                                                          |
| `market.country`                           | string           |                                                                                                                                                                                                                                                          |
| `market.region`                            | string           |                                                                                                                                                                                                                                                          |
| `market.market`                            | string           |                                                                                                                                                                                                                                                          |
| `market.language`                          | string           |                                                                                                                                                                                                                                                          |
| `market.locale`                            | string           |                                                                                                                                                                                                                                                          |
| `market.locales`                           | array of strings |                                                                                                                                                                                                                                                          |
| `platforms`                                | array of strings |                                                                                                                                                                                                                                                          |
| `social_accounts`                          | array of objects |                                                                                                                                                                                                                                                          |
| `social_accounts[].platform`               | string           | One of `instagram`, `tiktok`.                                                                                                                                                                                                                            |
| `social_accounts[].handle`                 | string           |                                                                                                                                                                                                                                                          |
| `preview_hooks`                            | array of objects |                                                                                                                                                                                                                                                          |
| `preview_hooks[].type`                     | string           |                                                                                                                                                                                                                                                          |
| `preview_hooks[].text`                     | string           |                                                                                                                                                                                                                                                          |
| `preferred_actor_ids`                      | array of strings |                                                                                                                                                                                                                                                          |
| `revision`                                 | number           | Server profile revision; increments on each save.                                                                                                                                                                                                        |
| `created_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                       |
| `updated_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                       |
| `next_steps`                               | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                |

### brand\_export

Export a brand profile as a portable brand.md (format md) or raw JSON (format json). Use it to save brand context into a repo or hand it to another tool.

* **Permission:** Read brands (`brands:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_export`

#### Input

| Field      | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `brand_id` | string | Yes      | Brand id from brand\_list or whoami. |
| `format`   | string | Yes      | One of `md`, `json`.                 |

#### Output

| Field        | Type             | Description                               |
| ------------ | ---------------- | ----------------------------------------- |
| `format`     | string           | One of `md`, `json`.                      |
| `content`    | string           |                                           |
| `next_steps` | array of strings | Short hints naming the next tool to call. |

### brand\_create

Create and save a brand: pass profile with a name and supplied details for a free save without research (website optional inside profile), or url with optional hints for website research and media analysis (40 credits, eligible first-brand allowance applies). Returns a job\_id; poll jobs\_get until succeeded, then confirm the saved brand\_id and name. Talking about a brand or exporting it does not save changes; use brand\_update for later edits.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free for a supplied profile; 40 credits for website research
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/brand_create`

#### Input

| Field                                | Type             | Required | Description                                                                                                                                               |
| ------------------------------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                                | string           |          | Website to research, e.g. <https://example.com>; omit when passing profile. 1 to 2048 characters.                                                         |
| `profile`                            | object           |          | Save supplied brand details without research or a credit charge; name is required and profile.url is optional. Omit top-level url and hints in this mode. |
| `profile.name`                       | string           | Yes      | 1 to 120 characters.                                                                                                                                      |
| `profile.name_pronunciation`         | string           |          | At most 200 characters.                                                                                                                                   |
| `profile.url`                        | string           |          | At most 2048 characters.                                                                                                                                  |
| `profile.product_category`           | string           |          | At most 200 characters.                                                                                                                                   |
| `profile.industry`                   | string           |          | At most 200 characters.                                                                                                                                   |
| `profile.target_audience`            | string           |          | At most 2000 characters.                                                                                                                                  |
| `profile.tone`                       | array of strings |          | At most 20 items.                                                                                                                                         |
| `profile.competitors`                | array of strings |          | At most 50 items.                                                                                                                                         |
| `profile.differentiator`             | string           |          | At most 2000 characters.                                                                                                                                  |
| `profile.brief`                      | string           |          | At most 10000 characters.                                                                                                                                 |
| `profile.products`                   | array of objects |          | At most 50 items.                                                                                                                                         |
| `profile.products[].name`            | string           | Yes      |                                                                                                                                                           |
| `profile.products[].description`     | string           |          |                                                                                                                                                           |
| `profile.colors`                     | array of objects |          | At most 20 items.                                                                                                                                         |
| `profile.colors[].hex`               | string           | Yes      |                                                                                                                                                           |
| `profile.colors[].name`              | string           |          |                                                                                                                                                           |
| `profile.platforms`                  | array of strings |          | At most 20 items.                                                                                                                                         |
| `profile.market`                     | object           |          |                                                                                                                                                           |
| `profile.market.country`             | string           |          |                                                                                                                                                           |
| `profile.market.region`              | string           |          |                                                                                                                                                           |
| `profile.market.market`              | string           |          |                                                                                                                                                           |
| `profile.market.language`            | string           |          |                                                                                                                                                           |
| `profile.market.locale`              | string           |          |                                                                                                                                                           |
| `profile.market.locales`             | array of strings |          |                                                                                                                                                           |
| `profile.social_accounts`            | array of objects |          | At most 20 items.                                                                                                                                         |
| `profile.social_accounts[].platform` | string           | Yes      | One of `instagram`, `tiktok`.                                                                                                                             |
| `profile.social_accounts[].handle`   | string           | Yes      |                                                                                                                                                           |
| `profile.preferred_actor_ids`        | array of strings |          | At most 10 items.                                                                                                                                         |
| `hints`                              | string           |          | Optional context: product focus, audience, market. At most 2000 characters.                                                                               |
| `idempotency_key`                    | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                    |

### brand\_update

Edit a brand profile and get the updated Brand back. patch holds only the fields to change (arrays replace the whole list). Use claim\_status / insight\_status to approve or exclude existing claims and insights.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_update`

#### Input

| Field                              | Type             | Required | Description                                                                                                                            |
| ---------------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`                         | string           | Yes      | Brand id from brand\_list or whoami.                                                                                                   |
| `patch`                            | object           | Yes      |                                                                                                                                        |
| `patch.name`                       | string           |          | 1 to 120 characters.                                                                                                                   |
| `patch.name_pronunciation`         | string           |          | At most 200 characters.                                                                                                                |
| `patch.url`                        | string           |          | At most 2048 characters.                                                                                                               |
| `patch.product_category`           | string           |          | At most 200 characters.                                                                                                                |
| `patch.industry`                   | string           |          | At most 200 characters.                                                                                                                |
| `patch.target_audience`            | string           |          | At most 2000 characters.                                                                                                               |
| `patch.tone`                       | array of strings |          | At most 20 items.                                                                                                                      |
| `patch.competitors`                | array of strings |          | At most 50 items.                                                                                                                      |
| `patch.differentiator`             | string           |          | At most 2000 characters.                                                                                                               |
| `patch.brief`                      | string           |          | At most 10000 characters.                                                                                                              |
| `patch.products`                   | array of objects |          | At most 50 items.                                                                                                                      |
| `patch.products[].name`            | string           | Yes      |                                                                                                                                        |
| `patch.products[].description`     | string           |          |                                                                                                                                        |
| `patch.colors`                     | array of objects |          | At most 20 items.                                                                                                                      |
| `patch.colors[].hex`               | string           | Yes      |                                                                                                                                        |
| `patch.colors[].name`              | string           |          |                                                                                                                                        |
| `patch.platforms`                  | array of strings |          | At most 20 items.                                                                                                                      |
| `patch.market`                     | object           |          |                                                                                                                                        |
| `patch.market.country`             | string           |          |                                                                                                                                        |
| `patch.market.region`              | string           |          |                                                                                                                                        |
| `patch.market.market`              | string           |          |                                                                                                                                        |
| `patch.market.language`            | string           |          |                                                                                                                                        |
| `patch.market.locale`              | string           |          |                                                                                                                                        |
| `patch.market.locales`             | array of strings |          |                                                                                                                                        |
| `patch.social_accounts`            | array of objects |          | At most 20 items.                                                                                                                      |
| `patch.social_accounts[].platform` | string           | Yes      | One of `instagram`, `tiktok`.                                                                                                          |
| `patch.social_accounts[].handle`   | string           | Yes      |                                                                                                                                        |
| `patch.preferred_actor_ids`        | array of strings |          | At most 10 items.                                                                                                                      |
| `patch.claim_status`               | array of objects |          | Approve or reject existing claims by id. Claims text cannot be edited. At most 200 items.                                              |
| `patch.claim_status[].id`          | string           | Yes      |                                                                                                                                        |
| `patch.claim_status[].status`      | string           | Yes      | One of `approved`, `rejected`.                                                                                                         |
| `patch.insight_status`             | array of objects |          | Include or exclude existing customer insights by id. At most 200 items.                                                                |
| `patch.insight_status[].id`        | string           | Yes      |                                                                                                                                        |
| `patch.insight_status[].status`    | string           | Yes      | One of `active`, `excluded`.                                                                                                           |
| `expected_revision`                | integer          |          | Brand revision from brand\_get. When set and the brand has changed since, the update fails with invalid\_input instead of overwriting. |
| `idempotency_key`                  | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                 |

#### Output

| Field                                      | Type             | Description                                                                                                                                                                                                                                              |
| ------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`                                 | string           |                                                                                                                                                                                                                                                          |
| `name`                                     | string           |                                                                                                                                                                                                                                                          |
| `is_primary`                               | boolean          | True when this is the account's default brand.                                                                                                                                                                                                           |
| `name_pronunciation`                       | string           |                                                                                                                                                                                                                                                          |
| `url`                                      | string           |                                                                                                                                                                                                                                                          |
| `product_category`                         | string           |                                                                                                                                                                                                                                                          |
| `industry`                                 | string           |                                                                                                                                                                                                                                                          |
| `brief`                                    | string           | Research summary of the brand, its offer and positioning.                                                                                                                                                                                                |
| `differentiator`                           | string           |                                                                                                                                                                                                                                                          |
| `target_audience`                          | string           |                                                                                                                                                                                                                                                          |
| `tone`                                     | array of strings |                                                                                                                                                                                                                                                          |
| `competitors`                              | array of strings |                                                                                                                                                                                                                                                          |
| `customer_insights`                        | array of objects |                                                                                                                                                                                                                                                          |
| `customer_insights[].id`                   | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].kind`                 | string           | One of `need`, `objection`, `desired_outcome`, `switching_trigger`, `customer_language`.                                                                                                                                                                 |
| `customer_insights[].summary`              | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].creative_use`         | string           | How a hook or script should use this finding.                                                                                                                                                                                                            |
| `customer_insights[].footage_suggestion`   | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].status`               | string           | One of `active`, `excluded`.                                                                                                                                                                                                                             |
| `customer_insights[].evidence`             | array of objects |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].source_id` | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].url`       | string           |                                                                                                                                                                                                                                                          |
| `customer_insights[].evidence[].quote`     | string           |                                                                                                                                                                                                                                                          |
| `products`                                 | array of objects |                                                                                                                                                                                                                                                          |
| `products[].name`                          | string           |                                                                                                                                                                                                                                                          |
| `products[].description`                   | string           |                                                                                                                                                                                                                                                          |
| `claims`                                   | array of objects |                                                                                                                                                                                                                                                          |
| `claims[].id`                              | string           |                                                                                                                                                                                                                                                          |
| `claims[].text`                            | string           | Verbatim first-party claim copy.                                                                                                                                                                                                                         |
| `claims[].product_name`                    | string           |                                                                                                                                                                                                                                                          |
| `claims[].status`                          | string           | Only approved claims are used in drafted ad copy. One of `suggested`, `approved`, `rejected`.                                                                                                                                                            |
| `claims[].evidence`                        | object           |                                                                                                                                                                                                                                                          |
| `claims[].evidence.url`                    | string           |                                                                                                                                                                                                                                                          |
| `claims[].evidence.quote`                  | string           |                                                                                                                                                                                                                                                          |
| `sources`                                  | array of objects |                                                                                                                                                                                                                                                          |
| `sources[].id`                             | string           |                                                                                                                                                                                                                                                          |
| `sources[].url`                            | string           |                                                                                                                                                                                                                                                          |
| `sources[].title`                          | string           |                                                                                                                                                                                                                                                          |
| `sources[].category`                       | string           | One of `website`, `app_store`, `reviews`, `discussion`, `social`, `web`.                                                                                                                                                                                 |
| `sources[].excerpt`                        | string           |                                                                                                                                                                                                                                                          |
| `sources[].collected_at`                   | string           |                                                                                                                                                                                                                                                          |
| `sources[].published_at`                   | string           |                                                                                                                                                                                                                                                          |
| `media`                                    | array of objects |                                                                                                                                                                                                                                                          |
| `media[].media_id`                         | string           | Stable id of this item (derived from its url); pass to brand\_media\_update, brand\_media\_remove, broll\_create or campaign\_update.featured\_media\_ids.                                                                                               |
| `media[].url`                              | string           |                                                                                                                                                                                                                                                          |
| `media[].name`                             | string           |                                                                                                                                                                                                                                                          |
| `media[].type`                             | string           | Explicit file type when set; kind is the resolved one. One of `image`, `video`.                                                                                                                                                                          |
| `media[].kind`                             | string           | video = B-roll Ava can cut in; image = product or scene visual; logo = brand mark or icon (never placed as B-roll or a product shot). One of `video`, `image`, `logo`.                                                                                   |
| `media[].label`                            | string           | Semantic media category: broll, product, lifestyle, screenshot, logo, ...                                                                                                                                                                                |
| `media[].description`                      | string           | Owner guidance on when/how to use the asset.                                                                                                                                                                                                             |
| `media[].analysis`                         | string           | Machine description of what is visible.                                                                                                                                                                                                                  |
| `media[].analyzed`                         | boolean          | True once Ava has analyzed it. Productions use only analyzed media; brand\_media\_add analyzes what it imports.                                                                                                                                          |
| `media_readiness`                          | object           | Whether the brand has the media good videos need (visual section). Below good, ask the user for real product videos and photos before producing.                                                                                                         |
| `media_readiness.level`                    | string           | good = 3+ analyzed videos and 3+ analyzed product, lifestyle, screenshot or hero images; none = no analyzed media besides logos; thin = anything between. Below good, videos get no B-roll or AI-generated product shots. One of `none`, `thin`, `good`. |
| `media_readiness.videos_analyzed`          | integer          | Analyzed B-roll videos Ava can place. Value at least 0.                                                                                                                                                                                                  |
| `media_readiness.product_images_analyzed`  | integer          | Analyzed product, lifestyle, screenshot and hero images (not logos, icons, team, partner or social). Value at least 0.                                                                                                                                   |
| `media_readiness.logos`                    | integer          | Value at least 0.                                                                                                                                                                                                                                        |
| `media_readiness.unanalyzed`               | integer          | Items not analyzed yet; productions skip them. Value at least 0.                                                                                                                                                                                         |
| `media_readiness.message`                  | string           | One line for the user, as Studio words it, e.g. that Ava will not place B-roll.                                                                                                                                                                          |
| `media_readiness.next_steps`               | array of strings | What would raise the level, for only what is short: product photos or B-roll clips to add (brand\_media\_upload\_url, brand\_media\_add, with the label to set), and broll\_create only when analyzed B-roll is short; empty when good.                  |
| `colors`                                   | array of objects |                                                                                                                                                                                                                                                          |
| `colors[].hex`                             | string           |                                                                                                                                                                                                                                                          |
| `colors[].name`                            | string           |                                                                                                                                                                                                                                                          |
| `market`                                   | object           |                                                                                                                                                                                                                                                          |
| `market.country`                           | string           |                                                                                                                                                                                                                                                          |
| `market.region`                            | string           |                                                                                                                                                                                                                                                          |
| `market.market`                            | string           |                                                                                                                                                                                                                                                          |
| `market.language`                          | string           |                                                                                                                                                                                                                                                          |
| `market.locale`                            | string           |                                                                                                                                                                                                                                                          |
| `market.locales`                           | array of strings |                                                                                                                                                                                                                                                          |
| `platforms`                                | array of strings |                                                                                                                                                                                                                                                          |
| `social_accounts`                          | array of objects |                                                                                                                                                                                                                                                          |
| `social_accounts[].platform`               | string           | One of `instagram`, `tiktok`.                                                                                                                                                                                                                            |
| `social_accounts[].handle`                 | string           |                                                                                                                                                                                                                                                          |
| `preview_hooks`                            | array of objects |                                                                                                                                                                                                                                                          |
| `preview_hooks[].type`                     | string           |                                                                                                                                                                                                                                                          |
| `preview_hooks[].text`                     | string           |                                                                                                                                                                                                                                                          |
| `preferred_actor_ids`                      | array of strings |                                                                                                                                                                                                                                                          |
| `revision`                                 | number           | Server profile revision; increments on each save.                                                                                                                                                                                                        |
| `created_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                       |
| `updated_at`                               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                       |
| `next_steps`                               | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                |

### brand\_media\_upload\_url

For clients that can PUT bytes, get a presigned link to upload one local image (JPEG, PNG or WebP, up to 10 MB) or video (MP4, MOV or WebM, up to 50 MB) for a brand: PUT the file bytes to upload\_url with exactly the returned headers before expires\_at (15 minutes). Then pass media\_url to brand\_media\_add to add and analyze it; public links need no upload, pass them to brand\_media\_add directly. Videos that are not H.264 (such as HEVC/H.265 from an iPhone) are converted to H.264 MP4 when added.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_media_upload_url`

#### Input

| Field          | Type    | Required | Description                                                                                                                                                                                                                      |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`     | string  | Yes      | Brand id from brand\_list or whoami.                                                                                                                                                                                             |
| `filename`     | string  | Yes      | The file's name, such as unboxing.mp4. 1 to 255 characters.                                                                                                                                                                      |
| `content_type` | string  | Yes      | The file's type: image/jpeg, image/png or image/webp (up to 10 MB); video/mp4, video/quicktime (.mov) or video/webm (up to 50 MB). One of `image/jpeg`, `image/png`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`. |
| `size_bytes`   | integer | Yes      | File size in bytes: images up to 10 MB (10485760), videos up to 50 MB (52428800). Value 1 to 52428800.                                                                                                                           |

#### Output

| Field        | Type             | Description                                                                      |
| ------------ | ---------------- | -------------------------------------------------------------------------------- |
| `upload_url` | string           | Presigned link: PUT the raw file bytes here. Never send your API key to it.      |
| `method`     | "PUT"            |                                                                                  |
| `headers`    | object           | Send exactly these headers with the PUT (Content-Type and any signed ones).      |
| `media_url`  | string           | Where the file lives once uploaded: pass it to brand\_media\_add as an item url. |
| `expires_at` | string           | The upload link stops working at this time (15 minutes after the call).          |
| `next_steps` | array of strings | Short hints naming the next tool to call.                                        |

### brand\_media\_add

Add 1-10 images or videos to a brand (https links, brand\_media\_upload\_url's media\_url or brand\_get urls; 30 max) and analyze each so Ava can use it; non-H.264 video, such as an iPhone's HEVC, is converted to an H.264 MP4 copy. Costs 2 credits per item imported and analyzed: failed lists items not added, analyzed false with analysis\_error marks items added but not analyzed (add again to retry), neither charged. Returns a job\_id; jobs\_get then has the items and media\_readiness.

* **Permission:** Edit brands (`brands:write`)
* **Price:** 2 credits per item
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/brand_media_add`

#### Input

| Field                 | Type             | Required | Description                                                                                                                                                                                                                                                                          |
| --------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `brand_id`            | string           | Yes      | Brand id from brand\_list or whoami.                                                                                                                                                                                                                                                 |
| `items`               | array of objects | Yes      | 1-10 files to add. The brand keeps at most 30 items: remove some with brand\_media\_remove first when it is full. 1 to 10 items.                                                                                                                                                     |
| `items[].url`         | string           | Yes      | Public https link to an image or video file, or media\_url from brand\_media\_upload\_url. At most 2048 characters.                                                                                                                                                                  |
| `items[].label`       | string           |          | What it shows (broll, product, lifestyle, screenshot, ...). Default: broll for a video, product for an image. Set lifestyle or screenshot when that fits better. One of `broll`, `product`, `lifestyle`, `screenshot`, `hero`, `team`, `social`, `partner`, `icon`, `logo`, `other`. |
| `items[].description` | string           |          | What it shows and when Ava should use it, in the owner's words (up to 1000 characters); wins over the machine analysis. At most 1000 characters.                                                                                                                                     |
| `idempotency_key`     | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                               |

### brand\_media\_update

Change one brand media item's label or description (when and how Ava should use it); a description set here wins over the machine analysis. Pass media\_id from brand\_get and label, description or both; returns the updated item and the brand's media\_readiness.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_media_update`

#### Input

| Field             | Type   | Required | Description                                                                                                                                                                                                                                                                                                      |
| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`        | string | Yes      | Brand id from brand\_list or whoami.                                                                                                                                                                                                                                                                             |
| `media_id`        | string | Yes      | Brand media id from brand\_get (visual section).                                                                                                                                                                                                                                                                 |
| `label`           | string |          | What the item shows: broll (a video clip to cut in), product (product photo), lifestyle (product in use), screenshot (app or site screen), hero, team, social, partner, icon, logo or other. One of `broll`, `product`, `lifestyle`, `screenshot`, `hero`, `team`, `social`, `partner`, `icon`, `logo`, `other`. |
| `description`     | string |          | What it shows and when Ava should use it (up to 1000 characters); an empty string clears it. At most 1000 characters.                                                                                                                                                                                            |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                           |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                                                                                              |
| ----------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`                                | string           |                                                                                                                                                                                                                                                          |
| `media_item`                              | object           |                                                                                                                                                                                                                                                          |
| `media_item.media_id`                     | string           | Stable id of this item (derived from its url); pass to brand\_media\_update, brand\_media\_remove, broll\_create or campaign\_update.featured\_media\_ids.                                                                                               |
| `media_item.url`                          | string           |                                                                                                                                                                                                                                                          |
| `media_item.name`                         | string           |                                                                                                                                                                                                                                                          |
| `media_item.type`                         | string           | Explicit file type when set; kind is the resolved one. One of `image`, `video`.                                                                                                                                                                          |
| `media_item.kind`                         | string           | video = B-roll Ava can cut in; image = product or scene visual; logo = brand mark or icon (never placed as B-roll or a product shot). One of `video`, `image`, `logo`.                                                                                   |
| `media_item.label`                        | string           | Semantic media category: broll, product, lifestyle, screenshot, logo, ...                                                                                                                                                                                |
| `media_item.description`                  | string           | Owner guidance on when/how to use the asset.                                                                                                                                                                                                             |
| `media_item.analysis`                     | string           | Machine description of what is visible.                                                                                                                                                                                                                  |
| `media_item.analyzed`                     | boolean          | True once Ava has analyzed it. Productions use only analyzed media; brand\_media\_add analyzes what it imports.                                                                                                                                          |
| `media_readiness`                         | object           |                                                                                                                                                                                                                                                          |
| `media_readiness.level`                   | string           | good = 3+ analyzed videos and 3+ analyzed product, lifestyle, screenshot or hero images; none = no analyzed media besides logos; thin = anything between. Below good, videos get no B-roll or AI-generated product shots. One of `none`, `thin`, `good`. |
| `media_readiness.videos_analyzed`         | integer          | Analyzed B-roll videos Ava can place. Value at least 0.                                                                                                                                                                                                  |
| `media_readiness.product_images_analyzed` | integer          | Analyzed product, lifestyle, screenshot and hero images (not logos, icons, team, partner or social). Value at least 0.                                                                                                                                   |
| `media_readiness.logos`                   | integer          | Value at least 0.                                                                                                                                                                                                                                        |
| `media_readiness.unanalyzed`              | integer          | Items not analyzed yet; productions skip them. Value at least 0.                                                                                                                                                                                         |
| `media_readiness.message`                 | string           | One line for the user, as Studio words it, e.g. that Ava will not place B-roll.                                                                                                                                                                          |
| `media_readiness.next_steps`              | array of strings | What would raise the level, for only what is short: product photos or B-roll clips to add (brand\_media\_upload\_url, brand\_media\_add, with the label to set), and broll\_create only when analyzed B-roll is short; empty when good.                  |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                |

### brand\_media\_remove

Remove 1-30 items from a brand's media by media\_id (from brand\_get), so Ava stops using them; the stored files are kept. Returns the ids removed, those not found and the brand's media\_readiness.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_media_remove`

#### Input

| Field             | Type             | Required | Description                                                                            |
| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `brand_id`        | string           | Yes      | Brand id from brand\_list or whoami.                                                   |
| `media_ids`       | array of strings | Yes      | 1-30 media ids from brand\_get. 1 to 30 items.                                         |
| `idempotency_key` | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field                                     | Type             | Description                                                                                                                                                                                                                                              |
| ----------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`                                | string           |                                                                                                                                                                                                                                                          |
| `removed`                                 | array of strings | Ids removed from the brand.                                                                                                                                                                                                                              |
| `not_found`                               | array of strings | Ids the brand does not hold (already removed, or a url that changed).                                                                                                                                                                                    |
| `media_readiness`                         | object           |                                                                                                                                                                                                                                                          |
| `media_readiness.level`                   | string           | good = 3+ analyzed videos and 3+ analyzed product, lifestyle, screenshot or hero images; none = no analyzed media besides logos; thin = anything between. Below good, videos get no B-roll or AI-generated product shots. One of `none`, `thin`, `good`. |
| `media_readiness.videos_analyzed`         | integer          | Analyzed B-roll videos Ava can place. Value at least 0.                                                                                                                                                                                                  |
| `media_readiness.product_images_analyzed` | integer          | Analyzed product, lifestyle, screenshot and hero images (not logos, icons, team, partner or social). Value at least 0.                                                                                                                                   |
| `media_readiness.logos`                   | integer          | Value at least 0.                                                                                                                                                                                                                                        |
| `media_readiness.unanalyzed`              | integer          | Items not analyzed yet; productions skip them. Value at least 0.                                                                                                                                                                                         |
| `media_readiness.message`                 | string           | One line for the user, as Studio words it, e.g. that Ava will not place B-roll.                                                                                                                                                                          |
| `media_readiness.next_steps`              | array of strings | What would raise the level, for only what is short: product photos or B-roll clips to add (brand\_media\_upload\_url, brand\_media\_add, with the label to set), and broll\_create only when analyzed B-roll is short; empty when good.                  |
| `next_steps`                              | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                |

### brand\_set\_primary

Make a brand the account's primary brand, the one Ava Studio opens by default and whoami marks is\_primary. Returns primary\_brand\_id and the previous primary brand.

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_set_primary`

#### Input

| Field             | Type   | Required | Description                                                                            |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `brand_id`        | string | Yes      | Brand id from brand\_list or whoami.                                                   |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field                       | Type             | Description                                                   |
| --------------------------- | ---------------- | ------------------------------------------------------------- |
| `primary_brand_id`          | string           |                                                               |
| `previous_primary_brand_id` | string or null   | The primary brand before this call; null when there was none. |
| `next_steps`                | array of strings | Short hints naming the next tool to call.                     |

### brand\_delete

Permanently delete a brand profile, as Studio's Delete brand does (its campaigns and projects stay); ask the user first and pass confirm true, since it cannot be undone. If it was the primary brand another brand becomes primary; returns deleted\_brand\_id and primary\_brand\_id (null when no brand is left).

* **Permission:** Edit brands (`brands:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/brand_delete`

#### Input

| Field             | Type   | Required | Description                                                                            |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `brand_id`        | string | Yes      | Brand id from brand\_list or whoami.                                                   |
| `confirm`         | true   | Yes      | Must be true: the user agreed to delete the brand, which cannot be undone.             |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field              | Type             | Description                                                                                                                             |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `deleted_brand_id` | string           |                                                                                                                                         |
| `primary_brand_id` | string or null   | The account's primary brand after the delete: unchanged, another brand when the deleted one was primary, or null when no brand is left. |
| `next_steps`       | array of strings | Short hints naming the next tool to call.                                                                                               |
