postfast

# PostFast Schedule social media posts across 11 platforms from one API. SaaS — no self-hosting needed. ## Setup 1. Sign up at https://app.postfa.st/register (7-day free trial, no credit card) 2. Go to Workspace Settings → generate an API key 3. Set the environment variable: ```bash export POSTFAST_API_KEY="your-api-key" ``` Base URL: `https://api.postfa.st` Auth header: `pf-api-key: $POSTFAST_API_KEY` **Important:** The header name is `pf-api-key` (not `Authorization: Bearer` or `x-api-key`). Regenerating your key in settings permanently invalidates the previous one. See [Troubleshooting](#troubleshooting) if you get 403 errors. ## Core Workflow ### 1. List connected accounts ```bash curl -s -H "pf-api-key: $POSTFAST_API_KEY" https://api.postfa.st/social-media/my-social-accounts ``` Returns array of `{ id, platform, platformUsername, displayName }`. Save the `id` — it's the `socialMediaId` required for every post. Platform values: `TIKTOK`, `INSTAGRAM`, `FACEBOOK`, `X`, `YOUTUBE`, `LINKEDIN`, `THREADS`, `BLUESKY`, `PINTEREST`, `TELEGRAM`, `GOOGLE_BUSINESS_PROFILE` ### 2. Schedule a text post (no media) ```bash curl -X POST https://api.postfa.st/social-posts \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "posts": [{ "content": "Your post text here", "mediaItems": [], "scheduledAt": "2026-06-15T10:00:00.000Z", "socialMediaId": "ACCOUNT_ID_HERE" }], "controls": {} }' ``` Returns `{ "postIds": ["uuid-1"] }`. ### 3. Schedule a post with media (3-step flow) **Step A** — Get signed upload URLs: ```bash curl -X POST https://api.postfa.st/file/get-signed-upload-urls \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contentType": "image/png", "count": 1 }' ``` Returns `[{ "key": "image/uuid.png", "signedUrl": "https://..." }]`. **Step B** — Upload file to S3: ```bash curl -X PUT "SIGNED_URL_HERE" \ -H "Content-Type: image/png" \ --data-binary @/path/to/file.png ``` **Step C** — Create post with media key: ```bash curl -X POST https://api.postfa.st/social-posts \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "posts": [{ "content": "Post with image!", "mediaItems": [{ "key": "image/uuid.png", "type": "IMAGE", "sortOrder": 0 }], "scheduledAt": "2026-06-15T10:00:00.000Z", "socialMediaId": "ACCOUNT_ID_HERE" }], "controls": {} }' ``` For video: use `contentType: "video/mp4"`, `type: "VIDEO"`, key prefix `video/`. ### 4. List scheduled posts ```bash curl -s -H "pf-api-key: $POSTFAST_API_KEY" "https://api.postfa.st/social-posts?page=0&limit=20" ``` Returns `{ "data": [...], "totalCount": 25, "pageInfo": { "page": 1, "hasNextPage": true, "perPage": 20 } }`. **Query parameters:** - `page` (int, default 0) — 0-based page index. Response shows 1-based display page in `pageInfo.page` - `limit` (int, default 20, max 50) — items per page - `platforms` (string) — comma-separated filter: `FACEBOOK,INSTAGRAM,X` - `statuses` (string) — comma-separated: `DRAFT`, `SCHEDULED`, `PUBLISHED`, `FAILED` - `from` / `to` (ISO 8601 UTC) — date range filter on `scheduledAt` Example: `GET /social-posts?page=0&limit=50&platforms=X,LINKEDIN&statuses=SCHEDULED&from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z` ### 5. Delete a scheduled post ```bash curl -X DELETE -H "pf-api-key: $POSTFAST_API_KEY" https://api.postfa.st/social-posts/POST_ID ``` ### 6. Cross-post to multiple platforms Include multiple entries in the `posts` array, each with a different `socialMediaId`. They share the same `controls` and `mediaItems` keys. ### 7. Generate a connect link (for clients) Let clients connect their social accounts to your workspace without creating a PostFast account: ```bash curl -X POST https://api.postfa.st/social-media/connect-link \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expiryDays": 7, "sendEmail": true, "email": "client@example.com" }' ``` Returns `{ "connectUrl": "https://app.postfa.st/connect?token=..." }`. Share the URL — they can connect accounts directly. Rate limit: 50/hour. ### 8. Create a draft post Omit `scheduledAt` and set `status: "DRAFT"` to save without scheduling: ```bash curl -X POST https://api.postfa.st/social-posts \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "posts": [{ "content": "Draft idea...", "mediaItems": [], "socialMediaId": "ACCOUNT_ID" }], "status": "DRAFT", "controls": {} }' ``` ### 9. Get post analytics Fetch published posts with their performance metrics: ```bash curl -s -H "pf-api-key: $POSTFAST_API_KEY" \ "https://api.postfa.st/social-posts/analytics?startDate=2026-03-01T00:00:00.000Z&endDate=2026-03-31T23:59:59.999Z&platforms=TIKTOK,INSTAGRAM" ``` **Query parameters:** - `startDate` (ISO 8601, required) — start of date range - `endDate` (ISO 8601, required) — end of date range - `platforms` (string, optional) — comma-separated filter - `socialMediaIds` (string, optional) — comma-separated account UUIDs Returns `{ "data": [{ id, content, socialMediaId, platformPostId, publishedAt, latestMetric }] }`. `latestMetric` fields: `impressions`, `reach`, `likes`, `comments`, `shares`, `totalInteractions`, `fetchedAt`, `extras`. All numbers are strings (bigint). `latestMetric` is null if metrics haven't been fetched yet. **Supported platforms for analytics:** Facebook, Instagram, Threads, LinkedIn, TikTok, YouTube, Pinterest. LinkedIn personal accounts are excluded. YouTube returns views, likes, comments, and total interactions (no reach or shares). **Pinterest specifics** (requires a Pinterest business account): Canonical fields: - `impressions`, `likes` (reactions: heart/applaud/idea/etc.), `comments` — **lifetime** totals from Pinterest's pin endpoint. - `shares` — **90-day rolling save count**. This is the only canonical field that isn't lifetime; Pinterest's v5 API does not expose lifetime save totals. - `totalInteractions` — sum of pin clicks + outbound clicks + saves + reactions + comments. Mostly lifetime, but the saves portion is 90-day, so treat it as a "best available" interaction total rather than strictly lifetime. - `reach` — always null (Pinterest doesn't return it). `extras` (lifetime): - `pin_clicks` — opens of the pin's close-up view - `outbound_clicks` — clicks to the destination URL - `engagement`, `engagement_rate`, `pin_click_rate`, `outbound_click_rate` — Pinterest's lifetime analytics fields, passed through when present `extras` (90-day rolling): - `impressions_90d`, `pin_clicks_90d`, `outbound_clicks_90d` — same metrics as their lifetime counterparts but for the last 90 days - `save_rate` — saves ÷ impressions over the 90-day window `extras` for video pins (when present): - `video_mrc_views`, `video_avg_watch_time`, `video_v50_watch_time`, `video_10s_views`, `video_start`, `quartile_95_percent_view` Refresh cadence: every 6 hours for pins under 14 days old, once a day for pins 14–60 days old. You can also trigger a manual refresh from the dashboard. Rate limit: 350/hour. ## Common Patterns ### Pattern 1: Cross-platform campaign Post the same content to LinkedIn, X, and Threads at the same time: ```bash curl -X POST https://api.postfa.st/social-posts \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "posts": [ { "content": "Big announcement!", "mediaItems": [], "scheduledAt": "2026-06-15T09:00:00.000Z", "socialMediaId": "LINKEDIN_ID" }, { "content": "Big announcement!", "mediaItems": [], "scheduledAt": "2026-06-15T09:00:00.000Z", "socialMediaId": "X_ID" }, { "content": "Big announcement!", "mediaItems": [], "scheduledAt": "2026-06-15T09:00:00.000Z", "socialMediaId": "THREADS_ID" } ], "controls": {} }' ``` See [examples/cross-platform-post.json](examples/cross-platform-post.json) for a complete example. ### Pattern 2: Instagram Reel with upload 1. Get signed URL with `contentType: "video/mp4"` 2. PUT video to signed URL 3. Create post with `instagramPublishType: "REEL"` Optional: add a custom cover image by uploading a JPEG (max 8MB) via the same 3-step flow, then set `coverImageKey` in the media item. You can also set `coverTimestamp` (milliseconds) as a fallback frame. See [examples/instagram-reel.json](examples/instagram-reel.json) for the basic request, or [examples/instagram-reel-cover.json](examples/instagram-reel-cover.json) for a Reel with a custom cover image. ### Pattern 3: TikTok video with privacy settings Upload video, then post with privacy controls: ```bash # controls object: { "tiktokPrivacy": "PUBLIC", "tiktokAllowComments": true, "tiktokAllowDuet": false, "tiktokAllowStitch": false, "tiktokBrandContent": true } ``` See [examples/tiktok-video.json](examples/tiktok-video.json). ### Pattern 4: Pinterest pin (board required) Always fetch boards first, then post: ```bash # Step 1: Get boards curl -s -H "pf-api-key: $POSTFAST_API_KEY" \ https://api.postfa.st/social-media/PINTEREST_ACCOUNT_ID/pinterest-boards # Step 2: Post with board ID # controls: { "pinterestBoardId": "BOARD_ID", "pinterestLink": "https://yoursite.com" } ``` See [examples/pinterest-pin.json](examples/pinterest-pin.json). ### Pattern 5: YouTube Short with tags and playlist Upload video, then post with YouTube controls: ```bash # controls object: { "youtubeIsShort": true, "youtubeTitle": "Quick Tip: Batch Your Content", "youtubePrivacy": "PUBLIC", "youtubePlaylistId": "PLxxxxxx", "youtubeTags": ["tips", "productivity", "social media"], "youtubeMadeForKids": false } ``` See [examples/youtube-short.json](examples/youtube-short.json). ### Pattern 5b: YouTube video with custom thumbnail Upload both video and thumbnail image, then reference the thumbnail key in controls: ```bash # 1. Upload thumbnail image (separate from video upload) curl -X POST https://api.postfa.st/file/get-signed-upload-urls \ -H "pf-api-key: $POSTFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contentType": "image/jpeg", "count": 1 }' # PUT thumbnail to signed URL # 2. Upload video (same 3-step flow as always) # 3. Create post with thumbnail key in controls: { "youtubeIsShort": false, "youtubeTitle": "Full Tutorial: Social Media Strategy", "youtubePrivacy": "PUBLIC", "youtubeThumbnailKey": "image/abc123.jpg", "youtubeTags": ["tutorial", "social media"], "youtubeMadeForKids": false }