> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/rest-api-reference/schedule-slots.md).

# Weekly posting schedule

Configure destination-specific calendar slots through REST for next-free-slot scheduling.

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](/rest-api-reference/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](/rest-api-reference/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 future posts still reference this slot, deletion fails. Do not cancel queued posts automatically. Ask whether to keep the slot, reschedule the posts, or cancel them. Obtain authorization before changing or deleting the affected schedules. Changing a schedule's time clears its slot association, so an authorized reschedule preserves the post while freeing the slot. See [Schedules](/rest-api-reference/schedules.md).

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. Preserve the posts until the user chooses to keep, reschedule, or cancel them. |

***

## 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](/rest-api-reference/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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.