postzen-dev Queues API

openapi: 3.2.0
info:
  title: PostZen Public Queues API
  version: 1.0.0
  description: The PostZen Public API lets server-side integrations manage profiles, connected social accounts, OAuth connection flows, media uploads, post creation, and outbound webhooks.
servers:
- url: https://api.postzen.dev
  description: Production API
security:
- bearerAuth: []
tags:
- name: Queues
  description: Manage per-profile posting queues. A queue is a named weekly schedule (`slots` of `{ dayOfWeek, time }`) evaluated in the queue's own timezone. A profile may hold several queues and exactly one is the default. Creating a post with `queuedFromProfile` claims the next free slot inside a single transaction, which is what keeps concurrent creates from landing on the same instant.
paths:
  /v1/queue/slots:
    get:
      tags:
      - Queues
      operationId: listQueueSlots
      summary: Get a queue schedule
      description: Returns the queue selected by `queueId`, or the profile's default queue when `queueId` is omitted. With `all=true` every queue on the profile is returned instead. `nextSlots` holds the next five instants the queue would hand out, already skipping occupied slots; a paused or slotless queue returns an empty array.
      parameters:
      - name: profileId
        in: query
        required: true
        schema:
          type: string
        description: Profile that owns the queue.
      - name: queueId
        in: query
        schema:
          type: string
        description: Specific queue. Defaults to the profile's default queue. Cannot be combined with `all=true`.
      - name: all
        in: query
        schema:
          type: boolean
        description: Return every queue on the profile instead of a single schedule.
      responses:
        '200':
          description: Queue schedule returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueSlotsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - Queues
      operationId: createQueueSlot
      summary: Create a queue
      description: Creates a posting queue on a profile. A profile may hold up to 10 queues, each with up to 56 slots. The first queue on a profile automatically becomes its default. This endpoint requires a read-write API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueCreateRequest'
            example:
              profileId: k57a1p3q9w2y8b6d4f0g
              name: Morning Posts
              timezone: America/Edmonton
              slots:
              - dayOfWeek: 1
                time: 09:00
              - dayOfWeek: 3
                time: 09:00
              active: true
      responses:
        '201':
          description: Queue created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueWriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The profile has reached its queue limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags:
      - Queues
      operationId: updateQueueSlot
      summary: Update a queue
      description: 'Replaces a queue''s timezone and slots, and optionally renames, pauses, or promotes it to default. With `reshuffleExisting: true` the queue''s future scheduled posts are re-placed onto the new schedule in their existing order; posts that are already publishing, published, or failed are never moved, and at most 200 posts may move in one call. Validation and slot assignment both run before the first write, so a rejected update leaves the queue untouched. This endpoint requires a read-write API key.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueUpdateRequest'
            example:
              profileId: k57a1p3q9w2y8b6d4f0g
              timezone: America/Edmonton
              slots:
              - dayOfWeek: 1
                time: 08:30
              reshuffleExisting: true
      responses:
        '200':
          description: Queue updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueUpdateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
      - Queues
      operationId: deleteQueueSlot
      summary: Delete a queue
      description: Deletes the queue named by `queueId`, or every queue on the profile when `queueId` is omitted. Posts already placed by the queue keep their scheduled times; only the queue link is removed. Deleting the default queue promotes the profile's oldest remaining queue. This endpoint requires a read-write API key.
      parameters:
      - name: profileId
        in: query
        required: true
        schema:
          type: string
        description: Profile that owns the queue.
      - name: queueId
        in: query
        schema:
          type: string
        description: Queue to delete. Omit to delete every queue on the profile.
      responses:
        '200':
          description: Queue deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueDeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/queue/next-slot:
    get:
      tags:
      - Queues
      operationId: getNextQueueSlot
      summary: Get the next queue slot
      description: Returns the next free instant the queue would hand out. This is a preview only — the slot is not reserved. Create queued posts with `queuedFromProfile` rather than passing this value back as `scheduledFor`, or a concurrent create can take the slot first.
      parameters:
      - name: profileId
        in: query
        required: true
        schema:
          type: string
        description: Profile that owns the queue.
      - name: queueId
        in: query
        schema:
          type: string
        description: Specific queue. Defaults to the profile's default queue.
      responses:
        '200':
          description: Next slot returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueNextSlotResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The queue is paused or has no slots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/queue/preview:
    get:
      tags:
      - Queues
      operationId: previewQueue
      summary: Preview upcoming queue slots
      description: Returns the next `count` instants the queue would hand out, in ascending order. Occupied slots are skipped, so the preview matches what the next posts would actually receive. Previewing reserves nothing.
      parameters:
      - name: profileId
        in: query
        required: true
        schema:
          type: string
        description: Profile that owns the queue.
      - name: queueId
        in: query
        schema:
          type: string
        description: Specific queue. Defaults to the profile's default queue.
      - name: count
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: How many upcoming slots to return.
      responses:
        '200':
          description: Upcoming slots returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuePreviewResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The queue is paused or has no slots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    QueueWriteResponse:
      type: object
      required:
      - success
      - schedule
      - nextSlots
      properties:
        success:
          type: boolean
        schedule:
          $ref: '#/components/schemas/QueueSchedule'
        nextSlots:
          type: array
          items:
            type: string
            format: date-time
    QueueUpdateRequest:
      type: object
      required:
      - profileId
      - timezone
      - slots
      properties:
        profileId:
          type: string
          description: Profile that owns the queue.
        queueId:
          type: string
          description: Queue to update. Defaults to the profile's default queue.
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
          description: Send an empty string to clear the description.
        timezone:
          type: string
        slots:
          type: array
          maxItems: 56
          items:
            $ref: '#/components/schemas/QueueSlot'
          description: Replaces the queue's slots entirely.
        active:
          type: boolean
        setAsDefault:
          type: boolean
        reshuffleExisting:
          type: boolean
          description: Re-place the queue's future scheduled posts onto the new schedule. Only applies when the timezone or slots actually changed.
    QueueSlotsResponse:
      description: A single schedule, or every schedule on the profile when `all=true`.
      oneOf:
      - $ref: '#/components/schemas/QueueScheduleResponse'
      - $ref: '#/components/schemas/QueueSchedulesResponse'
    QueueDeleteResponse:
      type: object
      required:
      - success
      - deleted
      - deletedCount
      properties:
        success:
          type: boolean
        deleted:
          type: boolean
        deletedCount:
          type: integer
          minimum: 1
          description: How many schedules were deleted. Always 1 when `queueId` is supplied; when it is omitted every schedule on the profile is deleted and this is that count.
    QueueSchedulesResponse:
      type: object
      required:
      - exists
      - schedules
      properties:
        exists:
          type: boolean
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/QueueScheduleWithNextSlots'
    QueueNextSlotResponse:
      type: object
      required:
      - profileId
      - nextSlot
      - timezone
      - queueId
      - queueName
      properties:
        profileId:
          type: string
        nextSlot:
          type:
          - string
          - 'null'
          format: date-time
          description: Null when every slot in the next year is already taken.
        timezone:
          type: string
        queueId:
          type: string
        queueName:
          type: string
    QueuePreviewResponse:
      type: object
      required:
      - profileId
      - count
      - slots
      properties:
        profileId:
          type: string
        count:
          type: integer
          minimum: 0
          description: Number of slots returned, which can be fewer than requested.
        slots:
          type: array
          items:
            type: string
            format: date-time
    QueueSlot:
      type: object
      required:
      - dayOfWeek
      - time
      properties:
        dayOfWeek:
          type: integer
          minimum: 0
          maximum: 6
          description: Day of the week, 0 = Sunday through 6 = Saturday.
        time:
          type: string
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
          description: 24-hour wall-clock time (`HH:mm`) in the queue's timezone.
    QueueUpdateResponse:
      type: object
      required:
      - success
      - schedule
      - nextSlots
      - reshuffledCount
      properties:
        success:
          type: boolean
        schedule:
          $ref: '#/components/schemas/QueueSchedule'
        nextSlots:
          type: array
          items:
            type: string
            format: date-time
        reshuffledCount:
          type: integer
          minimum: 0
          description: How many scheduled posts were moved onto the new schedule.
    QueueCreateRequest:
      type: object
      required:
      - profileId
      - timezone
      - slots
      properties:
        profileId:
          type: string
          description: Profile the queue belongs to.
        name:
          type: string
          minLength: 1
          maxLength: 100
          default: Default Queue
        description:
          type: string
          maxLength: 500
        timezone:
          type: string
          description: IANA timezone. Rejected if unknown — queues never silently fall back to UTC.
        slots:
          type: array
          maxItems: 56
          items:
            $ref: '#/components/schemas/QueueSlot'
          description: Weekly slots. May be empty; a queue with no slots accepts no queued posts until slots are added.
        active:
          type: boolean
          default: true
        setAsDefault:
          type: boolean
          description: Make this the profile's default queue. The first queue on a profile becomes default regardless.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        type:
          type: string
        code:
          type: string
        param:
          type:
          - string
          - 'null'
    QueueSchedule:
      type: object
      required:
      - _id
      - profileId
      - name
      - timezone
      - slots
      - active
      - isDefault
      - createdAt
      - updatedAt
      properties:
        _id:
          type: string
        profileId:
          type: string
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
        timezone:
          type: string
          description: IANA timezone the slots are evaluated in, for example `America/Edmonton`.
        slots:
          type: array
          maxItems: 56
          items:
            $ref: '#/components/schemas/QueueSlot'
          description: Weekly slots, deduplicated and sorted by day then time.
        active:
          type: boolean
          description: Paused queues reject new queue-mode posts and report no upcoming slots.
        isDefault:
          type: boolean
          description: Whether this queue answers when `queueId` is omitted.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RateLimitError:
      type: object
      required:
      - error
      - retryAfter
      properties:
        error:
          type: string
          const: rate_limited
        retryAfter:
          type: integer
          minimum: 1
          description: Number of seconds to wait before retrying.
    QueueScheduleResponse:
      type: object
      required:
      - exists
      - schedule
      - nextSlots
      properties:
        exists:
          type: boolean
          description: False when the profile has no matching queue; `schedule` is then null.
        schedule:
          oneOf:
          - $ref: '#/components/schemas/QueueSchedule'
          - type: 'null'
        nextSlots:
          type: array
          items:
            type: string
            format: date-time
          description: Next five instants this queue would hand out, occupied slots already skipped.
    QueueScheduleWithNextSlots:
      allOf:
      - $ref: '#/components/schemas/QueueSchedule'
      - type: object
        required:
        - nextSlots
        properties:
          nextSlots:
            type: array
            items:
              type: string
              format: date-time
  responses:
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Failed to create post
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Not found
    TooManyRequests:
      description: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: rate_limited
            retryAfter: 30
    Forbidden:
      description: The API key does not have sufficient permission or profile access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: API key requires read_write permission
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: JSON body is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: PostZen API key.