> 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/start-with-an-ai-agent/llm/scheduling.md).

# Schedules and slots

Read, edit, and cancel existing schedules, distinguish UTC slots from queued posts, and preserve user-approved content.

Compact reference for agents making REST requests. All endpoint paths below are relative to `https://backend.blotato.com/v2`. For task instructions, read the [workflow guide](/api-and-mcp-concepts/scheduling.md). For tool calls, use the [MCP reference](/start-with-an-ai-agent/mcp/tools.md).

## Managing scheduled posts

Resolve the user's requested date and timezone before changing a schedule. Replace example timestamps with the requested future time within the account's scheduling horizon. Use the existing schedule ID, not a post submission ID. Reading schedules does not authorize updates or cancellations.

```
List scheduled posts:
GET /schedules?limit=20&cursor=OPTIONAL_CURSOR

Response:
{
  "items": [
    {
      "id": "sch_abc123",
      "scheduledAt": "2026-04-01T14:00:00.000Z",
      "account": {
        "id": "98432",
        "name": "Jane Smith",
        "username": "janesmith",
        "profileImageUrl": "https://...",
        "subaccountId": null,
        "subId": null,
        "subaccountName": null
      },
      "draft": {
        "accountId": "98432",
        "content": { "text": "...", "mediaUrls": [], "platform": "twitter" },
        "target": { "targetType": "twitter" }
      }
    }
  ],
  "count": "12",
  "cursor": "eyJzY2hlZHVsZWRBd..."
}

NOTE: "draft" has the same structure as the "post" object in POST /posts.
NOTE: "scheduledAt" is the response field name. "scheduledTime" is the input field name for updates.

Get single schedule:
GET /schedules/:id
Response: { "schedule": { ...same fields as list item... } }

Update schedule (content, time, or both):
PATCH /schedules/:id
{
  "patch": {
    "scheduledTime": "2026-04-05T10:00:00Z",
    "draft": {
      "accountId": "98432",
      "content": { "text": "Updated text", "mediaUrls": [], "platform": "twitter" },
      "target": { "targetType": "twitter" }
    }
  }
}
Response: 204 No Content

RULES:
- At least one of scheduledTime or draft must be provided.
- scheduledTime must be valid ISO 8601 and in the future.
- draft must be a COMPLETE post object (accountId, content, target). The endpoint
  does NOT merge partial drafts. Read GET /schedules/:id first, preserve the
  returned schedule.draft fields, edit only the requested fields, and send the
  complete draft in patch.draft. Do not send the schedule wrapper as draft.
- DO NOT also call POST /posts (or blotato_create_post) when editing a schedule.
  PATCH /schedules/:id updates the existing schedule in place. Calling create
  publishes a separate post and you end up with duplicates at publish time.
- The update endpoint does NOT accept useNextFreeSlot. To reschedule to the next
  available slot, first call POST /schedule/slots/next-available to get the time,
  then pass it as scheduledTime.
- After PATCH, GET /schedules/:id and compare scheduledAt and draft with the
  requested changes. A 204 response has no updated schedule body.
- Changing scheduledTime clears the previous slot association. Editing content
  without changing the time preserves that association.

Delete schedule:
DELETE /schedules/:id
Response: 204 No Content (publishing job is also cancelled)
Cancel only the schedule the user authorized. This is not deletion of a live social post.
```

## Schedule slots (content calendar time windows)

```
Slots define recurring posting times in UTC. Convert the user's local day and time
to the UTC day, hour, and minute. A timezone conversion might change the weekday.
For daylight-saving changes, a fixed UTC slot does not promise a fixed local hour.
When you publish with useNextFreeSlot: true, the system finds the next open slot
matching the target platform, account, and Page.

HOW SLOTS AND SCHEDULES RELATE:
1. Slots define your posting cadence (e.g., "Monday 9 AM for Twitter").
2. useNextFreeSlot: true (on POST /posts) picks the next open slot.
3. A slot is "occupied" when a scheduled post is queued at that time.
4. Manage what is queued (schedules) and when (slots) separately.

List slots:
GET /schedule/slots
Response:
{
  "items": [
    {
      "id": "slot_1",
      "hour": 9,
      "minute": 0,
      "day": "monday",
      "selectedTargets": [
        { "platform": "twitter", "accountId": "98432", "subaccountId": null }
      ]
    }
  ]
}

Create slots:
POST /schedule/slots
{
  "slots": [
    {
      "hour": 9,
      "minute": 0,
      "day": "monday",
      "selectedTargets": [
        { "platform": "twitter", "accountId": "98432", "subaccountId": null }
      ]
    }
  ]
}
Response: 201 Created (returns created slots with IDs)

Update slot targets:
PATCH /schedule/slots/:id
{
  "patch": {
    "selectedTargets": [
      { "platform": "twitter", "accountId": "98432", "subaccountId": null }
    ]
  }
}
Response: 204 No Content

Delete slot:
DELETE /schedules/slots/:id
Response: 204 No Content
The plural /schedules/slots/:id deletion path differs from /schedule/slots elsewhere.
If future schedules still reference the slot, deletion fails. Do not cancel queued
posts automatically. Ask whether to keep the slot, reschedule those posts, or cancel
them. Obtain authorization before changing or deleting the affected schedules.

Find next available slot:
POST /schedule/slots/next-available
{ "platform": "twitter", "accountId": "98432", "subaccountId": null }
Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } }
This lookup does not reserve a slot or schedule a post.
If no slot is available, report the error. Do not fall back to immediate publishing.

Use this when rescheduling a post to the next free slot:
1. POST /schedule/slots/next-available -> get slotTime
2. PATCH /schedules/:id -> set scheduledTime to slotTime
3. GET /schedules/:id -> verify scheduledAt and the preserved draft
```

Return to the [agent reference index](/start-with-an-ai-agent/llm.md).


---

# 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/start-with-an-ai-agent/llm/scheduling.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.