List Queues

A queue is a recurring schedule with a set of weekly slots (day of week + time) interpreted in the queue’s timezone. When you create a post with a queue_id, it takes the next available slot.

A queue can be standalone (workspace-wide, profile_id: null) or scoped to one profile. The first queue in each bucket is its default: one default per profile for profile-scoped queues, and one default among a workspace’s standalone queues. Setting a new default clears the previous one within the same bucket.

The queue object

Times are stored per-slot as HH:mm local to the queue’s timezone. next_slots are the upcoming resolved slot instants in UTC.

{
  "id": "que_3fG...",
  "profile_id": "pro_9aB...",
  "name": "Weekday mornings",
  "timezone": "America/New_York",
  "status": "active",
  "default": true,
  "slots": [{ "day_of_week": 1, "time": "09:00" }],
  "next_slots": ["2026-07-14T13:00:00.000Z"],
  "created_at": "2026-07-12T10:00:00.000Z",
  "updated_at": "2026-07-12T10:00:00.000Z"
}

day_of_week is 0 (Sunday) through 6 (Saturday).

GET/v1/queues

Query parameters

No filter — lists all queues in the workspace (standalone + profile-scoped).
?profile_id=pro_... — lists that profile’s queues.
?standalone=true — lists only standalone (profile-less) queues.

{
  "queues": [
    {
      "id": "que_3fG...",
      "profile_id": "pro_9aB...",
      "name": "Weekday mornings",
      "timezone": "America/New_York",
      "status": "active",
      "default": true,
      "slots": [
        {
          "day_of_week": 1,
          "time": "09:00"
        }
      ],
      "next_slots": [
        "2026-07-14T13:00:00.000Z"
      ],
      "created_at": "2026-07-12T10:00:00.000Z",
      "updated_at": "2026-07-12T10:00:00.000Z"
    }
  ]
}

Create Queue

POST/v1/queues

Body parameters

Field	Type	Notes
`profile_id`	string	Optional; omit for a standalone queue
`name`	string	Required
`timezone`	string	IANA tz; defaults to the workspace timezone
`status`	string	`active` or `disabled`
`slots`	array	`{ day_of_week, time }` pairs

POST /v1/queues

curl -X POST https://api.socialit.com/v1/queues \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "pro_9aB...",
    "name": "Weekday mornings",
    "timezone": "America/New_York",
    "slots": [{ "day_of_week": 1, "time": "09:00" }, { "day_of_week": 3, "time": "09:00" }]
  }'

{
  "queue": {
    "id": "que_3fG...",
    "profile_id": "pro_9aB...",
    "name": "Weekday mornings",
    "timezone": "America/New_York",
    "status": "active",
    "default": true,
    "slots": [
      {
        "day_of_week": 1,
        "time": "09:00"
      }
    ],
    "next_slots": [
      "2026-07-14T13:00:00.000Z"
    ],
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Get Queue

GET/v1/queues/:id

{
  "queue": {
    "id": "que_3fG...",
    "profile_id": "pro_9aB...",
    "name": "Weekday mornings",
    "timezone": "America/New_York",
    "status": "active",
    "default": true,
    "slots": [
      {
        "day_of_week": 1,
        "time": "09:00"
      }
    ],
    "next_slots": [
      "2026-07-14T13:00:00.000Z"
    ],
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Update Queue

PATCH/v1/queues/:id

Update name, timezone, status, default, or replace slots.

PATCH /v1/queues/:id

curl -X PATCH https://api.socialit.com/v1/queues/que_3fG... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Weekday afternoons", "default": true }'

{
  "queue": {
    "id": "que_3fG...",
    "profile_id": "pro_9aB...",
    "name": "Weekday mornings",
    "timezone": "America/New_York",
    "status": "active",
    "default": true,
    "slots": [
      {
        "day_of_week": 1,
        "time": "09:00"
      }
    ],
    "next_slots": [
      "2026-07-14T13:00:00.000Z"
    ],
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Delete Queue

DELETE/v1/queues/:id

{ "ok": true }

Next Slot

GET/v1/queues/next-slot

Pass ?queue_id=que_..., or ?profile_id=pro_... to use that profile’s default queue. Returns the next available slot as a UTC datetime.

Scheduling a post to a queue

Pass queue_id when creating a post (instead of scheduled_at) to assign the next open slot.

{ "next_slot": "2026-07-14T13:00:00.000Z" }

Example create-post body using a queue:

curl -X POST https://api.socialit.com/v1/posts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Hello!", "queue_id": "que_3fG...", "target_account_ids": ["sa_..."] }'