Schedule post
Schedule a post for future publishing. Include a future publish_at timestamp and one or more social_account_ids. The post is created, its targets are queued in pg-boss, and a webhook fires when the job is queued.
Schedule a new post
POST /api/v1/posts with a future publish_at creates the post and immediately enqueues a publish job for each target. Include an Idempotency-Key header so retries are safe.
curl -X POST "$SOCIALSPOOL_BASE_URL/api/v1/posts" \
-H "Authorization: Bearer $SOCIALSPOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-2026-06-02-001" \
-d '{
"content": "Scheduled from the SocialSpool API",
"social_account_ids": ["SOCIAL_ACCOUNT_ID"],
"publish_at": "2026-06-02T15:00:00Z"
}'Successful response shape:
{
"post": {
"id": "post_01HZ...",
"content": "Scheduled from the SocialSpool API",
"status": "scheduled",
"publish_at": "2026-06-02T15:00:00Z",
"targets": [
{
"id": "pt_01HZ...",
"social_account_id": "SOCIAL_ACCOUNT_ID",
"status": "scheduled",
"publish_at": "2026-06-02T15:00:00Z"
}
],
"created_at": "2026-06-01T12:00:00Z",
"updated_at": "2026-06-01T12:00:00Z"
}
}Request body fields
content(string, required): the post body. Maximum 5000 characters.social_account_ids(string[], required): one or more account ids to publish to. Must be connected accounts from the same workspace.publish_at(string, required): ISO 8601 UTC timestamp in the future. Determines when the worker publishes.
Scheduling an existing draft
To schedule a draft that was created earlier, send a PATCH /api/v1/posts/:id with the fields you want to add or update.
curl -X PATCH "$SOCIALSPOOL_BASE_URL/api/v1/posts/post_01HZ..." \
-H "Authorization: Bearer $SOCIALSPOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: schedule-post_01HZ..." \
-d '{
"social_account_ids": ["acct_01HZ..."],
"publish_at": "2026-06-02T15:00:00Z"
}'