Metricool Brands Api Service API

openapi: 3.2.0
info:
  title: Metricool Brands 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: Brands Api Service
paths:
  /v2/settings/brands:
    get:
      tags:
      - Brands Api Service
      summary: Returns a list of brands for the current user
      operationId: getBrands_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseBrandLite'
    post:
      tags:
      - Brands Api Service
      summary: Creates a brand, optionally already named and with its own image
      description: 'The multipart sibling of POST /v2/settings/brands. The request is multipart/form-data with four optional parts: ''brandLabel'', ''agencyId'', ''organizationId'' and a ''picture'' file part - the same picture contract as POST /v2/media and the profile-picture endpoints. ''organizationId'' (from GET /v2/organizations) creates the brand in that organization, under its owner''s account and brand limit; it requires manageBrands there and cannot be combined with ''agencyId''. Every part may be omitted, and omitting all of them creates the same empty brand the JSON variant creates. The image is validated and normalised server-side to an 80x80 PNG, centre-cropped, before the brand is created, so an invalid image creates nothing. Accepted formats PNG, JPEG and WebP, decided from the actual bytes. Maximum upload size 1 MB, and neither side of the source image may exceed 2000 pixels - both are rejections, not automatic downscales. Once the brand exists the image is best-effort: if storing it fails the brand is still created and the response carries no image URL. Without a name the brand shows as an empty brand until its first account is connected; without an image it falls back to the image derived from that account.'
      operationId: createBrandWithImage
      responses:
        '200':
          description: The created brand, with its image URL when the image was stored. Its brandRole is the caller's organization role when a team member creates it in another owner's organization, null when that role lacks editBrand (manageBrands alone creates the brand but gives no access to it), manager otherwise
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrandLite'
        '400':
          description: Not an image, unsupported format, over 1 MB, a side over 2000 px, a non-numeric 'agencyId', a non-numeric or non-positive 'organizationId', both 'agencyId' and 'organizationId' at once, or a brand label over 500 characters
        '401':
          description: Not authenticated
        '403':
          description: The account that would own the brand has reached its brand limit, the caller is not a member of the requested agency, or the caller cannot manage the brands of the requested organization, which is also the answer when it does not exist
  /v2/settings/brands/engagement-ratio:
    put:
      tags:
      - Brands Api Service
      operationId: saveEngagementRatioInAllMyManagedBrands
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EngagementRatioValue'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
      summary: Save engagement ratio in all my managed brands
      x-summary-source: derived
  /v2/settings/brands/ip-filters:
    get:
      tags:
      - Brands Api Service
      operationId: getIpFilters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseIpFiltersResponse'
      summary: Get ip filters
      x-summary-source: derived
    post:
      tags:
      - Brands Api Service
      operationId: postIpFilters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseIpFiltersResponse'
      summary: Post ip filters
      x-summary-source: derived
    delete:
      tags:
      - Brands Api Service
      operationId: deleteIpFilters
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseIpFiltersResponse'
      summary: Delete ip filters
      x-summary-source: derived
  /v2/settings/brands/{brand-id}:
    get:
      tags:
      - Brands Api Service
      operationId: getBrand
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrand'
      summary: Get brand
      x-summary-source: derived
    delete:
      tags:
      - Brands Api Service
      summary: Delete a brand
      description: 'Deletes the specified brand. If the brand is associated with a WhiteLabel Integrator, the agencyId must be provided in the request body. A team member whose organization role grants manageBrands may also delete a brand of that organization, with no extra field: the organization is the brand owner''s. A role with only editBrand cannot, and gets 404 like any other brand not its own. Additionally, an optional maxRecoveryDays (max 45 days) can be specified to set the recovery period for the deleted brand.'
      operationId: deleteBrand
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteBrandRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
    patch:
      tags:
      - Brands Api Service
      operationId: updateBrand
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Brand'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrand'
      summary: Update brand
      x-summary-source: derived
  /v2/settings/brands/{brand-id}/dashboard-config:
    get:
      tags:
      - Brands Api Service
      summary: Get the effective dashboard config for a brand (custom -> agency -> default)
      operationId: getDashboardConfig
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseDashboardConfigDto'
    patch:
      tags:
      - Brands Api Service
      summary: Update the dashboard config (logo, ...) for a brand.
      operationId: updateDashboardConfig
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DashboardConfigDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseDashboardConfigDto'
  /v2/settings/brands/{brand-id}/feed:
    get:
      tags:
      - Brands Api Service
      operationId: getBrandFeed
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrandFeed'
      summary: Get brand feed
      x-summary-source: derived
    put:
      tags:
      - Brands Api Service
      operationId: setBrandFeed
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandFeed'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrandFeed'
      summary: Set brand feed
      x-summary-source: derived
  /v2/settings/brands/{brand-id}/images:
    get:
      tags:
      - Brands Api Service
      operationId: fetchImage_1
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: provider
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Fetch image 1
      x-summary-source: derived
    delete:
      tags:
      - Brands Api Service
      operationId: deleteBrandImage
      parameters:
      - name: brand-id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
      summary: Delete brand image
      x-summary-source: derived
  /v2/settings/brands/{brand-id}/profile-picture:
    put:
      tags:
      - Brands Api Service
      summary: Sets or replaces the brand's custom image
      description: The request is multipart/form-data with a single file part named 'picture' — the same contract as POST /v2/media and the profile-picture endpoints. The image is validated and normalised server-side to an 80x80 PNG, centre-cropped; there is no manual crop. The change is applied immediately and the previous image is deleted from the serving bucket, so it is no longer retrievable through the API. Accepted formats PNG, JPEG and WebP, decided from the actual bytes. Maximum upload size 1 MB, and neither side of the source image may exceed 2000 pixels — both are rejections, not automatic downscales. A custom image takes precedence over the image derived from the brand's connected networks.
      operationId: setBrandImage
      parameters:
      - name: brand-id
        in: path
        description: Id of the brand whose image is being set
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The updated brand, including the new image URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBrand'
        '400':
          description: Missing 'picture' file part, not an image, unsupported format, over 1 MB, a side over 2000 px, or brand-id does not match the request's brand
        '401':
          description: Not authenticated
        '403':
          description: Caller lacks EDIT_BRAND on this brand
        '409':
          description: Another image change for this brand is in progress
        '415':
          description: Declared content type is not multipart/form-data
components:
  schemas:
    JsonOkResponseBrandLite:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/BrandLite'
    BrandLite:
      type: object
      properties:
        id:
          type: integer
          format: int32
        userId:
          type: integer
          format: int32
        ownerUserId:
          type: integer
          format: int32
        label:
          type: string
        title:
          type: string
        description:
          type: string
        image:
          type: string
        ownerUsername:
          type: string
        hash:
          type: string
        joinDate:
          $ref: '#/components/schemas/DateTimeInfo'
        firstConnectionDate:
          $ref: '#/components/schemas/DateTimeInfo'
        timezone:
          type: string
        brandRole:
          $ref: '#/components/schemas/BrandRole'
        engagementRatio:
          type: integer
          format: int32
        networksData:
          $ref: '#/components/schemas/NetworksData'
        isShared:
          type: boolean
      description: Brands the user will lose after the downgrade
    OrganizationRoleActionsDto:
      type: object
      properties:
        manageBrands:
          type: boolean
          description: Whether the role can create and manage brands at the organization level.
        manageRoles:
          type: boolean
          description: Whether the role can create and manage other brand roles at the organization level.
        manageTeamMembers:
          type: boolean
          description: Whether the role can manage team members at the organization level.
        manageAgencyConfig:
          type: boolean
          description: Whether the role can manage the agency configuration.
        manageAgencyClients:
          type: boolean
          description: Whether the role can manage agency clients.
      description: Organization-level permissions granted by a brand role, on top of the per-brand actions. Never null in a read response - a role that never had organization permissions set is reported with every field false.
    BrandRole:
      required:
      - actions
      - name
      - organizationActions
      - userId
      type: object
      properties:
        id:
          type: integer
          format: int64
        userId:
          type: integer
          format: int32
        name:
          minLength: 1
          type: string
        description:
          type: string
        color:
          type: string
        type:
          type: string
        assignable:
          type: boolean
        teamMemberOnly:
          type: boolean
        deletedDate:
          $ref: '#/components/schemas/DateTimeInfo'
        deleted:
          type: boolean
        actions:
          $ref: '#/components/schemas/BrandRoleActions'
        organizationActions:
          $ref: '#/components/schemas/OrganizationRoleActionsDto'
        assignedUsersCount:
          type: integer
          format: int32
        assignedEnabledCount:
          type: integer
          format: int32
        assignedDisabledCount:
          type: integer
          format: int32
    JsonOkResponseBoolean:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: boolean
    Colors:
      type: object
      properties:
        blue:
          type: string
        teal:
          type: string
        pink:
          type: string
        yellow:
          type: string
        purple:
          type: string
        cyan:
          type: string
        red:
          type: string
        green:
          type: string
        slate:
          type: string
        charcoal:
          type: string
        lightYellow:
          type: string
        darkYellow:
          type: string
        cobalt:
          type: string
    BrandProperties:
      type: object
      properties:
        customEmail:
          type: string
        additionalNotificationAddresses:
          uniqueItems: true
          type: array
          items:
            type: string
        colors:
          $ref: '#/components/schemas/Colors'
        trialExcluded:
          type: string
        engagementRatio:
          type: integer
          format: int32
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    NetworksData:
      type: object
      properties:
        webData:
          type: string
        facebookData:
          type: string
        instagramData:
          type: string
        threadsData:
          type: string
        blueskyData:
          type: string
        twitterData:
          type: string
        linkedinData:
          type: string
        pinterestData:
          type: string
        tiktokData:
          type: string
        gbpData:
          type: string
        youtubeData:
          type: string
        twitchData:
          type: string
        facebookAdsData:
          type: string
        googleAdsData:
          type: string
        tiktokAdsData:
          type: string
    DashboardConfigDto:
      type: object
      properties:
        logo:
          type: string
        defaultLogo:
          type: boolean
    DeleteBrandRequest:
      type: object
      properties:
        maxRecoveryDays:
          type: integer
          description: Max recovery days for the deleted brand (max 45 days)
          format: int32
        agencyId:
          type: integer
          description: Brand agency id (if the brand belongs to an agency)
          format: int32
      description: Request to delete a brand
    IpFiltersResponse:
      type: object
      properties:
        ip:
          type: string
        filtered:
          type: boolean
    BrandFeed:
      type: object
      properties:
        feedUrl:
          type: string
    WhiteLabelData:
      type: object
      properties:
        whiteLabelLink:
          type: string
        analyticModeWhitelabelLink:
          type: string
        whiteLabelAlias:
          type: string
        isWhiteLabel:
          type: boolean
        isWhiteLabelOnlyRead:
          type: boolean
    JsonOkListResponseBrandLite:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BrandLite'
    JsonOkResponseDashboardConfigDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/DashboardConfigDto'
    JsonOkResponseBrandFeed:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/BrandFeed'
    EngagementRatioValue:
      required:
      - value
      type: object
      properties:
        value:
          type: integer
          format: int32
    JsonOkResponseBrand:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/Brand'
    Brand:
      type: object
      properties:
        id:
          type: integer
          format: int32
        userId:
          type: integer
          format: int32
        ownerUserId:
          type: integer
          format: int32
        label:
          type: string
        title:
          type: string
        description:
          type: string
        image:
          type: string
        imageSource:
          type: string
          description: Where the image the brand renders comes from. Always present on a brand response.
          enum:
          - CUSTOM
          - NETWORK
          - DEFAULT
        networksData:
          $ref: '#/components/schemas/NetworksData'
        isShared:
          type: boolean
        ownerUsername:
          type: string
        whiteLabelData:
          $ref: '#/components/schemas/WhiteLabelData'
        hash:
          type: string
        version:
          type: integer
          format: int64
        deleteDate:
          $ref: '#/components/schemas/DateTimeInfo'
        deleted:
          type: boolean
        joinDate:
          $ref: '#/components/schemas/DateTimeInfo'
        firstConnectionDate:
          $ref: '#/components/schemas/DateTimeInfo'
        lastResolvedInboxMessageTimestamp:
          type: integer
          format: int64
        lastReadInboxMessageTimestamp:
          type: integer
          format: int64
        timezone:
          type: string
        availableConnectors:
          type: array
          items:
            type: string
        brandRole:
          $ref: '#/components/schemas/BrandRole'
        isDemo:
          type: boolean
        properties:
          $ref: '#/components/schemas/BrandProperties'
    BrandRoleActions:
      type: object
      properties:
        viewAnalytics:
          type: boolean
        viewInbox:
          type: boolean
        viewPlanner:
          type: boolean
        viewAds:
          type: boolean
        viewSmartlinks:
          type: boolean
        fullAccessReports:
          type: boolean
        fullAccessInbox:
          type: boolean
        fullAccessPlanner:
          type: boolean
        fullAccessAds:
          type: boolean
        fullAccessSmartlinks:
          type: boolean
        fullAccessHashtagTracker:
          type: boolean
        editBrand:
          type: boolean
        schedulePosts:
          type: boolean
        publishPosts:
          type: boolean
        approvePosts:
          type: boolean
        viewCondensedAnalytics:
          type: boolean
        fullAccessDashboards:
          type: boolean
        viewDashboards:
          type: boolean
        editFlow:
          type: boolean
        viewFlow:
          type: boolean
        fullAccessStudio:
          type: boolean
    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
    JsonOkResponseIpFiltersResponse:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/IpFiltersResponse'