# 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](https://help.blotato.com/api/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](https://help.blotato.com/api/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`

```json
{
  "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

```json
{
  "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

```json
{
  "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](https://help.blotato.com/api/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](https://help.blotato.com/schedules#update-scheduled-post) endpoint, since that endpoint accepts `scheduledTime` but not `useNextFreeSlot`.

### Request Body

```json
{
  "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`

```json
{
  "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.