---
title: "Create a brand report"
method: POST
path: "/v1/reports/brand"
tags: ["Brand Reports"]
---

# Create a brand report

`POST /v1/reports/brand`

## Request

- Base URL: `https://data.otterly.ai`
- URL: `https://data.otterly.ai/v1/reports/brand`
- Auth: HTTP bearer

Creates a brand report in a workspace, the same as creating it in the UI. The prompts must already exist in that workspace — create them with `POST /v1/workspaces/{id}/prompts` — and the report tracks their countries. Domains are normalized (protocol, `www.` and path stripped). Detect the brand either by `brand` and `brandVariations`, or by `brandRegex` together with `reportTitle`. Competitors can come straight from `POST /v1/competitors/suggestions`. Data for the report is collected asynchronously. Sending the same request again within 2 minutes returns the report the first request created instead of a second one; if that report is still being set up, the response is a 409 carrying its ID.

## Request body

- PublicApiCreateBrandReportRequest
  - `workspaceId` string, required: Workspace to create the report in. The API key must have access to it.
  - `reportTitle` string: Optional. Report name shown in the app. Defaults to `brand`. Required when `brandRegex` is set.
  - `brand` string: Brand name to track. Required unless `brandRegex` is set, in which case `reportTitle` is used as the brand label.
  - `brandVariations` string[]: Optional. Other names the brand goes by, at most 100. Cannot be combined with `brandRegex`.
  - `brandDomain` string, required: Brand website domain, e.g. `acme.com`. Protocol, `www.` and path are stripped.
  - `brandDomainVariations` string[]: Optional. Other domains the brand owns, at most 100. Each must differ from `brandDomain`.
  - `brandDomainWildcard` boolean: Optional. When true, subdomains of `brandDomain` also count as the brand domain.
  - `brandRegex` string, nullable: Optional. Regular expression used to detect the brand in AI answers, instead of the name and its variations (so it cannot be combined with `brandVariations`). Up to 1000 characters. Send `null` to clear it.
  - `promptIds` string[], required: IDs of prompts that already exist in the report workspace — look them up with `GET /v1/workspaces/{id}/prompts`. The report tracks the countries of these prompts.
  - `competitors` PublicApiBrandCompetitorInput[]: Optional. Competitors to track, at most 100. Each competitor domain must be unique. `POST /v1/competitors/suggestions` returns items in this shape.
    - `brand` string, required: Competitor brand name.
    - `brandVariations` string[]
    - `brandDomain` string, required
    - `brandDomainVariations` string[]
    - `brandDomainWildcard` boolean
    - `brandRegex` string, nullable: Optional. Regular expression used to detect the brand in AI answers, instead of the name and its variations (so it cannot be combined with `brandVariations`). Up to 1000 characters. Send `null` to clear it.

## Response `201`

The created brand report.

- PublicApiBrandReport
  - `id` string, required
  - `workspaceId` string, required
  - `brand` string, required
  - `reportTitle` string
  - `brandVariations` string[]
  - `brandDomain` string, required
  - `brandDomainVariations` string[]
  - `brandDomainWildcard` boolean
  - `brandRegex` string, nullable, required: Regular expression used to detect the brand in AI answers, instead of `brand` and `brandVariations`. `null` when not set.
  - `countries` string[], required: Lowercase ISO 3166-1 alpha-2 country codes the report tracks (e.g. `us`, `de`), with `uk` used in place of `gb`.
  - `createdDate` string, required
  - `updatedDate` string, required
  - `promptIds` string[]
  - `countryPromptsTotal` object: Total prompt count keyed by country code (lowercase ISO 3166-1 alpha-2; `uk` instead of `gb`).
  - `competitors` PublicApiBrandCompetitor[]
    - `brand` string, required: Competitor brand name.
    - `brandVariations` string[], required
    - `brandDomain` string, required
    - `brandDomainVariations` string[], required
    - `brandDomainWildcard` boolean, required
    - `brandRegex` string, nullable, required: Regular expression used to detect the brand in AI answers, instead of `brand` and `brandVariations`. `null` when not set.
  - `tags` PublicApiBrandReportTag[]
    - `id` string, required
    - `name` string, required
    - `color` string, required: Tag color (Ant Design preset color name, e.g. 'gold', 'orange', 'magenta', 'green', 'blue').

## Other responses

- `400`: Validation failed.
- `401`: Unauthorized.
- `403`: Forbidden.
- `409`: An identical create is still in progress. Retry `GET /v1/reports/brand/{reportId}` with the ID in the message.
- `429`: Quota exhausted.

## Changes

- **2026-11-03** `b5dc4bea6d45`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/otterly/apis/otterly-public-api/changes/v1/reports/brand/post.md)

---

[API](https://skmtc.dev/otterly/apis/otterly-public-api.md) - [All operations](https://skmtc.dev/otterly/apis/otterly-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/otterly/apis/otterly-public-api/revisions/333e3100f0b4?raw)