Creates and schedules a post to a social account. The post is added to the publish queue and will be automatically published at the specified scheduledAt time.

Workflow

1. Upload media: POST /media/upload for each file. Save the returned id values.
2. Create the post: call this endpoint with mediaIds, scheduledAt, and platform params.
3. Done: the post is queued and will publish automatically at the scheduled time.

Media ordering: For carousel posts (Instagram, TikTok, etc.), files appear in the order of the mediaIds array. List the IDs in the order you want them to appear.

Media rules by platform

Platform-specific parameters

Some platforms require or accept additional parameters. Pass them only for their matching platform: sending youtubeParams on an Instagram post will return a validation error.

• YouTube: youtubeParams required: title (max 100 chars), optional categoryId (default "22"), tags (comma-separated, max 500 chars), selfDeclaredMadeForKids
• TikTok: tiktokParams optional: privacyLevel (defaults to PUBLIC_TO_EVERYONE), disableDuet, disableComment, disableStitch, isDraftType, isCommercialContent, isYourBrand, isBrandedContent, autoAddMusic, photosPostTitle (max 90 chars, photo posts only)
• Pinterest: pinterestParams required: boardId (get IDs from GET /social-accounts/{id}/pinterest-boards), optional title (max 100 chars), link (valid URL), altText (max 500 chars)
• Google Business: googleBusinessParams optional: topicType (default STANDARD; EVENT and OFFER require eventTitle, startDate, endDate), actionType (CTA button, not for OFFER), actionUrl (required for non-CALL CTA), couponCode (OFFER only, max 58 chars), redeemOnlineUrl, termsConditions
• X: xCommunityId optional, xTaggedUsers optional (comma-separated usernames, max 10, requires media)

Link shortening

Set shortenLinks: true to shorten the links in a post with the workspace's Bitly account. Bitly is connected per workspace in the dashboard under Settings > Integrations. These fields work on every platform.

• Links in the caption, thread posts and the first comment are shortened when the post is published, not when it is created, so the stored caption keeps the original links until then.
• Each link gets utm_source (the platform, e.g. instagram) and utm_medium=social, plus utm_campaign if you set utmCampaign. Because utm_source differs per platform, each platform gets its own short link and its own click count in Bitly.
• Links that are already Bitly links are left as they are.
• If the workspace has no Bitly connected, or Bitly fails (for example the monthly link limit is reached), the post is still published with the original links and a warning is added to the post's logs.

Caption limits

Caption length limits are enforced by each platform at publish time:

Stories

Set isStory: true to post as a story. Only Instagram and Facebook support stories. Stories require exactly 1 media file.

Example

{
  "workspaceId": "d35f525f-63e6-40ae-8946-8c120edb0225",
  "socialAccountId": "c47eb231-8eb2-4600-ac24-6951c7b5e3ce",
  "caption": "Check out our latest product launch!",
  "scheduledAt": "2026-03-15T20:00:00.000Z",
  "mediaIds": ["e1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6"]
}

{
  "workspaceId": "d35f525f-63e6-40ae-8946-8c120edb0225",
  "socialAccountId": "c47eb231-8eb2-4600-ac24-6951c7b5e3ce",
  "caption": "Check out our latest product launch!",
  "scheduledAt": "2026-03-15T20:00:00.000Z",
  "mediaIds": [
    "e1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6"
  ],
  "youtubeParams": {
    "title": "My Video Title",
    "categoryId": "22",
    "tags": "tech,tutorial,howto"
  },
  "tiktokParams": {
    "privacyLevel": "PUBLIC_TO_EVERYONE",
    "autoAddMusic": true,
    "photosPostTitle": "Check out these photos"
  },
  "pinterestParams": {
    "title": "Spring Collection 2026",
    "boardId": "board-abc123",
    "boardName": "Style Inspiration",
    "link": "https://mybrand.com/spring",
    "altText": "Spring fashion collection lookbook"
  },
  "googleBusinessParams": {
    "topicType": "STANDARD",
    "actionType": "LEARN_MORE",
    "actionUrl": "https://mybrand.com/book",
    "eventTitle": "Grand Opening Weekend",
    "startDate": "2026-04-01T09:00:00.000Z",
    "endDate": "2026-04-03T18:00:00.000Z",
    "couponCode": "SAVE20",
    "redeemOnlineUrl": "https://mybrand.com/redeem",
    "termsConditions": "Valid for new customers only. Cannot be combined with other offers."
  },
  "shortenLinks": true,
  "utmCampaign": "black_friday"
}

{
  "ok": true,
  "data": {
    "id": "a004b44d-2e69-4236-873a-081dc0d159a7",
    "workspaceId": "d35f525f-63e6-40ae-8946-8c120edb0225",
    "caption": "Check out our latest product launch! 🚀",
    "socialPlatformPostId": "17890523456789",
    "scheduledAt": "2026-03-01T12:00:00.000Z",
    "createdAt": "2026-02-19T10:30:00.000Z",
    "updatedAt": "2026-02-19T10:30:00.000Z",
    "socialAccount": {
      "id": "c47eb231-8eb2-4600-ac24-6951c7b5e3ce",
      "accountName": "mybrand",
      "accountUrl": "https://instagram.com/mybrand",
      "profilePictureUrl": "https://scontent.cdninstagram.com/profile.jpg",
      "customLabel": "Downtown"
    },
    "medias": [
      {
        "id": "f8a2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "name": "product-launch.jpg",
        "url": "https://cdn.postplanify.com/posts/all-types/product-launch.jpg",
        "type": "IMAGE_JPEG",
        "size": 245000,
        "width": 1080,
        "height": 1080
      }
    ],
    "logs": [
      {
        "type": "SUCCESS",
        "message": "Post created successfully",
        "createdAt": "2026-02-19T10:30:00.000Z"
      }
    ],
    "label": {
      "name": "Education",
      "color": "#3b82f6"
    },
    "metrics": {
      "views": 1842,
      "likes": 96,
      "comments": 12,
      "shares": 7,
      "engagementRate": 0.061,
      "platformMetrics": {
        "bookmarks": 14,
        "quotes": 3
      },
      "measuredAt": "2026-09-04"
    }
  }
}