Mention Accounts API

openapi: 3.1.0
info:
  title: Mention Accounts 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: Accounts
  description: Mention accounts and the authenticated identity.
paths:
  /accounts:
    post:
      operationId: createAccount
      summary: Create an account
      description: >-
        Creates a new Mention account. The password must be at least 6 characters long and mix letters and figures.
        The optional client property records the name of the application registering the user.
      tags:
      - Accounts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/PostAccount.html
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
            example:
              name: John Smith
              email: j.smith@nasa.com
              password: REDACTED_EXAMPLE_PASSWORD
              language_code: en
      responses:
        '200':
          description: The created account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
        '400': &id001
          $ref: '#/components/responses/ValidationError'
        '401': &id002
          $ref: '#/components/responses/Unauthorized'
        '402': &id003
          $ref: '#/components/responses/PaymentRequired'
        '403': &id004
          $ref: '#/components/responses/Forbidden'
        '404': &id005
          $ref: '#/components/responses/NotFound'
        '429': &id006
          $ref: '#/components/responses/RateLimited'
      parameters:
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
  /accounts/me:
    get:
      operationId: getMe
      summary: Fetch my account
      description: >-
        Fetches all account details for the account that owns the access token used on the request. This is the standard
        way to resolve the account_id required by every other endpoint.
      tags:
      - Accounts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/GetAccountMe.html
      responses:
        '200':
          description: The authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
        '400': *id001
        '401': *id002
        '402': *id003
        '403': *id004
        '404': *id005
        '429': *id006
      parameters:
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
  /accounts/{account_id}:
    get:
      operationId: getAccount
      summary: Fetch an account
      description: >-
        Retrieves details for the given account. An access token cannot read another person's account, even when that
        account was created through this API.
      tags:
      - Accounts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/GetAccount.html
      parameters:
      - &id007
        name: account_id
        in: path
        required: true
        description: ID of the account.
        schema:
          type: string
        example: 12345_69gjjsg4itgkcco040okwsck700o4w8gsco0k4kco0s4scw8o0
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: The account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
        '400': *id001
        '401': *id002
        '402': *id003
        '403': *id004
        '404': *id005
        '429': *id006
    put:
      operationId: updateAccount
      summary: Update an account
      description: >-
        Modifies an existing account. Only the account that owns the access token can be modified. Changing the password
        requires sending both old_password and new_password rather than password.
      tags:
      - Accounts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/PutAccount.html
      parameters:
      - *id007
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
            example:
              name: John Smith
              email: j.smith@nasa.com
      responses:
        '200':
          description: The updated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
        '400': *id001
        '401': *id002
        '402': *id003
        '403': *id004
        '404': *id005
        '429': *id006
    delete:
      operationId: deleteAccount
      summary: Delete an account
      description: Deletes an account. As with GET and PUT, an access token cannot delete another person's account.
      tags:
      - Accounts
      externalDocs:
        description: Mention API reference
        url: https://dev.mention.com/current/src/account/DeleteAccount.html
      parameters:
      - *id007
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '204':
          description: The account was deleted.
        '400': *id001
        '401': *id002
        '402': *id003
        '403': *id004
        '404': *id005
        '429': *id006
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
    AccountCreate:
      type: object
      title: Account create
      required:
      - name
      - email
      - password
      - language_code
      properties:
        name:
          type: string
        email:
          type: string
          format: email
          minLength: 2
          maxLength: 255
        phone:
          type: string
        password:
          type: string
          minLength: 6
          description: At least 6 characters, mixing letters and figures.
        language_code:
          type: string
          description: Two character language code; valid values come from app/data.
        client:
          type: string
          description: Name of the application registering the user. Not updatable.
    AccountEnvelope:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
    AccountUpdate:
      type: object
      title: Account update
      description: >-
        Any property may be omitted. Changing the password requires old_password and new_password rather than password.
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        language_code:
          type: string
        old_password:
          type: string
        new_password:
          type: string