> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.scheduled.so/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](https://app.scheduled.so/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 team@scheduled.so. We'll help you diagnose 🙌