Metricool Organization Api Service API

openapi: 3.2.0
info:
  title: Metricool Organization 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: Organization Api Service
paths:
  /v2/organizations:
    get:
      tags:
      - Organization Api Service
      summary: List the organizations the caller may act on
      description: The caller's own organization, if it exists, every one they are a team member of, and every one with a brand they edit as a collaborator (type COLLABORATOR). Organizations whose owner has the organization permissions feature disabled or no Advanced-or-higher plan are left out. Each one carries its owner's name (or email) and profile picture, as GET /v2/settings/organizations does. Unlike that endpoint, this never creates the caller's own organization.
      operationId: getAccessibleOrganizations
      responses:
        '200':
          description: Organizations retrieved, possibly none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkListResponseAccessibleOrganizationDto'
        '403':
          description: Caller is not a regular-user session.
  /v2/settings/organizations:
    get:
      tags:
      - Organization Api Service
      summary: Get the caller's own organization settings (id, display name and owner).
      operationId: getOrganization
      responses:
        '200':
          description: Organization id, name and owner resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseOrganizationDto'
        '403':
          description: Caller is not a regular-user owner session, or does not have an Advanced-or-higher plan.
    put:
      tags:
      - Organization Api Service
      summary: Rename the caller's own organization.
      operationId: renameOrganization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationNameRequest'
        required: true
      responses:
        '200':
          description: Organization renamed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseOrganizationDto'
        '400':
          description: Invalid (blank or too long) name.
        '403':
          description: Caller is not a regular-user owner session, or does not have an Advanced-or-higher plan.
components:
  schemas:
    UpdateOrganizationNameRequest:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          type: string
          description: New display name for the organization.
          example: Acme Corp
      description: Request body to rename an organization.
    OrganizationDto:
      type: object
      properties:
        id:
          type: integer
          description: Id of the organization. Always present -- the row is created on first access if the owner never personalized it. Use it to address /v2/organizations/{organizationId} endpoints (e.g. team members).
          format: int64
          example: 42
        name:
          type:
          - string
          - 'null'
          description: 'Display name of the organization: the personalized name if the owner set one, otherwise the owner''s billing company. Null when there is neither: the front shows its own default.'
          example: Acme Corp
        owner:
          $ref: '#/components/schemas/OrganizationOwnerDto'
      description: An account's organization settings.
    AccessibleOrganizationDto:
      type: object
      properties:
        id:
          type: integer
          description: Id of the organization, to address /v2/organizations/{organizationId} endpoints or to create a brand in it.
          format: int64
          example: 42
        ownerId:
          type: integer
          description: User id of the organization owner. Brands of GET /api/admin/simpleProfiles or GET /v2/settings/brands whose userId equals it belong to this organization.
          format: int32
          example: 1234
        name:
          type:
          - string
          - 'null'
          description: 'Display name of the organization: the personalized name if the owner set one, otherwise the owner''s billing company. Null when there is neither: the front shows its own default.'
          example: Acme Corp
        type:
          type: string
          description: 'How the caller reaches this organization. OWNER: they own it and hold every permission. TEAM_MEMBER: with the permissions of role. COLLABORATOR: they edit some of its brands as a collaborator, with no organization permission; only its collaborators, brands and roles endpoints let them in, on the brands they edit.'
          example: TEAM_MEMBER
          enum:
          - OWNER
          - TEAM_MEMBER
          - COLLABORATOR
        isOwner:
          type: boolean
          description: 'Whether the caller owns this organization: type is OWNER. Use type instead.'
          example: false
          deprecated: true
        hasAgency:
          type: boolean
          description: Whether the owner of this organization has an agency. Only then do the agency permissions of a role (organizationActions.manageAgencyConfig and manageAgencyClients) apply to it. Always false for type COLLABORATOR, which holds no role.
          example: false
        role:
          $ref: '#/components/schemas/BrandRole'
        owner:
          $ref: '#/components/schemas/OrganizationOwnerDto'
      description: 'An organization the caller may act on: their own, one they are a team member of, or one whose brands they edit as a collaborator.'
    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.
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    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
    JsonOkListResponseAccessibleOrganizationDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/AccessibleOrganizationDto'
    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
    OrganizationOwnerDto:
      type: object
      properties:
        name:
          type: string
          description: First name and last name of the owner, or their email when they have no first name.
          example: Ana García
        profilePicture:
          type:
          - string
          - 'null'
          description: URL of the owner's profile picture. Null when they have none, and the front shows their initials instead.
          example: https://cdn.metricool.com/avatars/1234.png
      description: The owner of an organization.
    JsonOkResponseOrganizationDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/OrganizationDto'