Mention Alerts API

openapi: 3.1.0
info:
  title: Mention Alerts API
  description: >-
    The Mention API is a JSON-based, RESTful API that gives programmatic access to the media monitoring and social
    listening platform: alerts (the keyword queries Mention crawls for), mentions (the results it finds), curation,
    tags, tasks, alert sharing, authors and influencers, and aggregate statistics. Everything the Mention web client
    can do is available through this API.


    Authentication uses bearer tokens, obtained either from an app's settings page (for your own account) or through
    the OAuth2 authorization-code flow (for a third party's account). Requests send JSON with a Content-Type: application/json
    header; the OAuth2 endpoints alone take application/x-www-form-urlencoded. Dates use the W3C date-time format
    level 6 (YYYY-MM-DDThh:mm:ss.sTZD) so that fractional seconds can drive date-based pagination. Collections are
    cursor-paginated through a _links object. The API version is selected per request with the Accept-Version header;
    without it, the version configured in the app's settings applies.


    This description was reconstructed from Mention's own published API reference at https://dev.mention.com/current/
    — Mention does not publish a machine-readable OpenAPI definition.
  version: '1.21'
  contact:
    name: Mention Support
    url: https://en.support.mention.com/
  license:
    name: Proprietary
    url: https://mention.com/en/terms-and-conditions/
externalDocs:
  description: Mention API reference
  url: https://dev.mention.com/current/
x-generated-from: https://dev.mention.com/current/
x-generated-by: api-evangelist-enrichment-2026-08-13
servers:
- url: https://api.mention.net/api
  description: Mention API — the base URL named in Mention's own reference documentation.
- url: https://api.mention.com/api
  description: Alternate host observed answering the same API (returns the same OAuth2 challenge).
security:
- bearerAuth: []
- accessTokenQuery: []
- oauth2: []
tags:
- name: Alerts
  description: The keyword queries Mention crawls the web and social media for.
paths:
  /accounts/{account_id}/alerts:
    get:
      operationId: listAlerts
      summary: Fetch all alerts of an account
      description: >-
        Returns the alerts visible to the account. The collection is paginated with an opaque cursor; follow _links.more
        to page. Since API version 1.21 the stats field is empty by default — request counters explicitly with the
        stats query string parameter.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/GetAlerts.html
      parameters:
      - &id001
        name: account_id
        in: path
        required: true
        description: ID of the account.
        schema:
          type: string
        example: 12345_69gjjsg4itgkcco040okwsck700o4w8gsco0k4kco0s4scw8o0
      - name: limit
        in: query
        required: false
        description: 'Number of alerts to return. Default: return all alerts.'
        schema:
          type: integer
        example: 20
      - name: cursor
        in: query
        required: false
        description: Opaque pagination cursor supplied by the API in _links.more.
        schema:
          type: string
        example: abc
      - name: ids
        in: query
        required: false
        explode: true
        description: IDs of the alerts to fetch. Must not contain more than 50 ids.
        schema:
          type: array
          maxItems: 50
          items:
            type: integer
      - name: stats
        in: query
        required: false
        description: >-
          Comma-separated list of alert counters to include. One or more of mention_folders.inbox.total, mention_folders.archive.total,
          mention_folders.spam.total, mention_folders.trash.total, unread_mentions.total, unseen_mentions.total, favorite_mentions.total,
          tasks.total, todo_tasks, done_tasks, logs.total. Added in API version 1.21.
        schema:
          type: string
        example: unread_mentions.total,mention_folders.inbox.total
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: A paginated list of alerts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertList'
        '400': &id002
          $ref: '#/components/responses/ValidationError'
        '401': &id003
          $ref: '#/components/responses/Unauthorized'
        '402': &id004
          $ref: '#/components/responses/PaymentRequired'
        '403': &id005
          $ref: '#/components/responses/Forbidden'
        '404': &id006
          $ref: '#/components/responses/NotFound'
        '429': &id007
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createAlert
      summary: Create an alert
      description: >-
        Creates a new alert for the account. A query is either basic (included / required / excluded keyword arrays)
        or advanced (a boolean query_string). At least one of included_keywords or required_keywords must carry a
        keyword. Since API version 1.21 the group_id query string parameter is always mandatory.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/PostAlert.html
      parameters:
      - *id001
      - name: group_id
        in: query
        required: true
        description: >-
          Group the alert belongs to. Mandatory since API version 1.21; before 1.21 it could be omitted when the caller
          had only one group.
        schema:
          type: string
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreate'
            example:
              name: NASA and competitors
              query:
                type: basic
                included_keywords:
                - NASA
                - Arianespace
                - SpaceX
              languages:
              - en
              sources:
              - web
      responses:
        '200':
          description: The created alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
  /accounts/{account_id}/alerts/{alert_id}:
    get:
      operationId: getAlert
      summary: Fetch an alert
      description: Retrieve details about a single alert, including its query, sources, languages, shares and permissions.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/GetAlert.html
      parameters:
      - *id001
      - &id008
        name: alert_id
        in: path
        required: true
        description: ID of the alert.
        schema:
          type: integer
        example: 112233
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: The alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
    put:
      operationId: updateAlert
      summary: Update an alert
      description: >-
        Modifies an existing alert, usually to refine the query criteria and improve the search's efficiency. Omitted
        properties are left unchanged; an alert fetched with GET may be sent back unchanged.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/PutAlert.html
      parameters:
      - *id001
      - *id008
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertUpdate'
            example:
              name: Space innovation
              query:
                type: advanced
                query_string: (space AND innovation)
      responses:
        '200':
          description: The updated alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
  /accounts/{account_id}/alerts/{alert_id}/pause:
    post:
      operationId: pauseAlert
      summary: Pause an alert
      description: Pauses a single alert so that it stops collecting new mentions.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/PostAlertPause.html
      parameters:
      - *id001
      - *id008
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: The paused alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
  /accounts/{account_id}/alerts/{alert_id}/unpause:
    post:
      operationId: unpauseAlert
      summary: Unpause an alert
      description: Resumes collection on a previously paused alert.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/PostAlertUnpause.html
      parameters:
      - *id001
      - *id008
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: The resumed alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
  /accounts/{account_id}/alerts/{alert_id}/preferences:
    get:
      operationId: getAlertPreferences
      summary: Fetch preferences of an alert
      description: Retrieves the per-account notification preferences and display weight for the given alert.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/preferences/GetPreferences.html
      parameters:
      - *id001
      - *id008
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: The alert preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferencesEnvelope'
              example:
                preferences:
                  email_notification_frequency: default
                  push_notification_frequency: default
                  desktop_notification_frequency: default
                  trending_email_notification_frequency: default
                  trending_sms_notification_frequency: default
                  weight: 10000
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
    put:
      operationId: updateAlertPreferences
      summary: Update preferences of an alert
      description: >-
        Updates the alert preferences. Any attribute returned by the GET request can be updated, and any attribute
        may be omitted. The weight attribute controls how important the alert is in the interface.
      tags:
      - Alerts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/alert/preferences/PutPreferences.html
      parameters:
      - *id001
      - *id008
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Preferences'
            example:
              push_notification_frequency: never
              weight: 1
      responses:
        '200':
          description: The updated preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferencesEnvelope'
        '400': *id002
        '401': *id003
        '402': *id004
        '403': *id005
        '404': *id006
        '429': *id007
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Access token passed in the Authorization header, prefixed with 'Bearer '. This is the preferred method. A
        token for your own account is available at the bottom of your app's settings page.
    accessTokenQuery:
      type: apiKey
      in: query
      name: access_token
      description: >-
        The same access token passed in the query string. Supported but discouraged, as it puts the credential in
        the URL.
    oauth2:
      type: oauth2
      description: >-
        Authorization-code flow used to obtain an access token for a third party's Mention account. No scopes are
        defined: a granted token carries full access to the authorizing account.
      flows:
        authorizationCode:
          authorizationUrl: https://web.mention.com/authorize
          tokenUrl: https://web.mention.net/oauth/v2/token
          scopes: {}
  parameters:
    AcceptVersion:
      name: Accept-Version
      in: header
      required: false
      description: >-
        API version to use for this request, e.g. 1.21. When omitted, the version configured in the app's settings
        applies.
      schema:
        type: string
      example: '1.21'
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      description: Language used for translated resource fields.
      schema:
        type: string
      example: fr
  responses:
    ValidationError:
      description: Invalid input — query string, body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    Unauthorized:
      description: Access was denied — missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
    PaymentRequired:
      description: Payment required — the account's plan does not cover this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
    Forbidden:
      description: Access was denied — the token is valid but not permitted on this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
    NotFound:
      description: The resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
    RateLimited:
      description: >-
        Rate limited. The response carries an X-Rate-Limit-Reset header holding the unix timestamp at which the limit
        resets.
      headers:
        X-Rate-Limit-Reset:
          description: Unix timestamp at which the rate limit resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  schemas:
    Account:
      type: object
      title: Account
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        language_code:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
        avatar_url:
          type: string
        timezone:
          type: string
        grouped_email_notification:
          type: boolean
        default_email_notification_frequency:
          type: string
        default_desktop_notification_frequency:
          type: string
        default_push_notification_frequency:
          type: string
        permissions:
          type: object
          additionalProperties: true
    Alert:
      type: object
      title: Alert
      properties:
        id:
          type: string
          example: '112233'
        name:
          type: string
        query:
          $ref: '#/components/schemas/AlertQuery'
        languages:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        blocked_sites:
          type: array
          items:
            type: string
        role:
          type: string
        stats:
          type: object
          additionalProperties: true
          description: >-
            Alert counters. Empty by default since API version 1.21 — request counters with the stats query string
            parameter.
        shares:
          type: array
          items:
            $ref: '#/components/schemas/Share'
        noise_detection:
          type: boolean
        created_at:
          type: string
        updated_at:
          type: string
        quota_used:
          type: integer
        index_version:
          type: integer
          description: Search index version of the alert; determines which mention filters are available to it.
        permissions:
          type: object
          additionalProperties:
            type: boolean
        description:
          type: string
        color:
          type: string
          example: '#05e363'
        connection_type:
          type: string
          enum:
          - main
          - related
          - independent
          description: >-
            main is the first alert created at onboarding, related is a competitor alert created alongside it, independent
            is any later unrelated alert.
        connection_id:
          type: string
          description: 'Set only on related alerts: the id of the main alert.'
    AlertCreate:
      type: object
      title: Alert create
      required:
      - name
      - query
      - languages
      properties:
        name:
          type: string
          description: Human readable identifier of the alert.
          example: NASA and competitors
        query:
          $ref: '#/components/schemas/AlertQuery'
        languages:
          type: array
          items:
            type: string
          description: Language codes to track.
          example:
          - en
          - fr
          - ru
        countries:
          type: array
          items:
            type: string
          example:
          - US
          - RU
        sources:
          type: array
          items:
            type: string
          description: Sources to crawl. Valid values come from app/data.
          example:
          - web
          - twitter
        blocked_sites:
          type: array
          items:
            type: string
        noise_detection:
          type: boolean
        reviews_pages:
          type: array
          items:
            type: string
    AlertEnvelope:
      type: object
      properties:
        alert:
          $ref: '#/components/schemas/Alert'
    AlertList:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
        _links:
          $ref: '#/components/schemas/Links'
    AlertQuery:
      type: object
      title: Alert query
      description: >-
        Either a basic keyword query or an advanced boolean query_string, discriminated by type. Keywords may contain
        alphanumerics, whitespace and ._@#'&, plus - when preceded by an alphanumeric. At least one of included_keywords
        or required_keywords must be non-empty.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - basic
          - advanced
        included_keywords:
          type: array
          items:
            type: string
          description: At least one must appear in a mention.
        required_keywords:
          type: array
          items:
            type: string
          description: All must appear in a mention.
        excluded_keywords:
          type: array
          items:
            type: string
          description: None may appear in a mention.
        monitored_website:
          $ref: '#/components/schemas/MonitoredWebsite'
        query_string:
          type: string
          description: >-
            Advanced boolean expression, e.g. (NASA AND Discovery) OR (Arianespace AND Ariane). A single clause may
            not mix AND and OR without parentheses.
    AlertUpdate:
      allOf:
      - $ref: '#/components/schemas/AlertCreate'
      title: Alert update
      description: Any property may be omitted; omitted properties are left unchanged.
    Link:
      type: object
      properties:
        href:
          type: string
          description: Relative URL to follow.
        params:
          type: object
          description: The query string parameters encoded in href.
          additionalProperties: true
    Links:
      type: object
      title: Pagination links
      description: >-
        Hypermedia links for cursor pagination. more points at older items and pull at newer items; each is present
        only when applicable.
      properties:
        more:
          $ref: '#/components/schemas/Link'
        pull:
          $ref: '#/components/schemas/Link'
    MonitoredWebsite:
      type: object
      title: Monitored website
      description: >-
        The domain acts as an included keyword; when block_self is true it also acts as a blocked url. A full URL
        is stripped down to its domain.
      required:
      - domain
      - block_self
      properties:
        domain:
          type: string
          example: www.nasa.gov
        block_self:
          type: boolean
          example: true
    Preferences:
      type: object
      title: Alert preferences
      description: Notification frequency vocabularies come from app/data and may change without notice.
      properties:
        email_notification_frequency:
          type: string
        push_notification_frequency:
          type: string
        desktop_notification_frequency:
          type: string
        trending_email_notification_frequency:
          type: string
        trending_sms_notification_frequency:
          type: string
        weight:
          type: integer
          description: How important the alert is.
    PreferencesEnvelope:
      type: object
      properties:
        preferences:
          $ref: '#/components/schemas/Preferences'
    Share:
      type: object
      title: Alert share
      description: The link between an account and an alert. Deleting the last share deletes the alert.
      properties:
        id:
          type: string
        account:
          $ref: '#/components/schemas/Account'
        role:
          type: string
        blocked:
          type: boolean
        permissions:
          type: object
          additionalProperties:
            type: boolean
        created_at:
          type: string
        weight:
          type: integer