Create a brand

Creates a brand in the active project. Typically, Pineprompt discovers brands from AI responses on its own, so you should reach for this endpoint when you want to track a brand before it has appeared in a response. Segment membership is what makes a brand a competitor, so a brand created with segment_ids starts out tracked and one created without them starts out discovered. If you would like to designate a brand as the project's own brand, you may point the project's brand_id at it via the update-project endpoint.

POST /api/v1/brands

Pineprompt attributes a mention to a brand by comparing the brand's aliases against the names an AI response uses, case-insensitively, and attributes a citation by comparing the brand's domains against the URLs the response links. A brand without aliases or domains will therefore never accrue mentions, so when you omit aliases, Pineprompt seeds the brand with its lowercased display name.

Matching applies to responses captured after the brand exists; Pineprompt does not re-attribute historical mentions or citations. Of course, brands that AI responses already mention are surfaced by discovery on their own, so you should reach for this endpoint when you want to track a brand ahead of its first appearance.

A brand's kind is derived from its context rather than set on the request. Segment membership is what makes a brand a competitor, so a brand created with segment_ids starts out tracked, and one created without them starts out discovered, from which you may attach it later with the segment attachment endpoints or ignore it via the update endpoint. If you would like to designate the brand as the project's own brand, you should point the project's brand_id at it via the update-project endpoint.

Body parameters

Name	Type	Required	Description
display_name	string	Required	The name the brand is shown under. Display names are unique per project and case-insensitive, and a display name may not collide with an alias of another brand, since both would compete for the same mentions.
aliases	string[]	Optional	The names Pineprompt matches against when it attributes a mention to the brand. Aliases are stored as you send them and compared while ignoring casing and punctuation. When omitted, the brand is seeded with its display name.
domains	string[]	Optional	The domains Pineprompt matches against when it attributes a citation to the brand. You may pass full URLs; each entry is reduced to a bare lowercase host before it is stored.
segment_ids	integer[]	Optional	The ids of the project segments the brand should join. Segment membership is what makes a brand a competitor, so a brand created with segments starts out tracked and one created without them starts out `discovered`. Each id must name a segment of the project.

Response

The brand object

Field	Type	Description
id	integer	The unique ID of the brand.
project_id	integer	The ID of the project the brand belongs to.
display_name	string	The canonical display name of the brand.
aliases	string[]	Alternative names that the brand is referred to by.
domains	string[]	The web domains associated with the brand.
kind	string	The brand's classification, derived from its context rather than stored: the brand the project's `brand_id` points at is `own`, a brand with `ignored_at` set is `ignored`, a brand attached to any segment is a `competitor`, and a brand with none of those is `discovered`. This field is read-only.
color	string	A hex color used to color the brand consistently across charts. It is derived from the brand's favicon, or assigned automatically when no color can be derived. This field is read-only and is always present.
ignored_at	datetime	When the brand was ignored, or null while it is not. Set and cleared through the `ignored` field on the update endpoint.
created_at	datetime	When the brand was created.
updated_at	datetime	When the brand was last updated.