For AI agents: a documentation index is available at /llms.txt. Every guide and example is also available as markdown by adding .md to its URL.

Your First Post

This walkthrough takes you from zero to a scheduled post.

1. Find a channel

Posts are published to a connected channel — a "social account". Channels are connected in the Schedulin dashboard; list them and grab an id:

curl https://api.schedulin.app/v0/social-accounts \
  -H "x-api-key: $SCHEDULIN_API_KEY"

{
  "data": [
    { "id": "acc_123", "platform": "instagram", "username": "yourbrand", "...": "..." },
    { "id": "acc_456", "platform": "twitter", "username": "yourbrand", "...": "..." }
  ]
}

2. Create the post

POST /v0/posts requires only caption and socialAccountId. Add a media array (each item needs a url) to attach images or video — Instagram, TikTok, Pinterest, and YouTube require at least one item. See Supported Platforms for each network's rules.

A post targets exactly one social account. To publish the same content to several channels, create one post per socialAccountId.

Use action to control what happens:

`action`	Behavior
`now`	Publish immediately
`schedule`	Publish at `scheduledAt` — `scheduledAt` is required
`queue`	Take the channel's next free queue slot
`draft`	Save as a draft, publish later

If you omit action, a post with scheduledAt is scheduled and a post without one is saved as a draft. action: "schedule" without scheduledAt is rejected with 422, and so is a scheduledAt in the past — always send a future time. The example below uses a fixed date far in the future; in real code compute one, for example an hour from now:

const scheduledAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();

from datetime import datetime, timedelta, timezone

scheduled_at = datetime.now(timezone.utc) + timedelta(hours=1)

curl -X POST https://api.schedulin.app/v0/posts \
  -H "x-api-key: $SCHEDULIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "socialAccountId": "acc_123",
    "caption": "Hello from the Schedulin API 👋",
    "media": [{ "url": "https://www.schedulin.app/opengraph-image.png" }],
    "action": "schedule",
    "scheduledAt": "2030-01-15T15:00:00Z"
  }'

TIP

Any publicly reachable image or video URL works in — the API downloads it into your media library for you. To upload a local file instead, see .

3. Confirm it's scheduled

curl "https://api.schedulin.app/v0/posts?status=SCHEDULED" \
  -H "x-api-key: $SCHEDULIN_API_KEY"

The post's status moves from SCHEDULED to PROCESSING while it publishes, then to COMPLETED or FAILED. Once it's live, postedAt holds the time it was published (it's null until then).

That's it — you've scheduled a post through the API. To be notified when it publishes or fails, register a webhook. Browse Examples for more recipes.