postproxy-dev Profile Comments API

openapi: 3.2.0
info:
  title: Postproxy Social Media Profile Comments API
  version: '2026-09-21'
  summary: Unified social media API for publishing, comments, direct messages, and reviews.
  description: 'The Postproxy API lets you programmatically create and manage social media posts across Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), Threads, Pinterest, Bluesky, Telegram, and Google Business. Beyond publishing you can read and reply to comments, read and send direct messages, and reply to Google Business reviews and Facebook Page recommendations.


    Send one payload; Postproxy maps it to each platform''s rules and returns a per-platform outcome. Sandbox mode is included on all plans for development without real accounts.


    Human-readable reference: https://postproxy.dev/reference/overview/


    ## Versioning and deprecation


    The API has a single stable version served at https://api.postproxy.dev/api. Releases are identified by this document''s date-based `info.version`. Changes are additive: new endpoints, new optional parameters, and new response fields may appear, and clients should ignore fields they do not recognize. Existing fields, parameters, and status codes are not changed or removed without a deprecation cycle.


    When an endpoint or field is deprecated it is marked `deprecated: true` in this specification and announced in the changelog (https://postproxy.dev/getting-started/changelog/) at least 90 days before removal.'
  termsOfService: https://postproxy.dev/terms-conditions/
  contact:
    name: Postproxy Support
    url: https://postproxy.dev/developers/
    email: support@postproxy.dev
  x-versioning:
    strategy: stable-single-version
    spec-version-format: date (YYYY-MM-DD)
    compatibility: additive-only; breaking changes go through a deprecation cycle
    deprecation-signal: 'deprecated: true in this spec, plus a changelog announcement at least 90 days before removal'
    changelog: https://postproxy.dev/getting-started/changelog/
servers:
- url: https://api.postproxy.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Profile Comments
  description: Profile-scoped comments (Google Business reviews, Facebook Page recommendations)
  externalDocs:
    url: https://postproxy.dev/reference/profile-comments/
paths:
  /api/profiles/{profile_id}/comments:
    parameters:
    - name: profile_id
      in: path
      required: true
      schema:
        type: string
      description: Profile ID (hashid)
    get:
      operationId: profile_comments_list
      summary: List profile comments
      description: Retrieves a paginated list of top-level profile-scoped comments (Google Business Profile reviews and Facebook Page recommendations). Each top-level comment includes a replies array containing all nested replies sorted by created_at ascending; results are sorted by posted_at descending.
      tags:
      - Profile Comments
      externalDocs:
        url: https://postproxy.dev/reference/profile-comments/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - name: placement_id
        in: query
        required: false
        schema:
          type: string
        description: Filter to comments on a single location (the accounts/X/locations/Y path returned by List Placements). Without it, comments from all locations are returned, interleaved by posted_at.
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: 'Paginated list of top-level comments, each with a replies array. Pagination applies to top-level comments only. Google Business reviews can be star-only: body is null while platform_data.star_rating is populated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileCommentListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: profile_comments_create
      summary: Reply to a profile comment
      description: Creates a reply to an existing review. The reply is stored immediately with status pending and external_id null; it is then published to the platform. Top-level comments cannot be created — the request returns 422 if parent_id is missing.
      tags:
      - Profile Comments
      externalDocs:
        url: https://postproxy.dev/reference/profile-comments/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileCommentCreateRequest'
      responses:
        '201':
          description: Reply created with status pending and external_id null; published asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileComment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/profiles/{profile_id}/comments/{id}:
    parameters:
    - name: profile_id
      in: path
      required: true
      schema:
        type: string
      description: Profile ID
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Comment ID — accepts either the Postproxy hashid or the platform's native resource path (e.g. accounts/1234/locations/5678/reviews/AbFvOq)
    get:
      operationId: profile_comments_get
      summary: Get profile comment
      description: Retrieves a single profile-scoped comment with its direct replies.
      tags:
      - Profile Comments
      externalDocs:
        url: https://postproxy.dev/reference/profile-comments/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: The comment with its replies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileComment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: profile_comments_delete
      summary: Delete profile comment reply
      description: Deletes your reply to a review. The Google Business API does not let businesses delete reviews themselves — the original review stays.
      tags:
      - Profile Comments
      externalDocs:
        url: https://postproxy.dev/reference/profile-comments/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Deletion accepted for asynchronous processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
components:
  schemas:
    ProfileCommentListResponse:
      type: object
      description: Paginated list of top-level profile comments.
      properties:
        total:
          type: integer
          description: Total number of top-level comments
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Items per page
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProfileComment'
          description: Array of top-level comment objects, each with a replies array
    ProfileComment:
      type: object
      description: A profile-scoped comment — a Google Business Profile review, a Facebook Page recommendation, or a reply to one.
      properties:
        id:
          type: string
          description: Postproxy comment ID (hashid)
        external_id:
          type:
          - string
          - 'null'
          description: Platform's native resource ID (null while a reply is pending publication)
        parent_external_id:
          type:
          - string
          - 'null'
          description: External ID of parent review (null for top-level reviews)
        placement_id:
          type: string
          description: Location path (e.g. accounts/X/locations/Y)
        body:
          type:
          - string
          - 'null'
          description: 'Comment/review text. Google Business reviews can be star-only: body is null while platform_data.star_rating is still populated.'
        status:
          type: string
          enum:
          - synced
          - pending
          - published
          - failed
          - failed_waiting_for_retry
          - deleted
        error:
          type:
          - string
          - 'null'
          description: Error summary if an outgoing reply failed (null otherwise)
        error_details:
          $ref: '#/components/schemas/PlatformErrorDetails'
        author_username:
          type:
          - string
          - 'null'
          description: Display name of reviewer (null for your own replies)
        author_avatar_url:
          type:
          - string
          - 'null'
          description: Profile image URL
        platform_data:
          type:
          - object
          - 'null'
          description: Platform-specific metadata (e.g. star_rating, update_time for Google reviews; recommendation_type for Facebook recommendations)
          additionalProperties: true
        permalink:
          type:
          - string
          - 'null'
          description: URL to the comment on the platform (the location's reviews page on Google or the Page's reviews tab on Facebook — shared by all reviews and replies on that location / Page; null if unavailable)
        posted_at:
          type:
          - string
          - 'null'
          description: ISO 8601 timestamp of platform posting
        created_at:
          type: string
          description: ISO 8601 timestamp of record creation
        replies:
          type: array
          items:
            $ref: '#/components/schemas/ProfileComment'
          description: Nested replies to this comment, sorted by created_at ascending (present on list/get responses)
    ProfileCommentCreateRequest:
      type: object
      description: Payload for replying to an existing review. Top-level comments cannot be authored — parent_id is required.
      required:
      - parent_id
      - body
      properties:
        parent_id:
          type: string
          description: Postproxy ID or external ID of the review being replied to
        body:
          type: string
          description: Reply body. (The legacy text parameter is still accepted as an alias.)
    PlatformErrorDetails:
      type:
      - object
      - 'null'
      description: Structured platform error (omitted when no platform error info is available).
      properties:
        platform_error_code:
          type:
          - string
          - 'null'
          description: Error code returned by the platform API
        platform_error_subcode:
          type:
          - string
          - 'null'
          description: Error subcode returned by the platform API
        platform_error_message:
          type:
          - string
          - 'null'
          description: Error message returned by the platform API
        postproxy_note:
          type:
          - string
          - 'null'
          description: Additional context from Postproxy about the error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
      - errors
    BadRequestError:
      type: object
      properties:
        status:
          type: integer
          const: 400
        error:
          type: string
        message:
          type: string
  responses:
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrors'
    NotFound:
      description: Resource does not exist or is not accessible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              value:
                error: Not found
    BadRequest:
      description: Missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Unauthorized:
      description: Invalid, missing, or insufficient API key permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidKey:
              value:
                error: Invalid API key
    MethodNotAllowed:
      description: Unsupported method for this platform or resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
        default: 10
    ProfileGroupId:
      name: profile_group_id
      in: query
      required: false
      description: Profile group context for the request. Optional when the API key is scoped to a profile group (that group is used automatically); with a full-access key, defaults to the first profile group in the account.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional idempotency key (up to 255 characters; a UUID is ideal). Retrying a successful write with the same key replays the original response (with an Idempotent-Replay: true header) instead of executing again. Stored responses are kept for 24 hours; only 2xx responses are stored.'
      schema:
        type: string
        maxLength: 255
    Page:
      name: page
      in: query
      required: false
      description: Page number (1-based). Passing 0 returns page 1.
      schema:
        type: integer
        default: 1
        minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key sent as a Bearer token in the Authorization header. Keys are either full-access (entire account) or scoped to a single profile group. Create keys at https://app.postproxy.dev under Settings → API Keys.
externalDocs:
  description: Full API reference
  url: https://postproxy.dev/reference/overview/