# 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](/api/schedules.md).

## 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](/api/publish-post.md)), 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](/api/schedules.md)), 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](/api/schedules.md#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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.blotato.com/api/schedule-slots.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.