postproxy-dev Profile Groups API

openapi: 3.2.0
info:
  title: Postproxy Social Media Profile Groups 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 Groups
  description: Workspaces for profiles, credentials, and access scope
  externalDocs:
    url: https://postproxy.dev/reference/profile-groups/
paths:
  /api/profile_groups:
    get:
      operationId: profile_groups_list
      summary: List profile groups
      description: Retrieves all profile groups accessible with your API key. Full-account keys return every group; profile-group-scoped keys return only the scoped group.
      tags:
      - Profile Groups
      externalDocs:
        url: https://postproxy.dev/reference/profile-groups/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: List of profile groups
          content:
            application/json:
              schema:
                type: object
                description: List of Profile Group objects accessible with the API key.
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: profile_groups_create
      summary: Create profile group
      description: Creates a new profile group. Requires a full account access API key - profile group scoped API keys cannot create new profile groups.
      tags:
      - Profile Groups
      externalDocs:
        url: https://postproxy.dev/reference/profile-groups/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profile_group
              properties:
                profile_group:
                  type: object
                  required:
                  - name
                  properties:
                    name:
                      type: string
                      description: Name for the new profile group.
      responses:
        '201':
          description: Profile group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/profile_groups/{id}:
    get:
      operationId: profile_groups_get
      summary: Get profile group
      description: Retrieves a single profile group by its ID.
      tags:
      - Profile Groups
      externalDocs:
        url: https://postproxy.dev/reference/profile-groups/
      parameters:
      - name: id
        in: path
        required: true
        description: Profile group id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: The profile group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: profile_groups_delete
      summary: Delete profile group
      description: Deletes a profile group and all its associated profiles. Requires a full account access API key.
      tags:
      - Profile Groups
      externalDocs:
        url: https://postproxy.dev/reference/profile-groups/
      parameters:
      - name: id
        in: path
        required: true
        description: Profile group id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Profile group deleted
          content:
            application/json:
              schema:
                type: object
                description: Deletion result.
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/profile_groups/{id}/initialize_connection:
    post:
      operationId: profile_groups_initialize_connection
      summary: Initialize connection
      description: Generates a URL to connect a new social media profile to a profile group via OAuth. Bluesky uses an app-password flow and Telegram uses a bring-your-own-bot flow; both authenticate synchronously and create the profile in one call.
      tags:
      - Profile Groups
      externalDocs:
        url: https://postproxy.dev/reference/profile-groups/
      parameters:
      - name: id
        in: path
        required: true
        description: Profile group id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Connection payload. OAuth platforms require redirect_url; bluesky requires identifier and app_password instead; telegram requires bot_token instead. instagram and whatsapp accept the optional onboarding parameter.
              required:
              - platform
              properties:
                platform:
                  type: string
                  description: Platform to connect.
                  enum:
                  - facebook
                  - instagram
                  - tiktok
                  - linkedin
                  - youtube
                  - twitter
                  - threads
                  - pinterest
                  - bluesky
                  - telegram
                  - whatsapp
                redirect_url:
                  type: string
                  description: URL to redirect to after OAuth completes. Required for all platforms except bluesky and telegram.
                refresh_connection:
                  type: boolean
                  description: 'Re-authorize a profile already connected to this group, to renew tokens or re-pick pages. Skips the already-connected check for that platform: the same account is updated in place, a different account is still rejected with account_is_already_connected.'
                identifier:
                  type: string
                  description: Bluesky handle (e.g. yourname.bsky.social). Required for bluesky. The .bsky.social suffix is added automatically if missing; custom domains are accepted as-is.
                app_password:
                  type: string
                  description: Bluesky app password, not the account password. Required for bluesky. Generate at https://bsky.app/settings/app-passwords.
                bot_token:
                  type: string
                  description: Telegram bot token from @BotFather. Required for telegram.
                onboarding:
                  type: string
                  description: 'Optional, whatsapp and instagram only. instagram: which login to use — "instagram" (default) for Instagram Login, or "facebook" for Facebook Login, for an account linked to a Facebook Page the user manages. whatsapp: where the number lives — "business_app" for coexistence with the WhatsApp Business app, or "api" for a number already on the Cloud API or a fresh API-only number. Omit it and the connect page asks the user.'
                  enum:
                  - instagram
                  - facebook
                  - business_app
                  - api
      responses:
        '200':
          description: Connection URL (OAuth platforms) or the created profile (bluesky, telegram)
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: 'OAuth platforms: URL to redirect the user to.'
                  properties:
                    url:
                      type: string
                      description: URL to redirect the user to for OAuth authentication.
                    success:
                      type: boolean
                      description: Whether the invitation was created successfully.
                - type: object
                  description: 'Bluesky and Telegram: the profile is created synchronously in one call.'
                  properties:
                    success:
                      type: boolean
                    profile:
                      type: object
                      properties:
                        id:
                          type: string
                        network:
                          type: string
                        name:
                          type: string
                        external_username:
                          type: string
                    next_step:
                      type: string
                      description: 'Telegram only: instructions for adding the bot as administrator to channels.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrors'
    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:
    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
  schemas:
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
      - errors
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    ProfileGroup:
      type: object
      description: An organizational container that groups related social media profiles together.
      properties:
        id:
          type: string
          description: Unique profile group identifier (id).
        name:
          type: string
          description: Display name of the profile group.
        profiles_count:
          type: integer
          description: Number of connected profiles in this group.
  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/