---
title: "Create a group"
method: POST
path: "/v1/groups"
tags: ["Groups"]
---

# Create a group

`POST /v1/groups`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/groups`
- Auth: HTTP bearer

Create a keyword group. `name` is unique per workspace; `externalId` (optional, unique too) is your own id for it, a customer id say, so you can find it again without storing ours; `context` (optional) is the group's own company description, which the classifier reads in place of the whole workspace profile for the group's keywords. Then pass the group id as `groupId` when creating a keyword.

## Request body

- object
  - `name` string, required: The group's name: a customer, a campaign, a product. Unique per workspace.
  - `externalId` string, nullable: Your own id for the group (a customer id, say). Unique per workspace; find the group by it with GET /v1/groups?externalId=.
  - `context` string, nullable: What the classifier reads as "the company" for this group's keywords, in place of the WHOLE workspace profile, its relevance guidelines and competitor list included (at most 4000 characters): who the business is, what it sells, for whom, what is not it, and any rule that should apply to this group ("ignore job posts"). For a group per customer, the customer's description. Null: the workspace profile, as for every keyword before groups.

## Response `201`

The new group

- Group: The group the keyword belongs to.
  - `id` string, required: Group id (grp_...).
  - `name` string, required: The group's name.
  - `externalId` string, nullable, required: Your own id for the group, or null.
  - `isDefault` boolean, required: The workspace's default group, where a keyword lands when no group is named.
  - `context` string, nullable, required: The group's own company description for the classifier, or null for the workspace profile.
  - `stats` object, required: Computed over the group's keywords.
    - `keywords` integer, required: Keywords in the group, muted ones included.
    - `active` integer, required: Keywords in the group that are tracking (not muted).
  - `createdAt` string, required: ISO 8601 timestamp, UTC.
  - `updatedAt` string, required: ISO 8601 timestamp, UTC.

## Other responses

- `401`: Missing or invalid API key
- `409`: A group with that name or externalId already exists (duplicate_group)

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)