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 may be attached to a segment.

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.
PUT /api/v1/segments/{segment}

Update a segment
Renames a segment. Since this endpoint uses PUT semantics, name is required on the request body.
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. A project must keep at least one segment, so attempting to delete the last one will return 422.
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, and the brand must be classified as own or competitor.
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.