OverviewPlatformsAPI Reference

Create a group

posthttps://api.mentio.dev/v1/groups

Create a keyword group, then pass its id as groupId when creating keywords.

externalId is your own id for it; context is its company description, read instead of the workspace profile. See Groups.

Authentication

AuthorizationBearer <token>Required

An API key (mk_live_...) from the dashboard or an OAuth access token. See Authentication.

Header parameters

idempotency-keystringOptional

A unique value (a UUID) for this request. Retrying with the same key within 24 hours returns the first response instead of creating twice.

1 to 255 characters

Body

application/json
namestringRequired

The group's name: a customer, a campaign, a product. Unique per workspace.

1 to 80 characters
externalIdstringnullableOptional

Your own id for the group (a customer id, say). Unique per workspace; find the group by it with GET /v1/groups?externalId=.

1 to 128 characters
contextstringnullableOptional

What the classifier reads as "the company" for this group's keywords, instead of the WHOLE workspace profile (guidelines and competitors included). Null: the workspace profile. See Groups.

0 to 4000 characters

Response

201The new group
idstringRequired

Group id (grp_...).

namestringRequired

The group's name.

externalIdstringnullableRequired

Your own id for the group, or null.

isDefaultbooleanRequired

The workspace's default group, where a keyword lands when no group is named.

contextstringnullableRequired

The group's own company description for the classifier, or null for the workspace profile.

statsobjectRequired

Computed over the group's keywords.

+Show 2 properties
keywordsintegerRequired

Keywords in the group, muted ones included.

0 to ∞
activeintegerRequired

Keywords in the group that are tracking (not muted).

0 to ∞
createdAtstringRequired

ISO 8601 timestamp, UTC.

updatedAtstringRequired

ISO 8601 timestamp, UTC.

400Invalid request: a parameter or the body failed validation (validation_error)
+Show 1 property
errorobjectRequired

The error.

+Show 5 properties
codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 53 enum values
unauthorizedforbiddenread_only_keyvalidation_errornot_foundinvalid_cursorpayload_too_largeidempotency_key_in_useidempotency_key_reusedrate_limitedduplicate_keywordinvalid_queryquery_needs_one_termquery_not_supportedinsufficient_balancefunding_requiredkeyword_limit_reachedbilling_not_configuredorder_not_creditedschedule_requiredunknown_channelnot_a_digesthourly_email_unsupportedslack_not_connectedslack_not_configuredtelegram_not_configuredfeed_unreadablefeed_login_requiredfeed_login_expiredfeed_limit_reachedfeed_auth_not_configuredemail_not_configuredinvalid_assigneeclassification_pendinginvalid_memberalready_memberlast_ownerduplicate_segmentfilter_too_complexduplicate_viewduplicate_automationautomation_filter_unreadableautomation_limit_reachedduplicate_groupdefault_groupdefault_group_contextgroup_changedinvalid_signaturewebhook_not_configuredinvalid_tokenprotected_userupstream_unavailableinternal_error
messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

detailsobjectOptional

Machine-readable facts about this error, when the code has any: for a keyword query, reason, position (the character a syntax error was found at) or terms (one keyword each).

401Missing or invalid API key
+Show 1 property
errorobjectRequired

The error.

+Show 5 properties
codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 53 enum values
unauthorizedforbiddenread_only_keyvalidation_errornot_foundinvalid_cursorpayload_too_largeidempotency_key_in_useidempotency_key_reusedrate_limitedduplicate_keywordinvalid_queryquery_needs_one_termquery_not_supportedinsufficient_balancefunding_requiredkeyword_limit_reachedbilling_not_configuredorder_not_creditedschedule_requiredunknown_channelnot_a_digesthourly_email_unsupportedslack_not_connectedslack_not_configuredtelegram_not_configuredfeed_unreadablefeed_login_requiredfeed_login_expiredfeed_limit_reachedfeed_auth_not_configuredemail_not_configuredinvalid_assigneeclassification_pendinginvalid_memberalready_memberlast_ownerduplicate_segmentfilter_too_complexduplicate_viewduplicate_automationautomation_filter_unreadableautomation_limit_reachedduplicate_groupdefault_groupdefault_group_contextgroup_changedinvalid_signaturewebhook_not_configuredinvalid_tokenprotected_userupstream_unavailableinternal_error
messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

detailsobjectOptional

Machine-readable facts about this error, when the code has any: for a keyword query, reason, position (the character a syntax error was found at) or terms (one keyword each).

409A group with that name or externalId already exists (duplicate_group)
+Show 1 property
errorobjectRequired

The error.

+Show 5 properties
codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 53 enum values
unauthorizedforbiddenread_only_keyvalidation_errornot_foundinvalid_cursorpayload_too_largeidempotency_key_in_useidempotency_key_reusedrate_limitedduplicate_keywordinvalid_queryquery_needs_one_termquery_not_supportedinsufficient_balancefunding_requiredkeyword_limit_reachedbilling_not_configuredorder_not_creditedschedule_requiredunknown_channelnot_a_digesthourly_email_unsupportedslack_not_connectedslack_not_configuredtelegram_not_configuredfeed_unreadablefeed_login_requiredfeed_login_expiredfeed_limit_reachedfeed_auth_not_configuredemail_not_configuredinvalid_assigneeclassification_pendinginvalid_memberalready_memberlast_ownerduplicate_segmentfilter_too_complexduplicate_viewduplicate_automationautomation_filter_unreadableautomation_limit_reachedduplicate_groupdefault_groupdefault_group_contextgroup_changedinvalid_signaturewebhook_not_configuredinvalid_tokenprotected_userupstream_unavailableinternal_error
messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

detailsobjectOptional

Machine-readable facts about this error, when the code has any: for a keyword query, reason, position (the character a syntax error was found at) or terms (one keyword each).