Publer Competitors API

openapi: 3.1.1
info:
  title: Publer Competitors API
  description: 'The Publer API (v1) is a RESTful JSON interface for automating social media workflows
    - scheduling, publishing, media management and analytics - across Facebook, Instagram, X/Twitter,
    LinkedIn, TikTok, YouTube, Pinterest, Threads, Bluesky, Mastodon, Google Business Profiles, WordPress
    and Telegram. Authentication is an API key sent as `Authorization: Bearer-API YOUR_API_KEY` together
    with a `Publer-Workspace-Id` header. The API is available exclusively to Publer Business users.'
  termsOfService: https://publer.com/terms
  contact:
    name: Publer Support
    email: support@publer.com
    url: https://publer.com/docs
  version: 1.0.0
servers:
- url: https://app.publer.com/api/v1
security:
- BearerApiAuth: []
tags:
- name: Competitors
  description: Endpoints for retrieving competitors and analytics
paths:
  /competitors/{account_id}:
    get:
      summary: List Competitors
      description: Retrieves a list of competitor accounts for the workspace or for a specific social
        media account.
      tags:
      - Competitors
      parameters:
      - schema:
          type: string
        name: account_id
        in: path
        description: ID of the social media account to retrieve competitors for.
        required: false
      - schema:
          type: string
        name: Publer-Workspace-Id
        in: header
        description: ID of the workspace to retrieve competitors from
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    provider:
                      type: string
                      description: Social media provider (instagram, facebook, twitter, etc.)
                    name:
                      type: string
                      description: Display name of the competitor account
                    social_id:
                      type: string
                      description: Unique social media ID of the competitor
                    picture:
                      type: string
                      description: Profile picture URL of the competitor
                    type:
                      type: string
                      description: Type of account (user, page, etc.)
                    competitor_sync_in_queue:
                      type: boolean
                      description: Whether competitor sync is currently queued
                    username:
                      type: string
                      description: Username of the competitor (available for twitter, instagram, telegram,
                        mastodon)
                    verified:
                      type: boolean
                      description: Whether the account is verified (available for twitter, facebook)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Permission denied or missing required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403ErrorResponse'
      operationId: listCompetitors
  /competitors/{account_id}/analytics:
    get:
      summary: Get Competitors Analytics
      description: Retrieves analytics data for competitor accounts, including engagement metrics, follower
        counts, and post performance statistics.
      tags:
      - Competitors
      parameters:
      - schema:
          type: string
        name: Publer-Workspace-Id
        in: header
        description: ID of the workspace to retrieve competitors analytics from
        required: true
      - schema:
          type: string
        name: account_id
        in: query
        description: ID of the social media account to filter competitors analytics for
        required: false
      - schema:
          type: string
        name: competitor_id
        in: query
        description: Specific competitor account ID to analyze
        required: false
      - schema:
          type: string
        name: query
        in: query
        description: Search filter for competitor account names
        required: false
      - schema:
          type: string
          format: date
        name: from
        in: query
        description: Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)
        required: false
      - schema:
          type: string
          format: date
        name: to
        in: query
        description: End date for analytics data (ISO 8601 format, e.g., 2023-12-31)
        required: false
      - schema:
          type: integer
          minimum: 0
        name: page
        in: query
        description: 'Page number for pagination (default: 0)'
        required: false
      - schema:
          type: string
          enum:
          - followers
          - reach
          - engagement
          - posts_count
          - videos_count
          - photos_count
          - links_count
          - statuses_count
        name: sort_by
        in: query
        description: Field to sort results by
        required: false
      - schema:
          type: string
          enum:
          - asc
          - desc
        name: sort_type
        in: query
        description: Sort direction
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  insights:
                    type: array
                    description: Array of competitor analytics data
                    items:
                      type: object
                      properties:
                        account:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Competitor account ID
                            name:
                              type: string
                              description: Competitor account name
                            provider:
                              type: string
                              description: Social media provider
                            competitor_sync_in_queue:
                              type: boolean
                              description: Whether sync is in progress
                            picture:
                              type: string
                              description: Profile picture URL
                            my_account:
                              type: boolean
                              description: Whether this is the user's own account
                        followers:
                          type: integer
                          description: Current follower count
                        followers_growth:
                          type: integer
                          description: Follower growth during the period
                        engagement:
                          type: integer
                          description: Total engagement count
                        engagement_rate:
                          type: number
                          description: Engagement rate percentage (for Twitter)
                        reach:
                          type: integer
                          description: Total reach (not available for Instagram/Facebook)
                        posts_count:
                          type: integer
                          description: Total number of posts
                        videos_count:
                          type: integer
                          description: Number of video posts
                        photos_count:
                          type: integer
                          description: Number of photo posts
                        links_count:
                          type: integer
                          description: Number of link posts (not available for Instagram)
                        statuses_count:
                          type: integer
                          description: Number of status posts (not available for Instagram)
                  total:
                    type: integer
                    description: Total number of competitor accounts
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Permission denied - requires analytics access or paying subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403ErrorResponse'
        '422':
          description: Unprocessable entity - service error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
                    description: Error message from the service
      operationId: getCompetitorsAnalytics
components:
  schemas:
    401ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
    403ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: string
  securitySchemes:
    BearerApiAuth:
      type: apiKey
      name: Authorization
      in: header
      description: 'API key authentication. Format: "Bearer-API YOUR_API_KEY"'