Schedule a Post

POST/api/schedule

Validates, persists, and enqueues a post via BullMQ. Returns the created post object with a queue_job_id.

Request body

connectedAccountIdstringbodyrequired

UUID of the connected social account to post from. Retrieve this from the Connections endpoint.

platformstringbodyrequired

Target platform. One of: twitter, linkedin, instagram, threads, tiktok, bluesky.

contentTextstringbodyrequired

The post content. Min 1 character, max 5000 characters. Platform character limits are enforced at publishing time.

scheduledAtstringbodyrequired

ISO 8601 datetime (with timezone offset) when the post should be published. Pass "now" to publish immediately.

mediaUrlsstring[]bodydefault: []

Array of media URLs to attach. Max 10 URLs.

firstCommentstringbody

Text to post as the first comment immediately after the main post publishes. Max 2200 characters.

variantIdstringbody

UUID of a draft post variant (from /api/drafts). Links this scheduled post back to its AI-generated source.

Response fields

postobject

The created post object, including id, status, scheduled_at, and queue_job_id.

{
  "connectedAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "twitter",
  "contentText": "Just shipped MisarPost v2! Schedule posts across 6 platforms with AI-generated variants. #ProductLaunch",
  "scheduledAt": "2026-05-22T10:00:00+05:30",
  "mediaUrls": [],
  "firstComment": "Thread: here's what's new in v2 🧵"
}

{
  "post": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "platform": "twitter",
    "content_text": "Just shipped MisarPost v2!...",
    "status": "queued",
    "scheduled_at": "2026-05-22T04:30:00+00:00",
    "source": "manual",
    "queue_job_id": "bull:posts:1234567890"
  }
}

{
  "error": "Post blocked by safety rules",
  "reason": "duplicate_content"
}

Error Responses

Status	Error	Description
`400`	Validation error	Missing or invalid fields
`401`	Unauthorized	Not authenticated
`402`	Plan limit reached	Free tier (10 posts/month) exceeded
`404`	Account not found	`connectedAccountId` not found or belongs to another user
`409`	Post already scheduled	Duplicate post for the same account + platform + time
`422`	Safety gate blocked	Post blocked by safety rules (duplicate content, daily limit, minimum gap between posts)
`429`	Rate limit exceeded	30 requests/minute per user

Safety Gates

The scheduling endpoint runs every post through a safety gateway before queuing:

Duplicate content — blocks identical text posted to the same account within the last 24 hours
Daily post limit — enforces a per-account maximum posts per day (platform-dependent)
Minimum gap — enforces a minimum time gap between consecutive posts on the same account
Account health — blocks scheduling if the account's token is expired or invalid

When a safety gate blocks a post, the response includes a reason field:

{
  "error": "Post blocked by safety rules",
  "reason": "duplicate_content"
}

Idempotency

Duplicate schedule requests for the same connectedAccountId + platform + scheduledAt combination are automatically detected and return 409 Conflict instead of creating a duplicate post. This protects against double-scheduling from retried requests.