Queues API Reference

The Queues API lets you create and manage posting queues. Queues automatically schedule posts into recurring weekly timeslots, with priority-based ordering.

Endpoints

Method	Endpoint	Description
`GET`	`/api/post_queues`	List all queues
`GET`	`/api/post_queues/:id`	Get a single queue
`GET`	`/api/post_queues/:id/next_slot`	Get next available timeslot
`POST`	`/api/post_queues`	Create a new queue
`PATCH`	`/api/post_queues/:id`	Update a queue
`DELETE`	`/api/post_queues/:id`	Delete a queue

Concepts

Timeslots

Each queue has a set of weekly timeslots that define when posts are published. A timeslot is a combination of a day of the week (0=Sunday through 6=Saturday) and a time in 24-hour HH:MM format. Times are interpreted in the queue’s timezone.

Priority

Posts added to a queue have a priority level that determines scheduling order:

Priority	Description
`high`	Scheduled first — gets the earliest available slot
`medium`	Default priority
`low`	Scheduled last — fills remaining slots

Within the same priority level, posts are ordered by creation time (oldest first).

Dynamic rearrangement

The queue automatically rearranges all scheduled posts when:

A new post is added to the queue
A post is removed from the queue
Timeslots are added or removed
The queue’s timezone is changed
The queue is unpaused

Jitter

Queues support a jitter parameter (0–60 minutes) that randomly shifts each post’s scheduled time by +/- the specified number of minutes. This makes posting patterns look more natural and less automated.

For example, with jitter: 10 and a timeslot at 09:00, posts will be scheduled anywhere between 08:50 and 09:10.

Jitter is applied when the queue is arranged — when posts are added, removed, or when queue settings change.

Pausing

When a queue is paused (enabled: false), posts in the queue will not be published even if their scheduled time arrives. When the queue is unpaused, all posts (including those that became past-due while paused) are rearranged into future timeslots.

List queues

GET /api/post_queues

Retrieves all queues for the current account.

Query parameters

Parameter	Type	Required	Description
`profile_group_id`	string	No	Filter by profile group (ID)

Example

curl -X GET "https://api.postproxy.dev/api/post_queues" \
  -H "Authorization: Bearer your_api_key"

Response

{
  "data": [
    {
      "id": "q1abc",
      "name": "Morning Posts",
      "description": "Daily morning content",
      "timezone": "America/New_York",
      "enabled": true,
      "jitter": 10,
      "profile_group_id": "pg123",
      "timeslots": [
        { "id": 1, "day": 1, "time": "09:00" },
        { "id": 2, "day": 3, "time": "09:00" },
        { "id": 3, "day": 5, "time": "14:00" }
      ],
      "posts_count": 5
    }
  ]
}

Get queue

GET /api/post_queues/:id

Retrieves a single queue by its ID.

Example

curl -X GET "https://api.postproxy.dev/api/post_queues/q1abc" \
  -H "Authorization: Bearer your_api_key"

Response fields

Field	Type	Description
`id`	string	Queue identifier (ID)
`name`	string	Queue name
`description`	string\|null	Optional description
`timezone`	string	IANA timezone name (e.g. `America/New_York`)
`enabled`	boolean	Whether the queue is active
`jitter`	integer	Random offset in minutes (+/-) applied to scheduled times (0–60, default: 0)
`profile_group_id`	string	Associated profile group (ID)
`timeslots`	array	Weekly timeslot definitions
`posts_count`	integer	Number of currently scheduled posts

Timeslot fields

Field	Type	Description
`id`	integer	Timeslot ID (used for deletion)
`day`	integer	Day of the week: `0`=Sunday, `1`=Monday, …, `6`=Saturday
`time`	string	Time in 24-hour `HH:MM` format

Get next slot

GET /api/post_queues/:id/next_slot

Returns the next available timeslot for the queue.

Example

curl -X GET "https://api.postproxy.dev/api/post_queues/q1abc/next_slot" \
  -H "Authorization: Bearer your_api_key"

Response

{
  "next_slot": "2026-03-11T14:00:00Z"
}

Error response

No timeslots configured (422):

{
  "error": "No available slots found. Add timeslots to your queue."
}

Create queue

POST /api/post_queues

Creates a new posting queue connected to a profile group.

Request body

Parameter	Type	Required	Description
`profile_group_id`	string	Yes	Profile group ID to connect the queue to
`post_queue[name]`	string	Yes	Queue name
`post_queue[description]`	string	No	Optional description
`post_queue[timezone]`	string	No	IANA timezone (default: `UTC`)
`post_queue[jitter]`	integer	No	Random offset in minutes (0–60, default: `0`)
`post_queue[queue_timeslots_attributes]`	array	No	Initial timeslots

Example

curl -X POST "https://api.postproxy.dev/api/post_queues" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_group_id": "pg123",
    "post_queue": {
      "name": "Morning Posts",
      "description": "Weekday morning content",
      "timezone": "America/New_York",
      "queue_timeslots_attributes": [
        { "day": 1, "time": "09:00" },
        { "day": 2, "time": "09:00" },
        { "day": 3, "time": "09:00" },
        { "day": 4, "time": "09:00" },
        { "day": 5, "time": "09:00" }
      ]
    }
  }'

Response (201 Created)

Returns the created queue object (same format as Get Queue).

Update queue

PATCH /api/post_queues/:id

Updates a queue’s settings, timeslots, or enabled state. Any changes to timezone or timeslots will trigger a rearrangement of all queued posts.

Request body

Parameter	Type	Required	Description
`post_queue[name]`	string	No	Queue name
`post_queue[description]`	string	No	Description
`post_queue[timezone]`	string	No	IANA timezone
`post_queue[enabled]`	boolean	No	Pause (`false`) or unpause (`true`) the queue
`post_queue[jitter]`	integer	No	Random offset in minutes (0–60)
`post_queue[queue_timeslots_attributes]`	array	No	Add/remove timeslots

Managing timeslots

Add a timeslot:

{
  "post_queue": {
    "queue_timeslots_attributes": [
      { "day": 2, "time": "10:00" }
    ]
  }
}

Remove a timeslot (pass id and _destroy: true):

{
  "post_queue": {
    "queue_timeslots_attributes": [
      { "id": 42, "_destroy": true }
    ]
  }
}

Example: Pause a queue

curl -X PATCH "https://api.postproxy.dev/api/post_queues/q1abc" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "post_queue": { "enabled": false } }'

Example: Change timezone

curl -X PATCH "https://api.postproxy.dev/api/post_queues/q1abc" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "post_queue": { "timezone": "America/Los_Angeles" } }'

Response

Returns the updated queue object.

Delete queue

DELETE /api/post_queues/:id

Deletes a queue. Posts that were in the queue will have their queue reference removed but will not be deleted.

Example

curl -X DELETE "https://api.postproxy.dev/api/post_queues/q1abc" \
  -H "Authorization: Bearer your_api_key"

Response (200 OK)

{
  "deleted": true
}

Adding posts to a queue

To add a post to a queue, pass the queue_id parameter when creating a post via the Posts API:

curl -X POST "https://api.postproxy.dev/api/posts" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "body": "Queued post content"
    },
    "profiles": ["twitter", "linkedin"],
    "queue_id": "q1abc",
    "queue_priority": "high"
  }'

Queue parameters on post creation

Parameter	Type	Required	Default	Description
`queue_id`	string	Yes	-	Queue ID
`queue_priority`	string	No	`medium`	Priority: `high`, `medium`, or `low`

The post will be assigned to the next available timeslot. After saving, the queue is rearranged so that higher-priority posts get earlier slots.

Response fields on queued posts

Posts created via a queue include additional fields:

Field	Type	Description
`queue_id`	string	Queue ID the post belongs to
`queue_priority`	string	Priority level: `high`, `medium`, or `low`
`scheduled_at`	string	Assigned timeslot (ISO 8601)