Metricool Inbox Notes Api Service API

openapi: 3.2.0
info:
  title: Metricool Inbox Notes 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: Inbox Notes Api Service
paths:
  /v2/inbox/notes:
    get:
      tags:
      - Inbox Notes Api Service
      operationId: getNotes
      parameters:
      - name: participantScreenNames
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: participantAccountIds
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: provider
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseInboxNote'
      summary: Get notes
      x-summary-source: derived
    post:
      tags:
      - Inbox Notes Api Service
      operationId: createNote
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxNoteRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseInboxNote'
      summary: Create note
      x-summary-source: derived
  /v2/inbox/notes/mentionable-users:
    get:
      tags:
      - Inbox Notes Api Service
      summary: Get the users that can be mentioned in the notes of the brand's Inbox…
      description: 'Whoever can read those notes, so a mention never names somebody the note will not reach. 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, anonymous). Requires `fullAccessInbox`, the same permission writing a note needs: a read-only Inbox session can never mention anybody. 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseMentionableUserDto'
  /v2/inbox/notes/{noteId}:
    put:
      tags:
      - Inbox Notes Api Service
      operationId: updateNote
      parameters:
      - name: noteId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxNoteRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseInboxNote'
      summary: Update note
      x-summary-source: derived
    delete:
      tags:
      - Inbox Notes Api Service
      operationId: deleteNote
      parameters:
      - name: noteId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
      summary: Delete note
      x-summary-source: derived
components:
  schemas:
    JsonOkResponseInboxNote:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/InboxNote'
    InboxNote:
      required:
      - content
      - contextBlogId
      - created
      - id
      - provider
      - userName
      type: object
      properties:
        id:
          type: integer
          format: int32
        contextBlogId:
          type: integer
          format: int32
        participantScreenName:
          type: string
        participantAccountId:
          type: string
        provider:
          type: string
        userId:
          type: integer
          description: Regular user id of the note author. Absent for an agency end client.
          format: int32
          example: 12345
        agencyId:
          type: integer
          description: Agency id of the note author. Only for an agency end client.
          format: int32
          example: 37
        agencyUserId:
          type: integer
          description: Agency user id of the note author. Only for an agency end client.
          format: int32
          example: 156
        userName:
          minLength: 1
          type: string
          description: 'Name to render for the author. Never an email address: an agency end client is stored under a display name, and a regular author''s stored address is replaced on read for any session not entitled to see it.'
        created:
          $ref: '#/components/schemas/DateTimeInfo'
        content:
          minLength: 1
          type: string
        updatedDate:
          $ref: '#/components/schemas/DateTimeInfo'
        updated:
          type: boolean
        deletedDate:
          $ref: '#/components/schemas/DateTimeInfo'
        deleted:
          type: boolean
        profilePicture:
          type: string
          description: Public URL of the author's 400x400 profile picture. Absent when they have none, in which case the frontend renders its initials fallback. Always absent for an agency end client — agency pictures are out of scope.
        mentions:
          type: array
          description: Users mentioned in the content of the note, resolved when the note is read. Empty when the note mentions nobody.
          items:
            $ref: '#/components/schemas/NoteMentionDto'
        mentionId:
          type: string
          description: 'Identity of the note author, and the field to compare against your own to tell whether a note is yours. `12345` for a regular user, `a:<agencyId>:<agencyUserId>` for an agency end client. Prefer it over the raw id fields: an agency author has no `userId` at all, so comparing that one answers "not mine" on their own note. Same shape as the `mentionId` of the mention picker, so the author of a note and the entry that mentions them carry the same string. Absent only for a note whose author could not be resolved.'
          example: a:37:156
    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.
    NoteMentionDto:
      type: object
      properties:
        userId:
          type: integer
          description: Regular user id of the mentioned user. Absent for an agency end client.
          format: int32
          example: 12345
        agencyId:
          type: integer
          description: Agency id of the mentioned user. Only for an agency end client.
          format: int32
          example: 37
        agencyUserId:
          type: integer
          description: Agency user id of the mentioned user. Only for an agency end client.
          format: int32
          example: 156
        name:
          type: string
          description: Current display name of the mentioned user. Absent when the account was deleted, in which case the frontend renders its own localized deleted-user label.
        deleted:
          type: boolean
          description: 'True when the mentioned account no longer exists. A user that merely lost access to the brand is not deleted: their mention keeps rendering as it always did.'
      description: A user mentioned in the content of a note, resolved when the note is read.
    JsonOkResponseBoolean:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: boolean
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    InboxNoteRequest:
      required:
      - content
      type: object
      properties:
        participantScreenName:
          type: string
        participantAccountId:
          type: string
        provider:
          type: string
        content:
          minLength: 1
          type: string
    JsonOkListResponseInboxNote:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/InboxNote'
    DateTimeInfo:
      required:
      - dateTime
      type: object
      properties:
        dateTime:
          type: string
          description: 'Local Date-time represented with a certain timezone '
        timezone:
          type: string
          description: Timezone applied to the datetime
    JsonOkListResponseMentionableUserDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/MentionableUserDto'