Use the Scheduled API: tokens, scopes, posts, media and webhooks
Scheduled has a REST API, the same engine Claude uses. Use it to plug Scheduled into Zapier, n8n, Make or your own scripts: schedule posts, upload media, read your stats and get notified when a post goes out.
Before you start
- Base URL:
https://api.scheduled.so/v1 - Authentication: a Personal Access Token. Create one in Settings → API and give it only the permissions your tool needs. Send it as
Authorization: Bearer <token>. - Format: JSON in, JSON out. Errors always look like
{ "error": "...", "message": "...", "request_id": "..." }: keep therequest_idif you contact us. - Limits: 600 requests per minute per token.
Permissions (scopes)
read:calendars,read:connections: list your calendars and connected accountsread:posts: list and read postswrite:posts: create and update posts, resume a calendar, check LinkedIn tagsdelete:posts: cancel postsread:analytics: stats, top posts, comparisons, best timeswrite:media: upload and read media
Schedule your first post
curl -X POST https://api.scheduled.so/v1/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: launch-2026-11-20" \
-H "Content-Type: application/json" \
-d '{
"scheduled_for": "2026-11-20T09:00:00+01:00",
"social_connection_labels": ["LI@your-name"],
"title": "Launch post (internal)",
"text": "We just shipped it."
}'
social_connection_labelsare the labels shown in the app (or usesocial_connection_ids). With a single active calendar you can leave the calendar out, otherwise passcalendar_nameorcalendar_id.titleis internal (shown in Notion). The published text istext.Idempotency-Keymakes the call safe to retry: the same key returns the same result instead of creating a second post.- A
201means the card already exists in Notion. A202means it was created and the sync is still catching up: do not send it again, read it fromGET /v1/posts.
Add media, a cover and a video title
POST /v1/mediawithfilename,mime_typeandsize_bytes. You get an upload URL.PUTthe file to that URL.- Use the returned
media_...id inmedia_idswhen you create the post.
For a video, add a cover (a JPEG or PNG uploaded the same way) and a title:
"media_ids": ["media_<video>"],
"cover_media_id": "media_<image>",
"video_title": "Why MQTT?"
- The cover is not part of
media_ids: a video plus an image there is a multi-asset post, which YouTube refuses. video_titleis used on YouTube (100 characters max) and LinkedIn.- The cover needs the Cover image feature on the calendar's Notion database, otherwise you get
cover_property_missingand nothing is created. - You can change or remove the cover later with
PATCH /v1/posts/:idandcover_media_id(a media id, ornull). - You can change the video title later with
PATCH /v1/posts/:idandvideo_title(1 to 100 characters, ornullto clear it). A post with no video block is refused withvideo_not_foundand nothing changes. - For YouTube, choose how the video is published with
visibility:public,unlistedorprivate(public when you leave it out). It needs the YouTube visibility feature on the calendar's Notion database, otherwise you getvisibility_property_missingand nothing is created.PATCH /v1/posts/:idcan change it until the post is published, then it answersalready_published: use YouTube Studio. Unlisted and private videos have no stats in Scheduled.
Check a LinkedIn tag before you post
POST /v1/linkedin/mentions/check with { "profile_urls": ["https://www.linkedin.com/in/jane-doe"] } (profiles or company pages, 5 links at most). Each link comes back taggable (with the name), not_taggable or unknown. It is limited to 60 lookups per hour. taggable means Scheduled can build the tag, LinkedIn can still decline to show it.
Check a post before you create it
Not sure a post will pass (a long text on X, a text-only post on Instagram, a media format)? Send the same body with "dry_run": true. Scheduled runs the same checks as for a real post and answers without creating anything in Notion or scheduling anything:
{ "dry_run": true, "valid": false, "error": { "code": "x_limit_exceeded", "message": "..." } }valid: truemeans the post would be accepted as sent. Send it again withoutdry_runto create it. The call answers200even when the post is not valid (an unknown calendar or account included): readvalid.- It does not check what only exists once the card is in Notion (reel or story options,
sc_*properties), nor what can fail at publication time. The answer lists this innot_checked. - A dry run never uses your
Idempotency-Key, so you can reuse the same key for the real call. It is limited to 20 per minute.
The main endpoints
GET /posts,GET /posts/:id: list (cursor pagination) and read postsPOST /posts,PATCH /posts/:id: create and update a postPOST /posts/:id/duplicate: copy a post to another dateDELETE /posts/:id: cancel a postGET /calendars,GET /connections: your calendars and accountsGET /analytics/top-posts,/analytics/compare,/analytics/post/:id: statsGET /scheduling/best-times,/scheduling/next-slot: when to postPOST /media,GET /media/:id: upload and check media
Get notified with webhooks
Create an endpoint with POST /v1/webhook_endpoints and you receive post.published, post.failed and post.sync_failed. Each call is signed: check the X-Scheduled-Signature header (t=<unix>,v1=<hmac>) with the secret shown when you create the endpoint, and use X-Scheduled-Delivery to ignore duplicates.
What the API cannot do (yet)
- Change the text or the media of an existing post: cancel it and create a new one.
Key takeaways
- Personal Access Token, scoped, revocable, 600 requests per minute.
- Every post lands in your Notion calendar.
- Send an
Idempotency-Keyon creation so a retry never duplicates a post. - A video cover is a separate
cover_media_id, never part ofmedia_ids. - Send
dry_run: trueto check a post before you create it.
Updated on: 18/11/2026
Thank you!
