postproxy-dev Placements API

openapi: 3.2.0
info:
  title: Postproxy Social Media Placements 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: Placements
  description: Account-wide placements and the profile serving each one
  externalDocs:
    url: https://postproxy.dev/reference/placements/
paths:
  /api/placements:
    get:
      operationId: placements_list
      summary: List placements (account-wide)
      description: Retrieves every placement on the account, across all platforms and profile groups, including which connected profile actively serves each one. Requires an account-wide API key (one not scoped to a profile group); a group-scoped key returns 422. Sandbox API keys list sandbox placements; live keys list live placements. Default per_page is 25 (maximum 100).
      tags:
      - Placements
      externalDocs:
        url: https://postproxy.dev/reference/placements/
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated list of placements
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedCollection'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Placement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: API key is scoped to a profile group — an account-wide key is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/placements/{id}/set_active_profile:
    patch:
      operationId: placements_set_active_profile
      summary: Set active profile
      description: Switches which connected profile serves the placement — posting and webhook traffic route through it from then on. The profile must be listed in the placement's linked_profiles and be connected. Switching an orphaned placement to a connected profile also fires the placement.restored webhook. Requires an account-wide API key; a group-scoped key returns 422.
      tags:
      - Placements
      externalDocs:
        url: https://postproxy.dev/reference/placements/
      parameters:
      - name: id
        in: path
        required: true
        description: Placement ID (the id from List placements, not the platform ID)
        schema:
          type: string
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profile_id
              properties:
                profile_id:
                  type: string
                  description: Profile to make active. Must be listed in the placement's linked_profiles and be connected.
      responses:
        '200':
          description: The updated placement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Profile cannot serve the placement (not linked, not connected, or in a different live/sandbox environment), or the API key is scoped to a profile group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  responses:
    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
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
        default: 10
    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
  schemas:
    Placement:
      type: object
      description: Account-wide placement record (Facebook Page, LinkedIn organization, Pinterest board, Telegram channel, Google Business location). One record exists per account, platform, and platform ID, even when several connected profiles can see it; exactly one linked profile is the active profile that posting and webhooks route through.
      properties:
        id:
          type: string
          description: Placement ID. Postproxy's own ID, used in placement URLs — not the platform ID.
        platform:
          type: string
          description: Platform the placement belongs to.
          enum:
          - facebook
          - linkedin
          - pinterest
          - telegram
          - google_business
        external_id:
          type: string
          description: Platform-specific ID — the value used as page_id / chat_id when creating posts, and returned as id by the per-profile List placements endpoint.
        name:
          type: string
          description: Placement name.
        avatar_url:
          type:
          - string
          - 'null'
          description: Stable Postproxy storage URL of the placement's picture, resized to 256x256 (Facebook Pages). null until it has been mirrored and for networks without one.
        status:
          type: string
          description: active (the active profile is connected), orphaned (the active profile is disconnected — posting is paused until you switch to a connected profile), or removed (access was revoked on the platform).
          enum:
          - active
          - orphaned
          - removed
        active_profile:
          $ref: '#/components/schemas/PlacementProfileRef'
          description: The profile posting routes through.
        linked_profiles:
          type: array
          description: Every profile that can see this placement — the candidates for Set active profile.
          items:
            $ref: '#/components/schemas/PlacementProfileRef'
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    PaginatedCollection:
      type: object
      description: Envelope for paginated list responses.
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        data:
          type: array
          items: {}
      required:
      - total
      - page
      - per_page
      - data
    PlacementProfileRef:
      type: object
      description: Compact profile reference on a placement.
      properties:
        id:
          type: string
          description: Profile ID.
        name:
          type: string
          description: Profile display name.
        connected:
          type: boolean
          description: Whether the profile is currently connected.
    BadRequestError:
      type: object
      properties:
        status:
          type: integer
          const: 400
        error:
          type: string
        message:
          type: string
  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/