Queues API

The queue system lets you define recurring time slots for a brand. Posts added to a queue automatically fill the next available slot — no need to calculate dates yourself. Especially useful for AI agents and content automation pipelines.

How queues work

1

Create queue slots for a brand

Define which days and times posts should go out (e.g., Monday 9am, Wednesday 2pm, Friday 10am)

2

Add posts to the queue

When creating a post, pass "queue": true instead of scheduledFor

3

Posts auto-fill the next available slot

Each post is assigned the next open time slot. Slots cycle weekly — once all slots for a week are filled, the queue rolls into the next week.

Endpoints

POST/api/v1/queuesCreate queue slots
GET/api/v1/queuesList queue configurations
GET/api/v1/queues/:id/nextPreview upcoming slots
PATCH/api/v1/queues/:idUpdate queue slots or timezone
DELETE/api/v1/queues/:idDelete a queue

Create queue slots

POST/api/v1/queuesCreate a new queue configuration for a brand

Each brand can have one queue. Creating a second queue for the same brand returns a 409 queue_exists error; use PATCH to change an existing queue.

Request Body

brandId
stringRequired

The brand to create the queue for

timezone
stringRequired

IANA timezone for slot scheduling (e.g., America/Toronto, Europe/London)

slots
arrayRequired

Array of slot objects, each with a day and times array

slots[].day
stringRequired

Day of the week

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
slots[].times
string[]Required

Array of times in 24-hour format (e.g., "09:00", "14:30")

curl -X POST https://schedulala.com/api/v1/queues \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "brand_xyz789",
    "timezone": "America/Toronto",
    "slots": [
      { "day": "monday", "times": ["09:00", "14:00"] },
      { "day": "tuesday", "times": ["09:00", "14:00"] },
      { "day": "wednesday", "times": ["09:00", "14:00"] },
      { "day": "thursday", "times": ["09:00", "14:00"] },
      { "day": "friday", "times": ["09:00", "14:00"] }
    ]
  }'
{
  "success": true,
  "queue": {
    "id": "queue_abc123",
    "brandId": "brand_xyz789",
    "timezone": "America/Toronto",
    "slots": [
      {
        "day": "monday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "tuesday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "wednesday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "thursday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "friday",
        "times": [
          "09:00",
          "14:00"
        ]
      }
    ],
    "totalSlotsPerWeek": 10,
    "isActive": true,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

List queue configurations

GET/api/v1/queuesList all queue configurations for your account

Query Parameters

brandId
stringOptional

Filter queues by brand ID

curl https://schedulala.com/api/v1/queues?brandId=brand_xyz789 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "queues": [
    {
      "id": "queue_abc123",
      "brandId": "brand_xyz789",
      "timezone": "America/Toronto",
      "slots": [
        {
          "day": "monday",
          "times": [
            "09:00",
            "14:00"
          ]
        },
        {
          "day": "wednesday",
          "times": [
            "09:00",
            "14:00"
          ]
        },
        {
          "day": "friday",
          "times": [
            "09:00",
            "14:00"
          ]
        }
      ],
      "totalSlotsPerWeek": 6,
      "isActive": true,
      "pendingPosts": 3,
      "nextSlot": "2026-03-03T14:00:00.000Z",
      "createdAt": "2026-02-15T10:00:00.000Z"
    }
  ]
}

Preview upcoming slots

GET/api/v1/queues/:id/nextPreview the next upcoming time slots and which posts fill them

Query Parameters

count
numberOptional

Number of upcoming slots to return (max 50)

Default: 10

curl https://schedulala.com/api/v1/queues/queue_abc123/next?count=5 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "queueId": "queue_abc123",
  "timezone": "America/Toronto",
  "upcoming": [
    {
      "datetime": "2026-03-03T14:00:00.000Z",
      "day": "monday",
      "time": "14:00",
      "post": {
        "id": "post_def456",
        "caption": "Queued post about productivity tips...",
        "status": "scheduled",
        "platforms": [
          "twitter",
          "linkedin"
        ],
        "externalId": null
      }
    },
    {
      "datetime": "2026-03-05T09:00:00.000Z",
      "day": "wednesday",
      "time": "09:00",
      "post": null
    },
    {
      "datetime": "2026-03-05T14:00:00.000Z",
      "day": "wednesday",
      "time": "14:00",
      "post": null
    },
    {
      "datetime": "2026-03-07T09:00:00.000Z",
      "day": "friday",
      "time": "09:00",
      "post": null
    },
    {
      "datetime": "2026-03-07T14:00:00.000Z",
      "day": "friday",
      "time": "14:00",
      "post": null
    }
  ]
}

Slots with post: null are empty and available. The next post added to this queue will fill the earliest open slot.

Update queue

PATCH/api/v1/queues/:idUpdate queue slots or timezone

Request Body

slots
arrayOptional

New slot configuration (replaces all existing slots)

timezone
stringOptional

New IANA timezone for slot scheduling

curl -X PATCH https://schedulala.com/api/v1/queues/queue_abc123 \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "Europe/London",
    "slots": [
      { "day": "monday", "times": ["10:00", "15:00"] },
      { "day": "thursday", "times": ["10:00", "15:00"] }
    ]
  }'
{
  "success": true,
  "queue": {
    "id": "queue_abc123",
    "brandId": "brand_xyz789",
    "timezone": "Europe/London",
    "slots": [
      {
        "day": "monday",
        "times": [
          "10:00",
          "15:00"
        ]
      },
      {
        "day": "thursday",
        "times": [
          "10:00",
          "15:00"
        ]
      }
    ],
    "totalSlotsPerWeek": 4,
    "isActive": true,
    "createdAt": "2026-02-15T10:00:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z"
  },
  "orphanedPostsConverted": 0
}

Note: Updating slots replaces the entire slot configuration. Posts whose scheduled time still matches a slot in the new configuration keep their times. Posts whose slot no longer exists are converted to draft; the response reports how many in orphanedPostsConverted.

Delete queue

DELETE/api/v1/queues/:idDelete a queue configuration
curl -X DELETE https://schedulala.com/api/v1/queues/queue_abc123 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "message": "Queue deleted",
  "postsConverted": 2
}

Important: Posts already assigned to future time slots from this queue will revert to draft status. They will not be published unless you reschedule them manually or assign them to a different queue.

Adding a post to a queue

To add a post to a queue, use the POST /api/v1/posts endpoint and pass "queue": true instead of scheduledFor. The post will automatically be assigned to the next available time slot. If you have queues on multiple brands, pass brandId to pick which brand's queue to use.

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Automating my content pipeline with queues!",
    "platforms": [
      { "platform": "twitter", "accountId": "acc_tw_123" },
      { "platform": "linkedin", "accountId": "acc_li_456" }
    ],
    "queue": true
  }'
{
  "success": true,
  "post": {
    "id": "post_ghi789",
    "content": "Automating my content pipeline with queues!",
    "mediaItems": [],
    "mediaType": "none",
    "status": "scheduled",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "acc_tw_123",
        "status": "pending"
      },
      {
        "platform": "linkedin",
        "accountId": "acc_li_456",
        "status": "pending"
      }
    ],
    "scheduledFor": "2026-03-05T09:00:00.000Z",
    "timezone": null,
    "isApiPost": true,
    "brandId": "brand_xyz789",
    "externalId": null,
    "createdAt": "2026-03-01T18:30:00.000Z",
    "updatedAt": "2026-03-01T18:30:00.000Z"
  }
}

Tip: You can mix queued and directly scheduled posts. Use queue for regular content cadence and scheduledFor for time-sensitive posts that need to go out at an exact moment.

Related

Posts API — Create, schedule, and manage posts across platformsAccounts API — Manage connected social accounts and brandsSandbox Mode — Test queues without publishing to real platforms