Create a scheduled post


POST /schedule

Creates a scheduled post or a draft for the workspace attached to your API key.

Authentication

embed-api-key: <YOUR_EMBED_API_KEY> header required. See auth.

Request body


{
  "status": "DRAFT | SCHEDULED",          // required
  "scheduledAt": "2026-07-01T10:00:00Z",  // required, ISO string, must be in the future
  "designId": "string | null",            // optional; must belong to your workspace if set .. can only be null for DRAFT
  "postContent": { "common": "..." },     // object; required unless designId is set
  "selectedAccounts": ["socialAccountId"], // array (may be empty); all must belong to your workspace
  "instagramPostSettings": { /* ... */ },  // conditionally required — see platform settings
  "tiktokPostSettings":    { /* ... */ },
  "linkedinPostSettings":  { /* ... */ },
  "threadsPostSettings":   { /* ... */ },
  "postSettings": { "videoDuration": 30, "audioId": "..." } // required for reel post types
}

Only the keys above are accepted. Sending any other top-level key is rejected with 422 { "status": false, "message": "Extra parameters passed in the body." }.

`status`

Required. Either "DRAFT" or "SCHEDULED".

`scheduledAt`

Required ISO-8601 datetime string, and must be in the future — for both drafts and scheduled posts.

`designId`

Optional. When set, it must reference a design in your workspace. A post must have either a designId or non-empty postContent.

`postContent`

An object keyed by platform; each value is the caption text for that platform. Required unless a designId is provided.


{
  "common":    "string",   // shared caption / fallback
  "linkedin":  "string",
  "instagram": "string",
  "tiktok":    "string",
  "facebook":  "string",
  "threads":   "string"
}

Recognized keys: common, linkedin, instagram, tiktok, facebook, threads. At least one must be a non-empty string (unless designId is set). Hashtags are extracted automatically from each non-empty caption.

`selectedAccounts`

Array of social-account ids to publish to (may be empty). Every id must belong to your workspace. The set of platforms among these accounts determines which *PostSettings objects are required — see Platform settings & conditional rules.

Platform settings

instagramPostSettings, tiktokPostSettings, linkedinPostSettings, threadsPostSettings, and postSettings are conditionally required. Full field definitions and cross-field rules: Platform settings & conditional rules.

Example request


curl -X POST "https://embed-api.postnitro.ai/schedule" \
  -H "embed-api-key: $EMBED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SCHEDULED",
    "scheduledAt": "2026-07-01T10:00:00Z",
    "designId": "design_456",
    "postContent": { "common": "Launch day! 🚀 #launch" },
    "selectedAccounts": ["acct_789"],
    "linkedinPostSettings": { "postType": "carousel", "postTitle": null }
  }'

Response `200`

Returns the created scheduled-post object in data. Note success is 200, not 201.


{
  "success": true,
  "message": "Scheduled post created",
  "data": {
    "id": "cmqkvnhk50001v0qusiglvc8h",
    "designId": "gpmg7dl0t73tukqvbnrtoqw6",
    "labels": null,
    "status": "SCHEDULED",
    "scheduledFor": "2026-06-20T10:00:00.000Z",
    "publishedAt": null,
    "errorMessage": null,
    "postSettings": null,
    "instagramPostSettings": null,
    "linkedinPostSettings": { "postType": "document", "postTitle": "fsdfsdfds" },
    "tiktokPostSettings": null,
    "threadsPostSettings": null,
    "postContents": [
      { "platform": "common", "text": "My draft caption", "hashtags": [] }
    ],
    "designDetails": {
      "id": "gpmg7dl0t73tukqvbnrtoqw6",
      "name": "FIFA's 2026 World Cup Will Print $10.9 Billion — Here's Who Gets What",
      "designType": "carousel",
      "source": "editor"
    },
    "socialAccounts": [
      {
        "socialAccountId": "cmqi7jyir0003v0m91hxnyyaq",
        "liveLink": null,
        "errorMessage": null,
        "status": "PENDING",
        "publishedAt": null
      }
    ],
    "createdAt": "2026-06-19T12:00:38.309Z",
    "updatedAt": "2026-06-19T12:00:38.309Z"
  }
}

Shape notes: the request sends postContent as an object keyed by platform, but the response returns postContents as an array of stored rows. Likewise, the request field scheduledAt is echoed back as scheduledFor. See the full scheduled-post object reference for every field.

Errors

Request-shape errors are returned at the edge as 422 { "status": false, "message": "..." }:

Message	When
`Status is required` / `Status must be 'DRAFT' or 'SCHEDULED'`	Invalid `status`
`Scheduled at is required` / `Scheduled at must be a string` / `Scheduled at is not a valid date`	Invalid `scheduledAt`
`Design id must be a string`	`designId` wrong type
`Post content must be an object`	`postContent` wrong type
`Selected accounts must be an array`	`selectedAccounts` wrong type
`Instagram/TikTok/LinkedIn/Threads/Post settings must be an object`	Settings field wrong type
`Extra parameters passed in the body.`	Unknown top-level key

Business-rule errors are relayed from PostNitro as { "success": false, "message": "...", "error": ... }. The full list is in the error reference — e.g. Workspace not found., Design not found., Scheduled at is in the past, Social account(s) not found or do not belong to this workspace: <ids>, the per-platform settings messages, and Failed to create <status> post.

Create a scheduled post

Authentication

Request body

status

scheduledAt

designId

postContent

selectedAccounts