postproxy-dev Instagram API

openapi: 3.2.0
info:
  title: Postproxy Social Media Instagram 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: Instagram
  description: Search Instagram's audio library for music and original sounds to attach to reels, and list, accept or decline incoming collaboration invites (Facebook-login profiles)
  externalDocs:
    url: https://postproxy.dev/reference/platforms/instagram/#reel-audio
paths:
  /api/profiles/{profile_id}/instagram/available_audio:
    get:
      operationId: ig_available_audio
      summary: List available audio
      description: 'Searches the music and original sounds a reel can use as its soundtrack. Pass the chosen audio_id as an Instagram reel parameter on POST /api/posts. Items keep Meta''s field names: display_artist and cover_artwork_thumbnail_uri appear on music only, ig_username and profile_picture_url on original_sound only, and download_url is a temporary preview link that expires after about 1.5 days. Instagram returns only audio cleared for third-party use. Requires an Instagram profile connected through Facebook login; Instagram-login profiles return 422.'
      tags:
      - Instagram
      externalDocs:
        url: https://postproxy.dev/reference/platforms/instagram/#available-audio
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile id (must be an instagram profile connected via Facebook login)
        schema:
          type: string
      - name: audio_type
        in: query
        required: false
        description: Which library to search
        schema:
          type: string
          enum:
          - music
          - original_sound
          default: music
      - name: search_query
        in: query
        required: false
        description: Search term. Without one, Instagram returns trending audio
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: Matching audio tracks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      description: Audio track, with Meta's own field names passed through.
                      properties:
                        audio_id:
                          type: string
                          description: Pass this as the Instagram reel audio_id when publishing.
                        audio_type:
                          type: string
                          enum:
                          - music
                          - original_sound
                        title:
                          type: string
                        display_artist:
                          type: string
                          description: music only.
                        duration_in_ms:
                          type: integer
                        cover_artwork_thumbnail_uri:
                          type: string
                          description: music only.
                        ig_username:
                          type: string
                          description: original_sound only.
                        profile_picture_url:
                          type: string
                          description: original_sound only.
                        is_ads_eligible:
                          type: boolean
                        on_platform_audio_preview_link:
                          type: string
                          description: Instagram page for the audio.
                        download_url:
                          type: string
                          description: Temporary preview link; expires after about 1.5 days.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The connection lacks permission to read the audio library
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Instagram did not accept the connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/profiles/{profile_id}/instagram/collaboration_invites:
    get:
      operationId: ig_collaboration_invites_list
      summary: List collaboration invites
      description: Lists posts from other accounts that invited this profile as a collaborator. Requires an Instagram profile connected through Facebook login; Instagram-login profiles return 422.
      tags:
      - Instagram
      externalDocs:
        url: https://postproxy.dev/reference/platforms/instagram/#list-invites
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile id (must be an instagram profile connected via Facebook login)
        schema:
          type: string
      - name: after
        in: query
        required: false
        description: next_cursor from the previous page
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: A page of invites
          content:
            application/json:
              schema:
                type: object
                properties:
                  collaboration_invites:
                    type: array
                    items:
                      type: object
                      properties:
                        media_id:
                          type: string
                          description: Instagram media ID of the post you were invited to
                        media_owner_username:
                          type: string
                        caption:
                          type: string
                        media_url:
                          type: string
                          description: Omitted by Instagram for videos with copyrighted or licensed audio
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: null on the last page
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The connection lacks permission for collaboration invites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Instagram did not accept the connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/profiles/{profile_id}/instagram/accept_collaboration_invite:
    post:
      operationId: ig_collaboration_invite_accept
      summary: Accept collaboration invite
      description: Accepts an incoming collaboration invite by media_id. Requires an Instagram profile connected through Facebook login; Instagram-login profiles return 422.
      tags:
      - Instagram
      externalDocs:
        url: https://postproxy.dev/reference/platforms/instagram/#accept-or-decline-an-invite
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile id (must be an instagram profile connected via Facebook login)
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - media_id
              properties:
                media_id:
                  type: string
                  description: media_id from List collaboration invites
      responses:
        '200':
          description: The invite was accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: boolean
                  media_id:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The connection lacks permission for collaboration invites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Instagram did not accept the connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/profiles/{profile_id}/instagram/decline_collaboration_invite:
    post:
      operationId: ig_collaboration_invite_decline
      summary: Decline collaboration invite
      description: Declines an incoming collaboration invite by media_id. Requires an Instagram profile connected through Facebook login; Instagram-login profiles return 422.
      tags:
      - Instagram
      externalDocs:
        url: https://postproxy.dev/reference/platforms/instagram/#accept-or-decline-an-invite
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile id (must be an instagram profile connected via Facebook login)
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - media_id
              properties:
                media_id:
                  type: string
                  description: media_id from List collaboration invites
      responses:
        '200':
          description: The invite was declined
          content:
            application/json:
              schema:
                type: object
                properties:
                  declined:
                    type: boolean
                  media_id:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The connection lacks permission for collaboration invites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Instagram did not accept the connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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
    RateLimited:
      description: Posting rate limit reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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
    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/