Metricool Planner Notes Mentions Api Service API

openapi: 3.2.0
info:
  title: Metricool Planner Notes Mentions Api Service API
  description: 'Metricool API


    The base URL for all endpoints is: https://app.metricool.com/api


    All endpoints require authentication.'
  version: 2.0.0
servers:
- url: https://app.metricool.com/api
tags:
- name: Planner Notes Mentions Api Service
paths:
  /v2/scheduler/notes/mentionable-users:
    get:
      tags:
      - Planner Notes Mentions Api Service
      summary: Get the users that can be mentioned in the notes of the brand's planner posts
      description: 'Calendar and library: whoever can see the brand''s posts. On a brand of an agency white-label that also covers the agency team members and the agency end clients. Deleted accounts are excluded. Rejected for sessions that cannot mention (integrator and white-label end clients, Vendasta and the anonymous reviewer). The whole list is returned: filtering by the typed text is done by the frontend over the loaded list.


        To write a mention into the note content, interpolate the entry''s `mentionId` and its `name` as `@[|]`.


        Use `mentionId` verbatim and never build it from `userId` or `agencyId`/`agencyUserId`: an agency end client has no `userId`, so composing the marker from it produces a marker the server cannot resolve and the mention is silently lost — the note saves, with no error, mentioning nobody.


        Use `name` for the label. What is stored is taken from the mentioned account rather than from the request, because the label lives inside the note content and the content is served verbatim to every reader, including sessions that must not see email addresses. A label written beside an id this API cannot resolve is kept as sent, except for an email address, which is reduced to its local part.'
      operationId: getMentionableUsers_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseMentionableUserDto'
components:
  schemas:
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    JsonOkListResponseMentionableUserDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/MentionableUserDto'
    MentionableUserDto:
      type: object
      properties:
        mentionId:
          type: string
          description: 'Id to write inside the mention marker of the note content, as @[<mentionId>|<name>]. Opaque and always present: interpolate it exactly as it arrives, never compose it from the id fields below. An agency end client has no userId, so a marker built from userId reads as @[null|...], which the server cannot resolve — the note saves but mentions nobody, with no error.'
          example: a:37:156
        userId:
          type: integer
          description: Regular user id of the user. Absent for an agency end client.
          format: int32
          example: 12345
        agencyId:
          type: integer
          description: Agency id of the user. Only for an agency end client.
          format: int32
          example: 37
        agencyUserId:
          type: integer
          description: Agency user id of the user. Only for an agency end client.
          format: int32
          example: 156
        label:
          type: string
          description: 'Badge to show next to the user, relative to the requesting session: CLIENT (an agency end client, as seen by a Metricool session), STAFF (anyone who is not an agency end client, as seen by an agency end-client session), or absent for no badge.'
          enum:
          - CLIENT
          - STAFF
        name:
          type: string
          description: Display name of the user, and the value to use as the mention label. A nameless account — common, since invited collaborators and end clients have no name until they activate — falls back to the local part of its address, never the whole address, because this value ends up stored inside the note content.
        email:
          type: string
          description: 'Email of the user, for display in the picker only. Omitted for agency end-client sessions, which must not see the emails of the agency staff nor of the other clients. Never use it as the mention label: the label is stored in the note content and served verbatim to readers who must not see addresses.'
        profilePicture:
          type: string
          description: Public URL of the user's 400x400 profile picture. Absent when they have none, in which case the frontend renders its initials fallback. Always absent for agency end clients — agency pictures are out of scope.
      description: A team member that can be mentioned in the notes of a brand.