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"'