Metricool Library Posts State Api Service API

openapi: 3.2.0
info:
  title: Metricool Library Posts State 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: Library Posts State Api Service
paths:
  /v2/scheduler/library/posts/state:
    put:
      tags:
      - Library Posts State Api Service
      summary: Set or clear the workflow state of several library posts in one request
      description: 'Best-effort: ids that do not resolve to a live post of the brand come back in ''failures'' and do not stop the rest of the selection from moving. Every post that actually changes state records it in its activity history; one already in the target state is returned as succeeded without an entry. At most 500 ids per request.'
      operationId: updateStatesInBulk
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateLibraryPostStateRequest'
        required: true
      responses:
        '200':
          description: 'Request processed. Partial success lives here too: ''succeeded'' and ''failures'' coexist in the same 200 response.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBulkUpdateLibraryPostStateResult'
        '400':
          description: 'Invalid selection: postIds empty, over 500 ids, or containing a null or non-positive id.'
        '403':
          description: User not authorized on the brand.
        '404':
          description: State not found for this brand. No post is moved.
  /v2/scheduler/library/posts/{postId}/state:
    put:
      tags:
      - Library Posts State Api Service
      summary: Set or clear the workflow state of a library post
      operationId: updateState
      parameters:
      - name: postId
        in: path
        description: id of the library post.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLibraryPostStateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseLibraryPostDto'
  /v2/scheduler/library/states:
    get:
      tags:
      - Library Posts State Api Service
      summary: Get the workflow states of the brand's library (excludes the permanent 'Sin…
      operationId: getStates
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseLibraryPostStateDto'
    post:
      tags:
      - Library Posts State Api Service
      summary: Create a new workflow state for the brand's library (appended as the last…
      operationId: createState
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveLibraryPostStateRequest'
        required: true
      responses:
        '201':
          description: State created.
        '400':
          description: Invalid name or color.
        '403':
          description: User not authorized on the brand.
        '409':
          description: Name already in use, or the brand reached the max number of states.
  /v2/scheduler/library/states/{stateId}:
    put:
      tags:
      - Library Posts State Api Service
      summary: Rename and recolor a workflow state
      operationId: modifyState
      parameters:
      - name: stateId
        in: path
        description: id of the workflow state.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveLibraryPostStateRequest'
        required: true
      responses:
        '200':
          description: State updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseLibraryPostStateDto'
        '400':
          description: Invalid name or color.
        '403':
          description: User not authorized on the brand.
        '404':
          description: State not found for this brand.
        '409':
          description: Name already in use by another state.
    delete:
      tags:
      - Library Posts State Api Service
      summary: Delete a workflow state. Blocked if any library post is still assigned to it
      operationId: deleteState
      parameters:
      - name: stateId
        in: path
        description: id of the workflow state.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: State deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseString'
        '403':
          description: User not authorized on the brand.
        '404':
          description: State not found for this brand.
        '409':
          description: State still has library posts assigned.
  /v2/scheduler/library/states/{stateId}/position:
    put:
      tags:
      - Library Posts State Api Service
      summary: Move a workflow state to a new position (reorder), shifting the states in…
      operationId: moveState
      parameters:
      - name: stateId
        in: path
        description: id of the workflow state.
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveLibraryPostStateRequest'
        required: true
      responses:
        '200':
          description: Resulting order of the brand's states.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseLibraryPostStateDto'
        '400':
          description: Position out of range.
        '403':
          description: User not authorized on the brand.
        '404':
          description: State not found for this brand.
components:
  schemas:
    InstagramCollaboratorTag:
      type: object
      properties:
        username:
          type: string
        deleted:
          type: boolean
    LibraryPostLocationCoordinates:
      type: object
      properties:
        city:
          type: string
        country:
          type: string
        state:
          type: string
        street:
          type: string
        zip:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    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.
    YoutubeConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        title:
          type: string
        type:
          type: string
        privacy:
          type: string
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
        category:
          type: string
        madeForKids:
          type: boolean
        playlistId:
          type: string
        isAiGeneratedContent:
          type: boolean
        notifySubscribers:
          type: boolean
    LinkedinPollDto:
      type: object
      properties:
        question:
          type: string
        options:
          type: array
          items:
            $ref: '#/components/schemas/LinkedinOptionDto'
        settings:
          $ref: '#/components/schemas/LinkedinSettingsDto'
    TwitterConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        tags:
          uniqueItems: true
          type: array
          items:
            type: string
        replySettings:
          type: string
        type:
          type: string
        poll:
          $ref: '#/components/schemas/ScheduledPostTwitterPoll'
    LinkedinSettingsDto:
      type: object
      properties:
        duration:
          type: string
    LibraryPostCommonConfigurationDto:
      required:
      - content
      type: object
      properties:
        content:
          type: string
        firstCommentText:
          type: string
        publishMode:
          type: string
        smartlinkData:
          $ref: '#/components/schemas/SmartlinkData'
    LibraryPostBulkStateFailure:
      type: object
      properties:
        postId:
          type: integer
          description: The id as it was submitted.
          format: int64
          example: 8802
        reason:
          type: string
          description: Why a post listed in a bulk workflow state change could not be moved.
          enum:
          - NOT_FOUND
      description: One id from a bulk workflow state change that could not be moved.
    InstagramAudioConfigurationDto:
      required:
      - audioId
      type: object
      properties:
        audioId:
          minLength: 1
          type: string
          description: Unique identifier of the audio asset from the Instagram Audio API.
        audioType:
          type: string
          description: 'Audio type. Allowed values: ''music'', ''original_sound''.'
          enum:
          - music
          - original_sound
          - music
          - original_sound
        title:
          type: string
          description: Title of the audio track.
        displayArtist:
          type: string
          description: Display artist name (populated for 'music' type).
        igUsername:
          type: string
          description: Instagram username of the creator (populated for 'original_sound' type).
        coverArtworkUrl:
          type: string
          description: URL of the cover artwork thumbnail.
        durationMs:
          type: integer
          description: Duration of the audio in milliseconds.
          format: int64
        audioVolume:
          maximum: 100
          minimum: 0
          type: integer
          description: Volume level for the audio asset, from 0 (muted) to 100 (full volume). Defaults to 100.
          format: int32
        videoVolume:
          maximum: 100
          minimum: 0
          type: integer
          description: Volume level for the video's original audio, from 0 (muted) to 100 (full volume). Defaults to 100.
          format: int32
    JsonOkResponseLibraryPostStateDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/LibraryPostStateDto'
    LibraryPostAssigneeDto:
      type: object
      properties:
        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
        userId:
          type: integer
          description: Regular user id of the assignee. Absent for an agency end client.
          format: int64
          example: 12345
        agencyId:
          type: integer
          description: Agency id of the assignee. Only for an agency end client.
          format: int32
          example: 42
        agencyUserId:
          type: integer
          description: Agency user id of the assignee. Only for an agency end client.
          format: int32
          example: 7
        name:
          type: string
          description: Display name of the assignee, or null when it cannot be resolved.
        deleted:
          type: boolean
          description: True when the assignee account has been deleted (frontend shows 'deleted user').
        hasBrandAccess:
          type: boolean
          description: False when the assignee no longer has access to this brand (frontend shows a warning).
        profilePicture:
          type: string
          description: Absolute URL of the assignee's profile picture. Omitted when it has none; the UI then renders its initials. Filled for both assignee kinds (ES5MPTM3-7292).
      description: Team member assigned to a library post.
    TikTokConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        disableComment:
          type: boolean
        disableDuet:
          type: boolean
        disableStitch:
          type: boolean
        privacyOption:
          type: string
        commercialContentThirdParty:
          type: boolean
        commercialContentOwnBrand:
          type: boolean
        title:
          type: string
        autoAddMusic:
          type: boolean
        photoCoverIndex:
          type: integer
          format: int32
        music:
          $ref: '#/components/schemas/TikTokTrackDto'
        isAigc:
          type: boolean
    ScheduledPostTwitterPollSettings:
      type: object
      properties:
        durationMinutes:
          type: integer
          format: int32
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    LinkedinConfigurationDto:
      required:
      - previewIncluded
      - publishImagesAsPDF
      type: object
      properties:
        enabled:
          type: boolean
        documentTitle:
          type: string
        publishImagesAsPDF:
          type: boolean
        previewIncluded:
          type: boolean
        type:
          type: string
        poll:
          $ref: '#/components/schemas/LinkedinPollDto'
    TikTokTrackDto:
      type: object
      properties:
        musicId:
          type: string
        title:
          type: string
        author:
          type: string
        previewUrl:
          type: string
        thumbnailUrl:
          type: string
        soundVolume:
          type: integer
          format: int32
        originalVolume:
          type: integer
          format: int32
        startMillis:
          type: integer
          format: int64
        endMillis:
          type: integer
          format: int64
    BlueskyConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        postLanguages:
          type: array
          items:
            type: string
    ScheduledPostTwitterPoll:
      type: object
      properties:
        options:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledPostTwitterPollOption'
        settings:
          $ref: '#/components/schemas/ScheduledPostTwitterPollSettings'
    SaveLibraryPostStateRequest:
      required:
      - color
      - name
      type: object
      properties:
        name:
          maxLength: 20
          minLength: 0
          type: string
          description: Display name of the state (1-20 characters).
          example: In progress
        color:
          minLength: 1
          pattern: ^#([0-9a-fA-F]{6})$
          type: string
          description: 'Color of the state in #RRGGBB hex format.'
          example: '#4A90E2'
      description: Body to create or modify a library workflow state.
    LibraryPostPeopleTagDto:
      type: object
      properties:
        username:
          type: string
        x:
          type: number
          format: double
        y:
          type: number
          format: double
    LibraryPostMediaDto:
      required:
      - position
      type: object
      properties:
        id:
          type: integer
          format: int64
        position:
          type: integer
          format: int32
        url:
          type: string
        altText:
          type: string
        videoCoverMilliseconds:
          type: integer
          format: int32
        videoThumbnailUrl:
          type: string
    BulkUpdateLibraryPostStateResult:
      type: object
      properties:
        succeeded:
          type: array
          description: The posts now sitting in the target state, with their state resolved. Includes posts that were already in it.
          items:
            $ref: '#/components/schemas/LibraryPostDto'
        failures:
          type: array
          description: Ids that could not be moved, each with its reason. Empty when everything moved.
          items:
            $ref: '#/components/schemas/LibraryPostBulkStateFailure'
      description: Outcome of a bulk workflow state change, split into the posts that moved and the ids that could not.
    LibraryPostLocationDto:
      type: object
      properties:
        name:
          type: string
        link:
          type: string
        id:
          type: string
        locationCoordinates:
          $ref: '#/components/schemas/LibraryPostLocationCoordinates'
    ScheduledPostTwitterPollOption:
      type: object
      properties:
        text:
          type: string
    MoveLibraryPostStateRequest:
      required:
      - position
      type: object
      properties:
        position:
          minimum: 0
          type: integer
          description: 0-based target position among the brand's states.
          format: int32
          example: 1
      description: Body to move a workflow state to a new position.
    JsonOkResponseBulkUpdateLibraryPostStateResult:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/BulkUpdateLibraryPostStateResult'
    LibraryPostProductTagDto:
      type: object
      properties:
        productName:
          type: string
        productId:
          type: string
        x:
          type: number
          format: double
        y:
          type: number
          format: double
        catalogId:
          type: string
        position:
          type: integer
          format: int32
    UpdateLibraryPostStateRequest:
      type: object
      properties:
        stateId:
          type: integer
          description: Workflow state id to set; null (or omitted) to move the post to 'Sin asignar'.
          format: int64
          example: 123
      description: Body to set or clear the workflow state of a library post.
    LibraryPostNoteDto:
      required:
      - content
      - created
      - id
      - libraryPostId
      - userName
      type: object
      properties:
        id:
          type: integer
          format: int64
        libraryPostId:
          type: integer
          format: int64
        userId:
          type: integer
          format: int32
        agencyId:
          type: integer
          format: int32
        agencyUserId:
          type: integer
          format: int32
        userName:
          minLength: 1
          type: string
        created:
          $ref: '#/components/schemas/DateTimeInfo'
        content:
          minLength: 1
          type: string
        updatedDate:
          $ref: '#/components/schemas/DateTimeInfo'
        updated:
          type: boolean
        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. Filled for agency-authored notes too.
        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
    LibraryPostStateDto:
      type: object
      properties:
        id:
          type: integer
          description: State id.
          format: int64
          example: 123
        name:
          type: string
          description: Display name of the state.
        color:
          type: string
          description: Color of the state.
        position:
          type: integer
          description: Ordering position of the state within the brand's workflow (ascending).
          format: int32
          example: 0
      description: A workflow state of a library post.
    BulkUpdateLibraryPostStateRequest:
      required:
      - postIds
      type: object
      properties:
        postIds:
          maxItems: 500
          minItems: 0
          type: array
          description: Ids of the library posts to move. Must not be empty; duplicates are collapsed.
          items:
            type: integer
            description: Ids of the library posts to move. Must not be empty; duplicates are collapsed.
            format: int64
        stateId:
          type: integer
          description: Workflow state id to set on every post; null (or omitted) to move them to 'Sin asignar'.
          format: int64
          example: 123
      description: Body to set or clear the workflow state of several library posts at once.
    JsonOkResponseString:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: string
    PinterestConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        boardId:
          type: string
        pinTitle:
          type: string
        pinLink:
          type: string
        pinNewFormat:
          type: boolean
    JsonOkResponseLibraryPostDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/LibraryPostDto'
    FacebookConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        boostBudget:
          type: number
        boostPayer:
          type: string
        boostBeneficiary:
          type: string
        location:
          $ref: '#/components/schemas/LibraryPostLocationDto'
        type:
          type: string
        reelTitle:
          type: string
    SmartlinkData:
      type: object
      properties:
        targetUrl:
          type: string
        ids:
          type: array
          items:
            type: integer
            format: int32
    LinkedinOptionDto:
      type: object
      properties:
        text:
          type: string
    JsonOkListResponseLibraryPostStateDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/LibraryPostStateDto'
    GbpConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        type:
          type: string
    InstagramConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
        carouselTags:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/LibraryPostPeopleTagDto'
        carouselProductTags:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/LibraryPostProductTagDto'
        type:
          type: string
        showReelOnFeed:
          type: boolean
        isAiGenerated:
          type: boolean
          description: Whether the Instagram post is flagged as AI-generated content (sent as is_ai_generated on publish).
        boostBudget:
          type: number
        boostPayer:
          type: string
        boostBeneficiary:
          type: string
        location:
          $ref: '#/components/schemas/LibraryPostLocationDto'
        reelAudioName:
          type: string
        collaborators:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/InstagramCollaboratorTag'
        shareTrialAutomatically:
          type: boolean
        audioConfiguration:
          $ref: '#/components/schemas/InstagramAudioConfigurationDto'
    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
    LibraryPostDto:
      type: object
      properties:
        id:
          type: integer
          format: int64
        creationDate:
          $ref: '#/components/schemas/DateTimeInfo'
        updatedDate:
          $ref: '#/components/schemas/DateTimeInfo'
        shortener:
          type: boolean
        draft:
          type: boolean
        commonData:
          $ref: '#/components/schemas/LibraryPostCommonConfigurationDto'
        media:
          type: array
          items:
            $ref: '#/components/schemas/LibraryPostMediaDto'
        saveExternalMediaFiles:
          type: boolean
        parentId:
          type: integer
          format: int64
        twitterData:
          $ref: '#/components/schemas/TwitterConfigurationDto'
        facebookData:
          $ref: '#/components/schemas/FacebookConfigurationDto'
        instagramData:
          $ref: '#/components/schemas/InstagramConfigurationDto'
        threadsData:
          $ref: '#/components/schemas/ThreadsConfigurationDto'
        linkedinData:
          $ref: '#/components/schemas/LinkedinConfigurationDto'
        pinterestData:
          $ref: '#/components/schemas/PinterestConfigurationDto'
        tiktokData:
          $ref: '#/components/schemas/TikTokConfigurationDto'
        youtubeData:
          $ref: '#/components/schemas/YoutubeConfigurationDto'
        gbpData:
          $ref: '#/components/schemas/GbpConfigurationDto'
        blueskyData:
          $ref: '#/components/schemas/BlueskyConfigurationDto'
        descendants:
          type: array
          items:
            $ref: '#/components/schemas/LibraryPostDto'
        notes:
          type: array
          items:
            $ref: '#/components/schemas/LibraryPostNoteDto'
        hasNotReadNotes:
          type: boolean
        tags:
          type: string
        performanceDashboardIds:
          type: array
          items:
            type: integer
            format: int64
        assignee:
          $ref: '#/components/schemas/LibraryPostAssigneeDto'
        state:
          $ref: '#/components/schemas/LibraryPostStateDto'
    ThreadsConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: A boolean that represents if the Threads configuration is enabled for this library post
        allowedCountryCodes:
          uniqueItems: true
          type: array
          description: 'A string list of valid ISO 3166-1 alpha-2 country codes that represents the countries where this media should be shown. '
          items:
            type: string
            description: 'A string list of valid ISO 3166-1 alpha-2 country codes that represents the countries where this media should be shown. '
        replyControl:
          type: string
          description: A string that represents who can reply to a Threads post, been EVERYONE by default. (EVERYONE, ACCOUNTS_YOU_FOLLOW,MENTIONED_ONLY,PARENT_POST_AUTHOR_ONLY,FOLLOWERS_ONLY)
        type:
          type: string
          description: Post type (POST or GHOST)
        shareAsInstagramStory:
          type: boolean
          description: A boolean that represents if the Threads post must be cross-shared as an Instagram Story. The Story is published on the Instagram account linked to the Threads account, which may not match the Instagram account connected to this brand.
        instagramStoryTheme:
          type: string
          description: Theme used when the Threads post is cross-shared as an Instagram Story (LIGHT or DARK). Only allowed when shareAsInstagramStory is enabled; must be absent otherwise.
        isSpoiler:
          type: boolean
          description: A boolean that represents if isSpoiler is activated or not