POST`/social-posts`

Creates and schedules one or more social posts (up to 15 per request).

https://api.postfa.st/Auth: pf-api-keyRate limit: 350 requests per day, 150 per minuteMaximum 250 MB per video and 10 MB per image.

Disabled accounts

If a post's socialMediaId points to an account whose connectionStatus is DISABLED, scheduling it returns 400 Bad Request. You can still save it as a draft (status: DRAFT). Check connectionStatus via GET /social-media/my-social-accounts first.

X (Twitter) per-account daily cap

PostFast caps X API posts per account per day: 6 on Starter, Creator, and Growth; 9 on Pro and Enterprise. An organization-wide daily X cap also applies. These are separate from the request rate limits.

Daily posting limits

Each platform has its own per-account daily posting limit, resetting at midnight UTC. See the fair usage policy at postfa.st/fair-usage for details.

Request body

postsarrayrequired

Array of post objects (1-15 per request).

contentstringrequired

Text content of the post.

mediaItemsarrayoptional

Media attached to the post.

keystringrequired

S3 object key from /file/get-signed-upload-urls.

typestringrequired

Whether the item is an image or a video.

IMAGEVIDEO

sortOrdernumberrequired

Ordering of the media items.

coverTimestampstringoptional

Millisecond timestamp used as the video cover (e.g. 5000). Supported on TikTok, Instagram Reels, and Pinterest video pins; not supported on Facebook.

coverImageKeystringoptional

S3 key of a custom video cover/thumbnail. Takes priority over coverTimestamp where supported (Instagram Reels JPEG max 8MB; Facebook Reels max 10MB; Pinterest JPEG/PNG; YouTube uses youtubeThumbnailKey; not supported on TikTok).

scheduledAtISO 8601Required (unless DRAFT)

UTC date-time, e.g. YYYY-MM-DDTHH:mm:ss.sssZ. Must be in the future, within 1 year.

socialMediaIdstring (UUID)required

Target account id from /social-media/my-social-accounts.

firstCommentstringoptional

Automatic first comment, posted ~10s after publish (up to 3 attempts). Supported on X, Instagram, Facebook, YouTube, Threads only.

statusstringoptionaldefault SCHEDULED

Whether the post is scheduled or saved as a draft.

DRAFTSCHEDULED

approvalStatusstringoptionaldefault APPROVED

APPROVED publishes; PENDING_APPROVAL holds for review.

APPROVEDPENDING_APPROVAL

controlsobjectoptional

Platform-specific settings (see the controls matrix below).

Controls (platform-specific)

Optional controls object. Each field applies only to its platform; PostFast validates which controls are valid for the target account.

X (Twitter)

xRetweetUrlstringoptional

URL of a tweet to retweet without changes. Content and media are ignored when set. Accepts x.com, twitter.com, mobile.twitter.com.

Instagram

instagramPublishTypestringoptionaldefault TIMELINE

Where the media is published.

TIMELINESTORYREEL

instagramPostToGridbooleanoptionaldefault true

Also post to the profile grid.

instagramCollaboratorsstring[]optional

Instagram usernames invited as collaborators.

instagramTrialReelStrategystringoptional

Publish the reel as a trial (non-followers only). Requires instagramPublishType: REEL; cannot combine with collaborators.

MANUALSS_PERFORMANCE

Facebook

facebookContentTypestringoptionaldefault POST

POST = up to 10 photos or 1 video; REEL = 1 video; STORY = 1 image or video.

POSTREELSTORY

facebookReelsCollaboratorsstring[]optional

Facebook usernames invited to a Reel collaboration.

TikTok

tiktokTitlestringoptional

Carousel title (max 90 chars, photo carousels only). When set, content becomes the description.

tiktokPrivacystringoptionaldefault PUBLIC

Audience for the post.

PUBLICMUTUAL_FRIENDSFOLLOWER_OF_CREATORONLY_ME

tiktokIsDraftbooleanoptionaldefault false

Save to TikTok drafts instead of publishing.

tiktokAllowCommentsbooleanoptionaldefault true

Allow comments.

tiktokAllowDuetbooleanoptionaldefault true

Allow duets.

tiktokAllowStitchbooleanoptionaldefault true

Allow stitches.

tiktokBrandOrganicbooleanoptionaldefault false

Your own brand promotion.

tiktokBrandContentbooleanoptionaldefault false

Paid partnership / branded content.

tiktokAutoAddMusicbooleanoptionaldefault false

Let TikTok add music automatically.

tiktokIsAigcbooleanoptionaldefault false

Disclose AI-generated content.

YouTube

youtubeTitlestringoptional

Video title (defaults to first 100 chars of content).

youtubePrivacystringoptionaldefault PUBLIC

Visibility of the video.

PRIVATEPUBLICUNLISTED

youtubeTagsstring[]optional

Video tags.

youtubeCategoryIdstringoptional

YouTube category id.

youtubeIsShortbooleanoptionaldefault true

Publish as a Short.

youtubeMadeForKidsbooleanoptionaldefault false

COPPA made-for-kids flag.

youtubePlaylistIdstringoptional

Playlist to add the video to after publishing (from /youtube-playlists). The playlist must belong to the authenticated channel; the video still publishes if the playlist addition fails.

youtubeThumbnailKeystringoptional

Custom thumbnail media key (JPEG/PNG recommended; GIF/BMP/WebP also allowed; max 2MB; 1280x720). Requires a phone-verified channel; the video still publishes if the thumbnail upload fails.

pinterestBoardIdstringRequired for Pinterest

Board to publish the pin to (from /pinterest-boards).

pinterestLinkstringoptional

Destination URL when users click the pin.

Content parsing: first line becomes the pin title (max 100 chars); the rest becomes the description (max 800).

Carousel pins support 2-5 static images (no video).

linkedinAttachmentKeystringRequired for documents

S3 key from /file/get-signed-upload-urls for a PDF/DOC/DOCX/PPT/PPTX (max 60MB). Cannot mix with mediaItems.

linkedinAttachmentTitlestringoptionaldefault Document

Display title for the document.

Google Business Profile

gbpLocationIdstringRequired for GBP

Location resource name (from /gbp-locations).

gbpTopicTypestringoptionaldefault STANDARD

Post type.

STANDARDEVENTOFFER

gbpCallToActionTypestringoptional

CTA button.

BOOKORDERSHOPLEARN_MORESIGN_UPCALL

gbpCallToActionUrlstringoptional

Destination URL for the CTA button. Used when a CTA type other than CALL is set.

gbpEventTitlestringoptional

Title for EVENT/OFFER posts (max 58 chars).

gbpEventStartDateISO 8601Required for EVENT/OFFER

Start of the event or offer.

gbpEventEndDateISO 8601Required for EVENT/OFFER

End of the event or offer.

gbpOfferCouponCodestringoptional

Coupon code (OFFER only).

gbpOfferRedeemUrlstringoptional

Redemption URL (OFFER only).

gbpOfferTermsstringoptional

Terms and conditions (OFFER only).

1 image only (JPEG/PNG), no video or carousel. Content limit 1500 chars.

Standard posts are visible for 6 months; Event and Offer posts stay until their end date.

The call-to-action button is ignored on OFFER posts.

Platform character limits

Platform	`content` cap	Notes
Facebook	63,206
X (Twitter)	4,000	Premium default; free-tier accounts are capped at 280 by X.
Instagram	2,200
LinkedIn	3,000
TikTok	4,000 / 2,200	Photo carousels: 4,000. Narrows to 2,200 if any media item is a VIDEO. See also `tiktokTitle` (max 90, photo carousels only).
YouTube	5,000	`<` and `>` are not allowed in titles or descriptions.
BlueSky	300
Threads	500
Pinterest	900	First line is the pin title (max 100); the remaining 800 chars become the description.
Telegram	4,096
Google Business Profile	1,500

Exceeding a cap returns 400 Bad Request with a contentLength.<platform> error key.

First-comment limits

Platform	`firstComment` cap
Instagram	2,200
Facebook	8,000
YouTube	10,000
Threads	500
X (Twitter)	4,000 (Premium); 280 (free tier)

firstComment is not supported on LinkedIn, TikTok, Pinterest, BlueSky, or Google Business Profile and returns a validation error.

Response

201 Created An object with the ids of the created posts.

Request20 examples

curl -X POST "https://api.postfa.st/social-posts" \
  -H "pf-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "content": "3 productivity hacks that changed my morning routine ☀️ Which one are you trying first? #productivity #morningroutine #lifehacks",
        "mediaItems": [
          {
            "key": "video/a7b8c9d1-e2f3-4567-8901-23456789abcd.mp4",
            "type": "VIDEO",
            "sortOrder": 0,
            "coverTimestamp": "3000"
          }
        ],
        "scheduledAt": "2025-01-31T10:00:00.000Z",
        "socialMediaId": "550e8400-e29b-41d4-a716-446655440001"
      }
    ],
    "controls": {
      "tiktokPrivacy": "PUBLIC",
      "tiktokAllowComments": true,
      "tiktokAllowDuet": true
    }
  }'

Response201 Created

{
  "postIds": [
    "8d9e0f1a-2b3c-4567-8901-def123456789",
    "9e0f1a2b-3c4d-5678-9012-ef1234567890"
  ]
}

POST/social-posts