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

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.

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"

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]
  }
}
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

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.

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]
  }'

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]
  }
}

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",
  "slots": [
    {
      "datetime_utc": "2025-01-30T14:00:00+00:00",
      "datetime_local": "2025-01-30T09:00:00-05:00",
      "available": true
    },
    {
      "datetime_utc": "2025-01-30T17:00:00+00:00",
      "datetime_local": "2025-01-30T12:00:00-05:00",
      "available": false,
      "scheduled_post": {
        "job_id": "abc123",
        "title": "My scheduled post",
        "platforms": ["instagram", "tiktok"]
      }
    }
  ],
  "next_available": "2025-01-30T14:00:00+00:00"
}

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)

See Also​