---
title: "Schedule a post"
method: POST
path: "/schedule"
tags: ["Scheduling"]
---

# Schedule a post

`POST /schedule`

## Request

- Base URL: `https://api.misar.io/post`
- URL: `https://api.misar.io/post/schedule`
- Auth: API key in header `Authorization`

Validates, persists, and enqueues a post for publishing via the BullMQ worker. Runs (in order): monthly plan-quota check → connected-account ownership check → server-side post-signature append → safety-gateway check (account health, daily caps, min gap, hashtag rules, duplicate detection) → idempotent insert (same account+platform+scheduledAt hashes to the same key — a repeat call returns 409, not a duplicate post) → BullMQ enqueue. Rate limit: 30 requests/minute.

## Request body

- SchedulePostRequest
  - `connectedAccountId` string, uuid, required
  - `platform` 'twitter' | 'linkedin' | 'instagram' | 'threads' | 'tiktok' | 'bluesky' | 'mastodon' | 'youtube' | 'reddit' | 'pinterest' | 'dribbble' | 'slack' | 'discord' | 'facebook' | 'telegram' | 'devto' | 'farcaster' | 'gmb' | 'hashnode' | 'lemmy' | 'listmonk' | 'medium' | 'mewe' | 'moltbook' | 'nostr' | 'skool' | 'tumblr' | 'twitch' | 'vk' | 'linkedin_page' | 'instagram_standalone' | 'tiktok_business' | 'whop' | 'wordpress' | 'kick', required
  - `contentText` string, required
  - `mediaUrls` string[]
  - `firstComment` string: Optional first-comment text (used by platforms that support it).
  - `scheduledAt` union, required: ISO 8601 datetime, or the literal string "now" to publish immediately.
    - string, date-time
    - 'now'
  - `variantId` string, uuid: Marks the source draft/generated variant as `scheduled` once this post is created.
  - `platformMeta` object: Per-post provider-specific fields with no dedicated column (e.g. Reddit subreddit, Pinterest board, YouTube title). Passed through verbatim; each publishing adapter reads the keys it needs.

## Response `201`

Scheduled and enqueued.

- SchedulePostResponse
  - `post` object, required
    - `id` string, uuid
    - `org_id` string, uuid
    - `workspace_id` string, uuid, nullable
    - `connected_account_id` string, uuid
    - `platform` string
    - `content_text` string
    - `media_urls` string[]
    - `first_comment` string, nullable
    - `platform_meta` object
    - `scheduled_at` string, date-time
    - `status` 'queued'
    - `source` 'manual' | 'ai_generated'
    - `source_ref` string, nullable
    - `idempotency_key` string
    - `queue_job_id` string: BullMQ job ID.
    - `created_at` string, date-time

## Other responses

- `400`: Request body failed schema validation. `error` is a Zod `flatten()`-shaped object (`fieldErrors` / `formErrors`), not a plain string.
- `401`: Missing, malformed, revoked, or invalid API key/session.
- `402`: No active plan (`code: "plan_limit_exceeded"`, `reason: "no_active_plan"`, with the plan offer in `upgrade`; MisarPost has no Free plan), or the plan's monthly post limit was reached.
- `403`: The API key lacks the scope this operation requires (`code: "insufficient_scope"`, `required_scope`).
- `404`: `connectedAccountId` does not belong to the caller (or isn't in the active workspace).
- `409`: A post with the same account, platform, and scheduled time was already scheduled (idempotency key collision).
- `422`: Blocked by the safety gateway (account health, rate/gap rule, banned content, or duplicate detection).
- `429`: Per-user, per-route rate limit exceeded for this endpoint.

---

[API](https://skmtc.dev/misarpost/apis/misarpost-api.md) · [All operations](https://skmtc.dev/misarpost/apis/misarpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/misarpost/apis/misarpost-api/revisions/deec26db1305?raw)