Brands

Update a brand

Updates a brand's display name, aliases, domains, or ignored state. Every field is optional, so you may send only the fields you would like to change; a field that is omitted keeps its current value. A brand's kind is derived from its context and cannot be written directly: pass ignored to move the brand in or out of the ignored state, attach it to a segment to make it a competitor, or point the project's brand_id at it to make it the own brand. An ignored brand cannot sit in a segment, so ignoring one detaches it everywhere; ignoring the own brand returns a 422.

PATCH /api/v1/brands/{brand}

A brand's kind is derived from its context rather than stored, so it is not writable here. The brand a project's brand_id points at is the own brand, a brand attached to any segment is a competitor, a brand with ignored_at set is ignored, and a brand with none of those is discovered.

The ignored field moves a brand in and out of the ignored state. An ignored brand cannot sit in a segment, so ignoring a competitor detaches it from every segment at the same time, and attaching an ignored brand to a segment clears the mark again. Ignoring the own brand fails with a 422; you should designate a different own brand through the update-project endpoint first.

The aliases and domains you send replace the brand's current lists in full, so a client that edits one entry should send the whole list back. Changing them affects how responses captured from that point on are attributed; Pineprompt does not re-attribute historical mentions or citations.

Path parameters

Name Type Required Description
brand integer Required

The numeric ID of the brand.

Body parameters

Name Type Required Description
display_name string Optional

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. The list you send replaces the current one.
domains string[] Optional

The domains Pineprompt matches against when it attributes a citation to the brand. The list you send replaces the current one. You may pass full URLs; each entry is reduced to a bare lowercase host before it is stored.
ignored boolean Optional

Pass true to ignore the brand. An ignored brand cannot sit in a segment, so it is detached from every segment as the mark is set; ignoring the own brand returns a 422. Pass false to clear the mark and return the brand to the discovered pool.

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.