mentio-dev Groups API

openapi: 3.2.0
info:
  title: Mentio Dev Groups API
  version: 0.0.1
  description: 'Operations tagged Groups across 4 of this provider''s published API definitions: api_mentio.json, mentio-dev-api-openapi.json, mentio-dev-app-openapi.json, mentio-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mentio.dev
tags:
- name: Groups
paths:
  /v1/groups:
    get:
      operationId: listGroups
      summary: List groups
      description: 'The keyword groups of the workspace, the default group first, then oldest first. A group is how keywords are grouped (a customer, a campaign, a product): a term may be tracked once per group, every keyword belongs to one, and GET /v1/usage/breakdown?by=group says what each group cost. Pass `externalId` to find the group carrying your own id.'
      tags:
      - Groups
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          maxLength: 128
          description: Only the group carrying exactly this externalId.
        required: false
        description: Only the group carrying exactly this externalId.
        name: externalId
        in: query
      responses:
        '200':
          description: The groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/GroupRef'
                      - type: object
                        properties:
                          context:
                            type:
                            - string
                            - 'null'
                            description: The group's own company description for the classifier, or null for the workspace profile.
                          stats:
                            type: object
                            properties:
                              keywords:
                                type: integer
                                minimum: 0
                                description: Keywords in the group, muted ones included.
                              active:
                                type: integer
                                minimum: 0
                                description: Keywords in the group that are tracking (not muted).
                            required:
                            - keywords
                            - active
                            description: Computed over the group's keywords.
                          createdAt:
                            type: string
                            description: ISO 8601 timestamp, UTC.
                          updatedAt:
                            type: string
                            description: ISO 8601 timestamp, UTC.
                        required:
                        - context
                        - stats
                        - createdAt
                        - updatedAt
                      description: The group the keyword belongs to.
                    description: The workspace's groups, the default first, then oldest first.
                required:
                - data
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createGroup
      summary: Create a group
      description: 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.
      tags:
      - Groups
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: 'The group''s name: a customer, a campaign, a product. Unique per workspace.'
                externalId:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  maxLength: 128
                  description: Your own id for the group (a customer id, say). Unique per workspace; find the group by it with GET /v1/groups?externalId=.
                context:
                  type:
                  - string
                  - 'null'
                  maxLength: 4000
                  description: '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.'
              required:
              - name
      responses:
        '201':
          description: The new group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A group with that name or externalId already exists (duplicate_group)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.mentio.dev
  /v1/groups/{id}:
    get:
      operationId: getGroup
      summary: Get a group
      tags:
      - Groups
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Group id (grp_...).
          example: grp_abc123
        required: true
        description: Group id (grp_...).
        name: id
        in: path
      responses:
        '200':
          description: The group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such group in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: updateGroup
      summary: Update a group
      description: 'Rename a group, change your id for it (`externalId`, null clears) or its company description (`context`, null clears: the workspace profile applies again; new mentions are judged with it at once, old ones are not rescored). The default group can be renamed like any other but takes no description: it is the workspace itself and reads the company profile.'
      tags:
      - Groups
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Group id (grp_...).
          example: grp_abc123
        required: true
        description: Group id (grp_...).
        name: id
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: 'The group''s name: a customer, a campaign, a product. Unique per workspace.'
                externalId:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  maxLength: 128
                  description: Replaces your id for the group; null clears it.
                context:
                  type:
                  - string
                  - 'null'
                  maxLength: 4000
                  description: 'Replaces the group''s company description; null clears it (the workspace profile applies again). New mentions are judged with it at once; old ones are not rescored. Not on the default group (400 default_group_context): that one is the workspace itself and reads the profile.'
              description: Omitted fields are untouched.
      responses:
        '200':
          description: The updated group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: A company description on the default group (default_group_context)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such group in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A group with that name or externalId already exists (duplicate_group)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteGroup
      summary: Delete a group and its keywords
      description: 'Deletes the group and EVERY keyword in it, each the way DELETE /v1/keywords/{id} does (its mentions go with it, alert rules that named it are adjusted; charges already made stay on the usage record). Read the group first: `stats.keywords` says how many go. The default group cannot be deleted: move or delete its keywords instead.'
      tags:
      - Groups
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Group id (grp_...).
          example: grp_abc123
        required: true
        description: Group id (grp_...).
        name: id
        in: path
      responses:
        '204':
          description: Deleted, with its keywords
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such group in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The default group cannot be deleted (default_group)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.mentio.dev
components:
  schemas:
    Group:
      allOf:
      - $ref: '#/components/schemas/GroupRef'
      - type: object
        properties:
          context:
            type:
            - string
            - 'null'
            description: The group's own company description for the classifier, or null for the workspace profile.
          stats:
            type: object
            properties:
              keywords:
                type: integer
                minimum: 0
                description: Keywords in the group, muted ones included.
              active:
                type: integer
                minimum: 0
                description: Keywords in the group that are tracking (not muted).
            required:
            - keywords
            - active
            description: Computed over the group's keywords.
          createdAt:
            type: string
            description: ISO 8601 timestamp, UTC.
          updatedAt:
            type: string
            description: ISO 8601 timestamp, UTC.
        required:
        - context
        - stats
        - createdAt
        - updatedAt
      description: The group the keyword belongs to.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - read_only_key
              - validation_error
              - not_found
              - invalid_cursor
              - payload_too_large
              - rate_limited
              - duplicate_keyword
              - insufficient_balance
              - keyword_limit_reached
              - billing_not_configured
              - order_not_credited
              - schedule_required
              - unknown_channel
              - not_a_digest
              - hourly_email_unsupported
              - slack_not_connected
              - slack_not_configured
              - telegram_not_configured
              - feed_unreadable
              - feed_login_required
              - feed_login_expired
              - feed_limit_reached
              - feed_auth_not_configured
              - email_not_configured
              - invalid_assignee
              - classification_pending
              - invalid_member
              - already_member
              - last_owner
              - duplicate_segment
              - filter_too_complex
              - duplicate_view
              - duplicate_group
              - default_group
              - default_group_context
              - group_changed
              - invalid_signature
              - webhook_not_configured
              - invalid_token
              - protected_user
              - upstream_unavailable
              - internal_error
              description: '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.'
            message:
              type: string
              description: Human-readable detail; may change between releases.
            requestId:
              type: string
              description: The id of this request (also the X-Request-Id response header); quote it to support.
            retryAfterSeconds:
              type: integer
              description: 'For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).'
          required:
          - code
          - message
          description: The error.
      required:
      - error
    GroupRef:
      type: object
      properties:
        id:
          type: string
          description: Group id (grp_...).
        name:
          type: string
          description: The group's name.
        externalId:
          type:
          - string
          - 'null'
          description: Your own id for the group, or null.
        isDefault:
          type: boolean
          description: The workspace's default group, where a keyword lands when no group is named.
      required:
      - id
      - name
      - externalId
      - isDefault
      description: The group the keyword belongs to.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key minted via POST /v1/api-keys (format mk_live_...)
x-refined-from:
- api_mentio.json
- mentio-dev-api-openapi.json
- mentio-dev-app-openapi.json
- mentio-dev-openapi.json
x-mentio-errors:
- code: unauthorized
  status: 401
  source: user
  retryable: false
  description: No credential, or one that does not resolve to a workspace.
  fix: 'Send Authorization: Bearer mk_live_… with a key from /api-keys.'
- code: forbidden
  status: 403
  source: user
  retryable: false
  description: The credential is valid but may not do this.
- code: read_only_key
  status: 403
  source: user
  retryable: false
  description: A read key was used on a write endpoint.
  fix: Create a key with write scope.
- code: validation_error
  status: 400
  source: user
  retryable: false
  description: The body or query failed validation; the message names the field.
- code: not_found
  status: 404
  source: user
  retryable: false
  description: No such resource in your workspace. An id from another workspace is a 404, never a 403.
- code: invalid_cursor
  status: 400
  source: user
  retryable: false
  description: The cursor was not one this endpoint issued, or the filters changed between pages.
- code: payload_too_large
  status: 413
  source: user
  retryable: false
  description: The body exceeds the endpoint limit.
- code: rate_limited
  status: 429
  source: user
  retryable: true
  description: The workspace made more than 600 requests in a minute (every key and token together), or hit an endpoint's own cap; Retry-After says when.
  fix: Wait Retry-After seconds and send the same request again. X-RateLimit-Remaining on every response says how much room is left.
- code: duplicate_keyword
  status: 409
  source: user
  retryable: false
  description: The group already tracks this term. A term may be tracked once per group; another group may track it too.
- code: insufficient_balance
  status: 402
  source: user
  retryable: false
  description: The wallet cannot cover one more keyword-day.
  fix: Top up from Billing; tracking resumes on its own.
- code: keyword_limit_reached
  status: 402
  source: user
  retryable: false
  description: The self-serve keyword cap; beyond it is an enterprise conversation.
- code: billing_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no payment provider set up.
- code: schedule_required
  status: 400
  source: user
  retryable: false
  description: A daily alert rule was created without a schedule.
- code: unknown_channel
  status: 400
  source: user
  retryable: false
  description: A rule referenced a channel id the workspace does not own.
- code: not_a_digest
  status: 400
  source: user
  retryable: false
  description: A digest-only action was called on an instant rule.
- code: hourly_email_unsupported
  status: 400
  source: user
  retryable: false
  description: An hourly rule was given an email channel (up to 24 emails a day per rule). Use Slack, Telegram or a webhook, or a daily digest by email.
- code: slack_not_connected
  status: 409
  source: user
  retryable: false
  description: Connect Slack from Settings first. 404 on the Slack connection endpoints, 409 elsewhere.
- code: slack_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Slack app credentials.
- code: telegram_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Telegram bot.
- code: feed_unreadable
  status: 400
  source: user
  retryable: false
  description: No feed was found at the address, or the site blocks automated readers, or it answers an error; the message says which.
- code: feed_login_required
  status: 400
  source: user
  retryable: false
  description: The address answers a sign-in or access-denied page. Send it again with `auth` (the cookie your browser sends to the forum, or one header) to read it signed in.
- code: feed_login_expired
  status: 400
  source: user
  retryable: false
  description: 'The feed still answers a sign-in page with the `auth` sent: copy a fresh cookie from a signed-in browser.'
- code: feed_limit_reached
  status: 409
  source: user
  retryable: false
  description: A workspace reads at most 500 feeds; disconnect one before connecting another.
- code: feed_auth_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no FEED_AUTH_SECRET, so a feed sign-in (auth) cannot be stored encrypted and is refused instead.
- code: email_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Resend key, so nothing that needs Resend (the audience sync) can run.
- code: invalid_assignee
  status: 400
  source: user
  retryable: false
  description: The assignee id is not a workspace member.
- code: classification_pending
  status: 409
  source: user
  retryable: true
  description: A relevance or sentiment verdict was sent for a mention the classifier has not scored yet.
- code: invalid_member
  status: 400
  source: user
  retryable: false
  description: A person's owner, and the member an outreach activity is credited to, must be workspace members.
- code: already_member
  status: 409
  source: user
  retryable: false
  description: An invitation was sent to an address that already belongs to a member.
- code: last_owner
  status: 409
  source: user
  retryable: false
  description: Removing this member would leave the workspace without an owner.
- code: duplicate_segment
  status: 409
  source: user
  retryable: false
  description: Segment names are unique per workspace.
- code: filter_too_complex
  status: 400
  source: user
  retryable: false
  description: The filters together (lists, anyOf groups, a view or alert rule applied on top) name more values than one query can carry. Shorten the lists or use fewer groups.
- code: duplicate_view
  status: 409
  source: user
  retryable: false
  description: View names are unique per workspace.
- code: duplicate_group
  status: 409
  source: user
  retryable: false
  description: Group names and externalIds are unique per workspace.
- code: default_group
  status: 409
  source: user
  retryable: false
  description: Every workspace keeps one default group, where a keyword lands when no group is named.
- code: default_group_context
  status: 400
  source: user
  retryable: false
  description: 'The default group is the workspace itself: its company is the profile (PATCH /v1/company). A company description goes on any other group.'
- code: group_changed
  status: 409
  source: user
  retryable: false
  description: A keyword was created in or moved into the group while its keywords were being deleted. Its other keywords are gone; retry the delete.
- code: invalid_signature
  status: 401
  source: user
  retryable: false
  description: An inbound webhook did not carry a valid signature.
- code: webhook_not_configured
  status: 503
  source: system
  retryable: false
  description: The inbound webhook has no secret on this deployment.
- code: invalid_token
  status: 400
  source: user
  retryable: false
  description: A signed link (unsubscribe, confirmation) was tampered with or is malformed.
- code: protected_user
  status: 409
  source: user
  retryable: false
  description: Staff accounts cannot be deleted from the admin page.
- code: upstream_unavailable
  status: 502
  source: platform
  retryable: true
  description: A provider (Slack, Telegram, Polar, …) failed while serving your request. Retry with backoff.
- code: internal_error
  status: 500
  source: system
  retryable: false
  description: Something failed on our side. The response carries a requestId; quote it to support.