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. For tool calls, use the MCP reference.

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.