API Reference

Segments

Segments group brands into named cohorts, such as Direct Competitors or Enterprise Competitors. A single brand may belong to multiple segments, and you may use segments to filter the dashboard. Every new project is seeded with a Direct Competitors segment, and a project must always have at least one segment. Only brands classified as own or competitor belong to segments; attaching a discovered or ignored brand promotes it to competitor, and detaching a competitor from its only segment reclassifies it to ignored.

Endpoints

GET /api/v1/segments

List segments
Returns every segment belonging to the active project. The response is paginated. Every new project is seeded with a Direct Competitors segment.
POST /api/v1/segments

Create a segment
Creates a new segment in the active project. Segment names are unique per project and case-insensitive.
GET /api/v1/segments/{segment}

Get a segment
Returns a single segment. The segment must belong to the active project.
DELETE /api/v1/segments/{segment}

Delete a segment
Deletes a segment. Every brand-segment attachment is removed at the same time; the brands themselves are left untouched, although a brand whose only segment this was derives back to discovered. A project must keep at least one segment, so attempting to delete the last one will return 422.
PATCH /api/v1/segments/{segment}

Update a segment
Renames a segment.
POST /api/v1/brands/{brand}/segments/{segment}

Attach a brand to a segment
Attaches the given brand to the segment. The endpoint is idempotent. Both the brand and the segment must belong to the active project. Segment membership is what makes a brand a competitor, so attaching a discovered brand starts tracking it, and attaching an ignored brand revives it and clears its ignored mark. The own brand is implicit in every segment, so attaching it changes nothing.
DELETE /api/v1/brands/{brand}/segments/{segment}

Detach a brand from a segment
Removes the brand from the segment. The endpoint is idempotent. Both the brand and the segment must belong to the active project. Detaching a competitor from its only segment stops tracking it: the brand derives back to discovered and returns to the discover pool with its mention history intact. The own brand is implicit in every segment, so detaching it returns 422.