postproxy-dev Queues API

openapi: 3.2.0
info:
  title: Postproxy Social Media Queues 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: Queues
  description: Posting queues with recurring timeslots and priority
  externalDocs:
    url: https://postproxy.dev/reference/queues/
paths:
  /api/post_queues:
    get:
      operationId: queues_list
      summary: List queues
      description: Retrieves all queues for the current account.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: List of queues
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Queue'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: queues_create
      summary: Create queue
      description: Creates a new posting queue connected to a profile group.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueCreateRequest'
      responses:
        '201':
          description: The created queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/post_queues/{id}:
    get:
      operationId: queues_get
      summary: Get queue
      description: Retrieves a single queue by its ID, including its weekly timeslot definitions.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - name: id
        in: path
        required: true
        description: Queue id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: The queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: queues_update
      summary: Update queue
      description: Updates a queue's settings, timeslots, or enabled state. Any changes to timezone or timeslots will trigger a rearrangement of all queued posts.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - name: id
        in: path
        required: true
        description: Queue id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueUpdateRequest'
      responses:
        '200':
          description: The updated queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      operationId: queues_delete
      summary: Delete queue
      description: Deletes a queue. Posts that were in the queue will have their queue reference removed but will not be deleted.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - name: id
        in: path
        required: true
        description: Queue id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Queue deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    examples:
                    - true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/post_queues/{id}/next_slot:
    get:
      operationId: queues_next_slot
      summary: Get next available timeslot
      description: Returns the next available timeslot for the queue.
      tags:
      - Queues
      externalDocs:
        url: https://postproxy.dev/reference/queues/
      parameters:
      - name: id
        in: path
        required: true
        description: Queue id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: Next available timeslot
          content:
            application/json:
              schema:
                type: object
                properties:
                  next_slot:
                    type: string
                    format: date-time
                    examples:
                    - '2026-03-11T14:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    QueueCreateRequest:
      type: object
      description: Request body for creating a queue.
      required:
      - profile_group_id
      - post_queue
      properties:
        profile_group_id:
          type: string
          description: Profile group ID to connect the queue to
        post_queue:
          type: object
          required:
          - name
          properties:
            name:
              type: string
              description: Queue name
            description:
              type: string
              description: Optional description
            timezone:
              type: string
              description: 'IANA timezone (default: UTC)'
              default: UTC
            jitter:
              type: integer
              description: 'Random offset in minutes (0-60, default: 0)'
              minimum: 0
              maximum: 60
              default: 0
            queue_timeslots_attributes:
              type: array
              description: Initial timeslots
              items:
                $ref: '#/components/schemas/QueueTimeslotInput'
    QueueTimeslot:
      type: object
      description: 'A weekly timeslot: a day of the week plus a time, interpreted in the queue''s timezone.'
      properties:
        id:
          type: integer
          description: Timeslot ID (used for deletion)
        day:
          type: integer
          description: 'Day of the week: 0=Sunday, 1=Monday, ..., 6=Saturday'
          minimum: 0
          maximum: 6
        time:
          type: string
          description: Time in 24-hour HH:MM format
    QueueUpdateRequest:
      type: object
      description: Request body for updating a queue. Any changes to timezone or timeslots trigger a rearrangement of all queued posts.
      properties:
        post_queue:
          type: object
          properties:
            name:
              type: string
              description: Queue name
            description:
              type: string
              description: Description
            timezone:
              type: string
              description: IANA timezone
            enabled:
              type: boolean
              description: Pause (false) or unpause (true) the queue
            jitter:
              type: integer
              description: Random offset in minutes (0-60)
              minimum: 0
              maximum: 60
            queue_timeslots_attributes:
              type: array
              description: 'Add timeslots (day + time) or remove them (id + _destroy: true)'
              items:
                $ref: '#/components/schemas/QueueTimeslotInput'
    Queue:
      type: object
      description: A posting queue that automatically schedules posts into recurring weekly timeslots, with priority-based ordering.
      properties:
        id:
          type: string
          description: Queue identifier (ID)
        name:
          type: string
          description: Queue name
        description:
          type:
          - string
          - 'null'
          description: Optional description
        timezone:
          type: string
          description: IANA timezone name (e.g. America/New_York)
        enabled:
          type: boolean
          description: Whether the queue is active. When paused (false), posts in the queue will not be published even if their scheduled time arrives
        jitter:
          type: integer
          description: 'Random offset in minutes (+/-) applied to scheduled times (0-60, default: 0)'
          minimum: 0
          maximum: 60
          default: 0
        profile_group_id:
          type: string
          description: Associated profile group (ID)
        timeslots:
          type: array
          description: Weekly timeslot definitions
          items:
            $ref: '#/components/schemas/QueueTimeslot'
        posts_count:
          type: integer
          description: Number of currently scheduled posts
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
      - errors
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    QueueTimeslotInput:
      type: object
      description: 'Timeslot attributes for create/update. To add, pass day and time; to remove, pass id and _destroy: true.'
      properties:
        id:
          type: integer
          description: Existing timeslot ID (required when removing)
        day:
          type: integer
          description: 'Day of the week: 0=Sunday through 6=Saturday'
          minimum: 0
          maximum: 6
        time:
          type: string
          description: Time in 24-hour HH:MM format
        _destroy:
          type: boolean
          description: Pass true together with id to remove the timeslot
    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
  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
  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/