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": "..." } // reel post types; omit it and it's resolved for you
}

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.

`postSettings`

Video render settings for reel posts — videoDuration (seconds) and an optional audioId. You may omit it: the duration and audio then fall back to the videoSettings the attached design was generated with, and finally to 30 seconds with no audio. See postSettings.

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
`postSettings has invalid field '<key>'. Allowed fields are: videoDuration, audioId`	Unknown key inside `postSettings`
`postSettings.videoDuration is required and must be a number of seconds`	`postSettings` sent without a numeric `videoDuration`
`postSettings.videoDuration must be at least 5 seconds and less than 60 seconds`	Duration out of range
`postSettings.audioId must be a media id string`	`audioId` empty or wrong type
`postSettings.audioId does not exist in this workspace`	No such media, or it belongs to another workspace
`postSettings.audioId must reference an audio file`	The media id points at an image or other non-audio file
`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