Metricool Notifications Feed Api Service API

openapi: 3.2.0
info:
  title: Metricool Notifications Feed 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: Notifications Feed Api Service
paths:
  /v2/notifications/feed:
    get:
      tags:
      - Notifications Feed Api Service
      summary: Get the authenticated user's in-app notification feed, most recent first
      operationId: getFeed
      parameters:
      - name: page
        in: query
        description: Page number (0-based)
        required: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: pageSize
        in: query
        description: Number of results per page
        required: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          format: int32
      - name: unreadOnly
        in: query
        description: Only return unread notifications
        required: true
        schema:
          type: boolean
      responses:
        '200':
          description: Paginated feed plus unread count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseNotificationFeedPageDto'
        '400':
          description: Delegated proxy sessions (integrator/alias/Vendasta) cannot access the feed
  /v2/notifications/read-all:
    put:
      tags:
      - Notifications Feed Api Service
      summary: Mark every one of the authenticated user's notifications as read
      operationId: markAllNotificationsAsRead
      responses:
        '200':
          description: All notifications marked as read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseMarkAllNotificationsResponse'
        '400':
          description: Delegated proxy sessions (integrator/alias/Vendasta) cannot access the feed
  /v2/notifications/unread-count:
    get:
      tags:
      - Notifications Feed Api Service
      summary: Get the authenticated user's unread in-app notification count
      operationId: getUnreadCount
      responses:
        '200':
          description: Unread count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseUnreadCountDto'
        '400':
          description: Delegated proxy sessions (integrator/alias/Vendasta) cannot access the feed
  /v2/notifications/{id}/read:
    put:
      tags:
      - Notifications Feed Api Service
      summary: Mark a single notification as read or unread
      operationId: markNotificationAsRead
      parameters:
      - name: id
        in: path
        description: Notification id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkNotificationRequest'
        required: true
      responses:
        '200':
          description: Notification marked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseNotificationReadResponse'
        '404':
          description: Notification not found or not owned by the caller
        '400':
          description: Malformed notification id, or delegated proxy sessions cannot access the feed
components:
  schemas:
    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
    JsonOkResponseNotificationReadResponse:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/NotificationReadResponse'
    UnreadCountDto:
      type: object
      properties:
        count:
          type: integer
          description: Total unread notifications, within the 30-day retention window
          format: int32
          example: 3
      description: The authenticated user's unread in-app notification count
    NotificationFeedItemDto:
      type: object
      properties:
        id:
          type: integer
          description: Notification row id
          format: int64
          example: 12345
        eventType:
          type: string
          description: Notification event type id
          example: postApproved
        text:
          type: string
          description: Display text for this notification
        link:
          type: string
          description: Relative link to the notification's destination (post, connections screen, etc.)
        read:
          type: boolean
          description: Whether the notification has already been read
        actor:
          $ref: '#/components/schemas/NotificationActorDto'
        createdAt:
          $ref: '#/components/schemas/DateTimeInfo'
        network:
          type: string
          description: Social network id this notification is about, blank when not applicable
          example: instagram
        noteText:
          type: string
          description: The note's content, only present for postNote
          example: hay que hacer el CTA más evidente
        scheduledDate:
          type: string
          description: ISO scheduled/publish date of the post this notification is about, blank when not applicable; for monthlyReport this instead carries the first day of the covered month, not a post's date
        accountName:
          type: string
          description: Connected account name, only present for accountTokenExpired
          example: '@metricool'
        networks:
          type: array
          description: Every network id the post targets — populated for postNote/postApproved/postRejected, which are post-level events (a post can target several networks at once); for aiNetworkInstructionsGenerated, every network of the generation; for manualPostPending, the single network the post has to be published on by hand; empty otherwise
          items:
            type: string
            description: Every network id the post targets — populated for postNote/postApproved/postRejected, which are post-level events (a post can target several networks at once); for aiNetworkInstructionsGenerated, every network of the generation; for manualPostPending, the single network the post has to be published on by hand; empty otherwise
        prompt:
          type: string
          description: The prompt behind the notification, truncated; populated for nlSchedulingJobFinished/nlSchedulingJobFailed (the natural-language prompt that launched the job) and for studioReportFinished/studioReportFailed (the prompt used to generate the Studio report, truncated to 300 characters), blank otherwise
          example: Schedule 3 posts about the new summer collection
        postsCount:
          type: integer
          description: Number of posts generated by the job, only present for nlSchedulingJobFinished
          format: int32
          example: 3
        errorMessage:
          type: string
          description: The job's failure reason; populated for nlSchedulingJobFailed and for a failed single-network aiNetworkInstructionsGenerated, blank otherwise
        brandNames:
          type: array
          description: Label of every brand the Studio report's content was matched to; only present for studioReportFinished/studioReportFailed
          items:
            type: string
            description: Label of every brand the Studio report's content was matched to; only present for studioReportFinished/studioReportFailed
        failedNetworks:
          type: array
          description: Networks whose AI instructions generation failed, only for aiNetworkInstructionsGenerated; the rest of networks succeeded. Empty otherwise
          example:
          - tiktok
          items:
            type: string
            description: Networks whose AI instructions generation failed, only for aiNetworkInstructionsGenerated; the rest of networks succeeded. Empty otherwise
            example: '["tiktok"]'
      description: One item of the authenticated user's in-app notification feed
    MarkAllNotificationsResponse:
      type: object
      properties:
        updatedCount:
          type: integer
          description: Number of notifications marked as read
          format: int32
          example: 12
        unreadCount:
          type: integer
          description: Current unread count for the user (should be 0)
          format: int64
          example: 0
      description: Response after marking all notifications as read
    JsonOkResponseUnreadCountDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/UnreadCountDto'
    MarkNotificationRequest:
      required:
      - read
      type: object
      properties:
        read:
          type: boolean
          description: true to mark as read, false to mark as unread
          example: true
      description: Request to mark a notification as read or unread
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    NotificationFeedPageDto:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageDtoNotificationFeedItemDto'
        unreadCount:
          type: integer
          description: Total unread notifications for the user, within the 30-day retention window
          format: int32
          example: 3
      description: One page of the authenticated user's in-app notification feed
    JsonOkResponseMarkAllNotificationsResponse:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/MarkAllNotificationsResponse'
    NotificationActorDto:
      type: object
      properties:
        name:
          type: string
          description: Display name to show (profile name, or the actor's email if they have none configured)
          example: Pedro
        regularUserId:
          type: integer
          description: The actor's regular user id, when they have a Metricool account (null for an agency-managed actor or one with no account)
          format: int32
          example: 55
        agencyId:
          type: integer
          description: The actor's agency id, when they are an agency-managed user (null otherwise)
          format: int32
          example: 3
        agencyUserId:
          type: integer
          description: The actor's agency-managed user id (null otherwise)
          format: int32
          example: 9
      description: The user who triggered a notification, when this event type has one
    PageDtoNotificationFeedItemDto:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/NotificationFeedItemDto'
        pageNumber:
          type: integer
          format: int64
        pageSize:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
      description: Paginated feed items
    JsonOkResponseNotificationFeedPageDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/NotificationFeedPageDto'
    NotificationReadResponse:
      type: object
      properties:
        notificationId:
          type: integer
          description: ID of the notification that was marked
          format: int64
          example: 456
        unreadCount:
          type: integer
          description: Current unread count for the user after the operation
          format: int64
          example: 5
      description: Response after marking a notification