Schedule Slots

Schedule slots define the recurring time windows in your content calendar. When you publish a post with useNextFreeSlot: true, Blotato picks the next open slot matching the target platform and queues the post at that time.

To manage the posts queued in those slots, see Schedules.

How Slots and Schedules Work Together

1. Slots define your posting cadence -- for example, "every Monday at 9:00 AM UTC for Twitter."

2. When you publish a post with useNextFreeSlot: true (see Publish Post), Blotato finds the next slot that matches the target platform and account, and schedules the post at that time.

3. A slot is "occupied" when a scheduled post is already queued at that time. The next call to useNextFreeSlot skips occupied slots and picks the next open one.

4. You manage what is queued (the schedules) and when things are queued (the slots) separately.

---

List Slots

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /schedule/slots

Method: GET

Description

Returns all scheduling slots for the current user.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "slot_1",
      "hour": 9,
      "minute": 0,
      "day": "monday",
      "selectedTargets": [
        {
          "platform": "twitter",
          "accountId": "98432",
          "subaccountId": null
        }
      ]
    },
    {
      "id": "slot_2",
      "hour": 14,
      "minute": 30,
      "day": "wednesday",
      "selectedTargets": [
        {
          "platform": "instagram",
          "accountId": "98434",
          "subaccountId": null
        },
        {
          "platform": "linkedin",
          "accountId": "98435",
          "subaccountId": null
        }
      ]
    }
  ]
}

Field	Type	Description
items[].id	string	Slot ID
items[].hour	integer	Hour in UTC (0-23)
items[].minute	integer	Minute (0-59)
items[].day	string	Day of week: monday, tuesday, wednesday, thursday, friday, saturday, sunday
items[].selectedTargets	array	Platforms and accounts this slot applies to
items[].selectedTargets[].platform	string	Platform name
items[].selectedTargets[].accountId	string or null	Account ID. Null means the slot applies to all accounts on that platform.
items[].selectedTargets[].subaccountId	string or null	Subaccount ID (for Facebook Pages / LinkedIn Company Pages).

---

Create Slots

Endpoint

URL: /schedule/slots

Method: POST

Description

Create one or more scheduling slots. Each slot defines a day, time (in UTC), and which platforms/accounts it applies to. Returns an error if a slot at the same day and time already exists.

Request Body

{
  "slots": [
    {
      "hour": 9,
      "minute": 0,
      "day": "monday",
      "selectedTargets": [
        {
          "platform": "twitter",
          "accountId": "98432",
          "subaccountId": null
        }
      ]
    }
  ]
}

Field	Type	Required	Description
slots	array	Yes	Array of slots to create
slots[].hour	integer	Yes	Hour in UTC (0-23)
slots[].minute	integer	Yes	Minute (0-59)
slots[].day	string	Yes	Day of week (e.g., monday)
slots[].selectedTargets	array	Yes	Platforms and accounts. Set accountId to null for a slot that applies to all accounts on that platform.

Response

Status Code: 201 Created

Returns the created slots with their generated IDs.

---

Update Slot Targets

Endpoint

URL: /schedule/slots/:id

Method: PATCH

Description

Replace the selected targets for a slot. Send the full list of targets -- this is a full replacement, not a partial update.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Slot ID

Request Body

{
  "patch": {
    "selectedTargets": [
      {
        "platform": "twitter",
        "accountId": "98432",
        "subaccountId": null
      },
      {
        "platform": "instagram",
        "accountId": "98434",
        "subaccountId": null
      }
    ]
  }
}

Response

Status Code: 204 No Content

---

Delete Slot

Endpoint

URL: /schedules/slots/:id

Method: DELETE

Description

Delete a scheduling slot. If posts are scheduled using this slot in the future, the delete fails. Delete the scheduled posts first (see Schedules), then delete the slot.

Past scheduled posts linked to this slot are cleaned up automatically.

Path Parameters

Field	Type	Required	Description
id	string	Yes	Slot ID

Response

Status Code: 204 No Content

Errors

Status	Reason
400	Slot has future scheduled content. Delete the scheduled posts first.

---

Find Next Available Slot

Endpoint

URL: /schedule/slots/next-available

Method: POST

Description

Find the next available (unoccupied) slot for a given platform and account. Returns the slot ID and the UTC time of the next open slot.

Use this when you want to reschedule a post to the next free slot via the Update Schedule endpoint, since that endpoint accepts scheduledTime but not useNextFreeSlot.

Request Body

{
  "platform": "twitter",
  "accountId": "98432",
  "subaccountId": null
}

Field	Type	Required	Description
platform	string	Yes	Platform name
accountId	string	No	Account ID. Omit to match slots for all accounts on the platform.
subaccountId	string	No	Subaccount ID for Facebook Pages / LinkedIn Company Pages.

Response

Status Code: 201 Created

{
  "slot": {
    "slotId": "slot_1",
    "slotTime": "2026-04-02T09:00:00Z"
  }
}

Field	Type	Description
slot.slotId	string	The slot that was matched
slot.slotTime	string	ISO 8601 UTC time of the next open occurrence of this slot

Returns 400 if no slots are configured for the given platform/account.