Articles on: API & MCP
This article is also available in:

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.


The API is included in the Pro and Agency plans, trials included. Every post you create through it is written to your Notion calendar, like any other card.


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 the request_id if you contact us.
  • Limits: 600 requests per minute per token.


Treat the token like a password. It is shown once, and you can revoke it any time from the same page.


Permissions (scopes)


  • read:calendars, read:connections : list your calendars and connected accounts
  • read:posts : list and read posts
  • write:posts : create and update posts, resume a calendar, check LinkedIn tags
  • delete:posts : cancel posts
  • read:analytics : stats, top posts, comparisons, best times
  • write: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_labels are the labels shown in the app (or use social_connection_ids). With a single active calendar you can leave the calendar out, otherwise pass calendar_name or calendar_id.
  • title is internal (shown in Notion). The published text is text.
  • Idempotency-Key makes the call safe to retry: the same key returns the same result instead of creating a second post.
  • A 201 means the card already exists in Notion. A 202 means it was created and the sync is still catching up: do not send it again, read it from GET /v1/posts.


Add media, a cover and a video title


  1. POST /v1/media with filename, mime_type and size_bytes. You get an upload URL.
  2. PUT the file to that URL.
  3. Use the returned media_... id in media_ids when 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_title is 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_missing and nothing is created.
  • You can change or remove the cover later with PATCH /v1/posts/:id and cover_media_id (a media id, or null).
  • You can change the video title later with PATCH /v1/posts/:id and video_title (1 to 100 characters, or null to clear it). A post with no video block is refused with video_not_found and nothing changes.
  • For YouTube, choose how the video is published with visibility: public, unlisted or private (public when you leave it out). It needs the YouTube visibility feature on the calendar's Notion database, otherwise you get visibility_property_missing and nothing is created. PATCH /v1/posts/:id can change it until the post is published, then it answers already_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: true means the post would be accepted as sent. Send it again without dry_run to create it. The call answers 200 even when the post is not valid (an unknown calendar or account included): read valid.
  • 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 in not_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 posts
  • POST /posts, PATCH /posts/:id : create and update a post
  • POST /posts/:id/duplicate : copy a post to another date
  • DELETE /posts/:id : cancel a post
  • GET /calendars, GET /connections : your calendars and accounts
  • GET /analytics/top-posts, /analytics/compare, /analytics/post/:id : stats
  • GET /scheduling/best-times, /scheduling/next-slot : when to post
  • POST /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-Key on creation so a retry never duplicates a post.
  • A video cover is a separate cover_media_id, never part of media_ids.
  • Send dry_run: true to check a post before you create it.


Followed every step and it still doesn't work? Reach out via the chat at the bottom right or at [email protected]. We'll help you diagnose 🙌

Updated on: 18/11/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!