Schedules

A schedule belongs to a collection and publishes on its behalf: every weekday at 09:00, every six hours, or once on Friday evening. Instead of giving each post a time, you fill the collection with drafts and the schedule sends them out in order. When nothing is left, it can do nothing, ask your agent for new posts, or call an endpoint of yours that returns them.

Create a scheduleCopy Anchor Link

The same from the API, the CLI or an agent:

curl -s -H "Authorization: Bearer $STAQLY_API_KEY" -X POST http://localhost:3333/v1/schedules -H 'Content-Type: application/json' -d '{
  "collection": "Product updates",
  "name": "Weekday mornings",
  "kind": "recurring",
  "rule": { "times": ["09:00"], "weekdays": [1, 2, 3, 4, 5], "tz": "Europe/Warsaw" },
  "channels": ["ch_7h2kq9xw3nbvd5yhzm6a"],
  "pick": "next",
  "source": "agent"
}'

Managing schedules needs the schedules:manage scope in cloud mode.

The schedule objectCopy Anchor Link

Changing a schedule (PATCH /v1/schedules/{id}, any field) recomputes next_run_at. Run now (POST /v1/schedules/{id}/run, 202) runs it at once; the regular next run is unchanged. A once schedule is disabled after its run.

What a run doesCopy Anchor Link

A run is a run_schedule job, so it survives restarts and is retried when the server is busy.

1. Pick the posts: the oldest waiting draft, the chosen ones, or every draft, in creation order.
2. Give each one targets on the schedule's channels (unless it has its own), and publish it: the post goes publishing and its targets are published like any other.
3. When nothing was waiting, follow source (below).
4. Record schedule.ran with what happened (result in words, published_post_ids), or schedule.failed with the error, and set last_result.

The calendar shows upcoming runs as hollow chips (09:00 · Weekday mornings · next post) next to the posts that already have a time.

When nothing is waitingCopy Anchor Link

Ask your agent (source: agent)Copy Anchor Link

The run records schedule.posts_requested and leaves the schedule in GET /v1/work (kind: posts, with the schedule and its collection) until a draft appears in the collection. An agent connected over MCP sees it with list_requested_work and answers by creating drafts in that collection; the next run publishes the first of them. An alert subscribed to schedule.posts_requested tells you too, and a webhook can wake a workflow.

What to tell your agent, once, in its instructions or in the conversation:

When list_requested_work shows a schedule asking for posts, write three new drafts into its collection in the voice of the previous posts there, each with targets on the schedule's channels.

See the cookbook: Let an agent fill a collection.

Call an endpoint (source: endpoint)Copy Anchor Link

The run POSTs to endpoint_url, signed like a webhook, and creates the posts it answers with:

POST <endpoint_url>
Content-Type: application/json
User-Agent: Staqly-Schedules/1.0
X-Staqly-Timestamp: 1792400000
X-Staqly-Signature: sha256=<hex HMAC-SHA256(endpoint_secret, timestamp + "." + raw body)>

{
  "schedule": { "id": "sch_5k2nq8rx7bvm3dz4hcye", "name": "Weekday mornings", "collection_id": "col_qjuybkx6355nz4no6pqk", "channels": ["ch_7h2kq9xw3nbvd5yhzm6a"], ... },
  "collection_id": "col_qjuybkx6355nz4no6pqk",
  "channels": ["ch_7h2kq9xw3nbvd5yhzm6a"],
  "slot": "2026-10-20T07:00:00Z"
}

Answer within 60 seconds with 2xx and a JSON body:

{
  "posts": [
    { "content": "Tip of the day: drag a post on the calendar to move it.", "tags": ["tips"] },
    { "content": "A longer one for the newsletter.", "media": ["med_t4w6pz2kqm7xr3nb5vya"],
      "targets": [{ "channel_id": "ch_7h2kq9xw3nbvd5yhzm6a", "settings": { "title": "Tip of the day" } }],
      "metadata": { "campaign": "launch" } }
  ]
}

• Each entry takes content, media (ids from POST /v1/media), targets, tags and metadata; a post without targets gets one per schedule channel. At most 50 posts per answer are used.
• The posts are created in the schedule's collection with source schedule:<name> and published by the same run. A post the API refuses (over a provider's limit, say) fails the run.
• A non-2xx answer, a timeout or a body that is not {"posts": [...]} fails the run: schedule.failed with the error, last_result endpoint failed: ..., and the job is retried with the usual backoff.
• The endpoint URL follows the same network policy as webhooks (WEBHOOK_ALLOW_PRIVATE, WEBHOOK_ALLOW_LOOPBACK); see Network policy.

Verify the signature exactly as for a webhook (Verifying signatures), with the schedule's endpoint_secret as the key. See the cookbook: Posts from your endpoint.

EventsCopy Anchor Link

Every event carries schedule_id and collection_id, so GET /v1/events?schedule_id=... is one schedule's history.

Next stepsCopy Anchor Link