Skip to main content

Queue System

The queue system allows you to automatically schedule posts to predefined time slots. Instead of specifying an exact date/time with scheduled_date, you can use add_to_queue=true to have the system automatically assign your post to the next available slot.

How It Works​

The queue is always active with default time slots (9am, 12pm, 5pm Eastern Time). You can customize these slots, timezone, and active days through the Queue Settings endpoints.

When you upload content with add_to_queue=true:

  1. The system finds the next available slot based on your queue configuration
  2. Your post is automatically scheduled to that slot
  3. You receive a job_id to track the scheduled post

Multiple Posts Per Slot​

By default, each slot accepts 1 post. You can increase this with the max_posts_per_slot setting to allow multiple posts in the same time slot. This is useful when you want to post to different platforms at the same time (e.g., an Instagram post and a Facebook post both at 9am).

You can also mark individual slots as full to prevent new posts from being added, even if they haven't reached the maximum capacity.

Using the Queue in Uploads​

Add the add_to_queue parameter to any upload endpoint:

NameTypeRequiredDescription
add_to_queueBooleanNoIf true, automatically schedules the post to your next available queue slot. Cannot be used together with scheduled_date.
max_posts_per_slotIntegerNoOverride the profile's max_posts_per_slot setting for this request. Only used when add_to_queue=true.

Example Request​

curl -X POST "https://api.upload-post.com/api/upload" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -F "user=my_profile" \
  -F "platform[]=instagram" \
  -F "platform[]=tiktok" \
  -F "video=@my_video.mp4" \
  -F "title=My awesome video" \
  -F "add_to_queue=true"

Example with Multiple Posts Per Slot​

# First post goes to 9am slot
curl -X POST "https://api.upload-post.com/api/upload" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -F "user=my_profile" \
  -F "platform[]=instagram" \
  -F "[email protected]" \
  -F "title=Instagram video" \
  -F "add_to_queue=true" \
  -F "max_posts_per_slot=3"

# Second post also goes to 9am slot (same slot, different platform)
curl -X POST "https://api.upload-post.com/api/upload" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -F "user=my_profile" \
  -F "platform[]=facebook" \
  -F "[email protected]" \
  -F "title=Facebook video" \
  -F "add_to_queue=true" \
  -F "max_posts_per_slot=3"

Success Response 202 Accepted​

{
  "success": true,
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_date": "2025-01-30T14:00:00+00:00",
  "queue_slot": "2025-01-30T14:00:00+00:00",
  "message": "Post added to queue"
}

Get Queue Settings​

Retrieve the current queue configuration for a profile.

EndpointGET /api/uploadposts/queue/settings
AuthenticationRequired. Authorization: Apikey <token>

Query Parameters​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to get settings for

Success Response 200 OK​

{
  "success": true,
  "queue_settings": {
    "timezone": "America/New_York",
    "slots": [
      { "hour": 9, "minute": 0 },
      { "hour": 12, "minute": 0 },
      { "hour": 17, "minute": 0 }
    ],
    "days_of_week": [0, 1, 2, 3, 4, 5, 6],
    "max_posts_per_slot": 1,
    "full_slots": []
  }
}
FieldTypeDescription
timezoneStringIANA timezone for the queue slots (e.g., "America/New_York", "Europe/Madrid")
slotsArrayArray of time slots with hour (0-23) and minute (0-59)
days_of_weekArrayActive days: 0=Monday, 1=Tuesday, ..., 6=Sunday
max_posts_per_slotIntegerMaximum number of posts allowed per time slot (default: 1)
full_slotsArrayList of ISO 8601 datetimes that have been manually marked as full

Update Queue Settings​

Update the queue configuration for a profile.

EndpointPOST /api/uploadposts/queue/settings
AuthenticationRequired. Authorization: Apikey <token>

Body Parameters (JSON)​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to update settings for
timezoneStringNoIANA timezone (e.g., "Europe/London"). See valid timezones.
slotsArrayNoArray of slot objects: [{ "hour": 9, "minute": 0 }, ...]. Max 24 slots.
days_of_weekArrayNoArray of active days (0-6). Example: [0, 1, 2, 3, 4] for Monday-Friday.
max_posts_per_slotIntegerNoMaximum posts per slot (1-100). Default: 1. Set higher to allow multiple posts in the same time slot.

Example Request​

curl -X POST "https://api.upload-post.com/api/uploadposts/queue/settings" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_username": "my_profile",
    "timezone": "Europe/Madrid",
    "slots": [
      { "hour": 8, "minute": 30 },
      { "hour": 13, "minute": 0 },
      { "hour": 19, "minute": 30 }
    ],
    "days_of_week": [0, 1, 2, 3, 4],
    "max_posts_per_slot": 3
  }'

Success Response 200 OK​

{
  "success": true,
  "queue_settings": {
    "timezone": "Europe/Madrid",
    "slots": [
      { "hour": 8, "minute": 30 },
      { "hour": 13, "minute": 0 },
      { "hour": 19, "minute": 30 }
    ],
    "days_of_week": [0, 1, 2, 3, 4],
    "max_posts_per_slot": 3
  }
}

Get Queue Preview​

Preview the next upcoming queue slots and their availability.

EndpointGET /api/uploadposts/queue/preview
AuthenticationRequired. Authorization: Apikey <token>

Query Parameters​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to preview
countIntegerNoNumber of slots to return (default: 10, max: 50)

Success Response 200 OK​

{
  "success": true,
  "timezone": "America/New_York",
  "max_posts_per_slot": 3,
  "slots": [
    {
      "datetime_utc": "2025-01-30T14:00:00+00:00",
      "datetime_local": "2025-01-30T09:00:00-05:00",
      "available": true,
      "post_count": 0,
      "max_posts_per_slot": 3,
      "is_full": false,
      "manually_full": false
    },
    {
      "datetime_utc": "2025-01-30T17:00:00+00:00",
      "datetime_local": "2025-01-30T12:00:00-05:00",
      "available": true,
      "post_count": 2,
      "max_posts_per_slot": 3,
      "is_full": false,
      "manually_full": false,
      "scheduled_posts": [
        {
          "job_id": "abc123",
          "title": "My Instagram post",
          "platforms": ["instagram"]
        },
        {
          "job_id": "def456",
          "title": "My Facebook post",
          "platforms": ["facebook"]
        }
      ]
    },
    {
      "datetime_utc": "2025-01-30T22:00:00+00:00",
      "datetime_local": "2025-01-30T17:00:00-05:00",
      "available": false,
      "post_count": 3,
      "max_posts_per_slot": 3,
      "is_full": true,
      "manually_full": false,
      "scheduled_posts": [...]
    }
  ],
  "next_available": "2025-01-30T14:00:00+00:00"
}
FieldTypeDescription
post_countIntegerNumber of posts currently scheduled in this slot
max_posts_per_slotIntegerMaximum posts allowed per slot
is_fullBooleantrue if the slot is at capacity or manually marked as full
manually_fullBooleantrue if the slot was manually marked as full via the Mark Slot Full endpoint
scheduled_postsArrayList of all posts scheduled in this slot (when multiple posts per slot is enabled)
scheduled_postObjectFirst scheduled post in the slot (for backward compatibility)

Mark Slot Full​

Manually mark a specific queue slot as full, preventing new posts from being added to it even if it hasn't reached max_posts_per_slot.

EndpointPOST /api/uploadposts/queue/slot-full
AuthenticationRequired. Authorization: Apikey <token>

Body Parameters (JSON)​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to update
slot_datetimeStringYesISO 8601 datetime of the slot to mark as full (UTC)

Example Request​

curl -X POST "https://api.upload-post.com/api/uploadposts/queue/slot-full" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_username": "my_profile",
    "slot_datetime": "2025-01-30T14:00:00+00:00"
  }'

Success Response 200 OK​

{
  "success": true,
  "message": "Slot 2025-01-30T14:00:00+00:00 marked as full",
  "full_slots": ["2025-01-30T14:00:00+00:00"]
}

Unmark Slot Full​

Remove the full mark from a slot, allowing new posts to be added again.

EndpointDELETE /api/uploadposts/queue/slot-full
AuthenticationRequired. Authorization: Apikey <token>

Body Parameters (JSON)​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to update
slot_datetimeStringYesISO 8601 datetime of the slot to unmark (UTC)

Example Request​

curl -X DELETE "https://api.upload-post.com/api/uploadposts/queue/slot-full" \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_username": "my_profile",
    "slot_datetime": "2025-01-30T14:00:00+00:00"
  }'

Success Response 200 OK​

{
  "success": true,
  "message": "Slot 2025-01-30T14:00:00+00:00 unmarked as full",
  "full_slots": []
}

Get Next Available Slot​

Get the next available queue slot for a profile.

EndpointGET /api/uploadposts/queue/next-slot
AuthenticationRequired. Authorization: Apikey <token>

Query Parameters​

NameTypeRequiredDescription
profile_usernameStringYesThe profile to check

Success Response 200 OK​

{
  "success": true,
  "next_slot": {
    "datetime_utc": "2025-01-30T14:00:00+00:00",
    "datetime_local": "2025-01-30T09:00:00-05:00",
    "timezone": "America/New_York"
  }
}

If no slots are available within the next 30 days:

{
  "success": true,
  "next_slot": null,
  "message": "No available slots found"
}

Default Configuration​

If you haven't customized your queue settings, these defaults apply:

SettingDefault Value
TimezoneAmerica/New_York (Eastern Time)
Slots9:00 AM, 12:00 PM, 5:00 PM
Days of weekAll days (Monday-Sunday)
Max posts per slot1

See Also​