Postfast

PostFast

Schedule social media posts across 10 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:

   export POSTFAST_API_KEY="your-api-key"

Base URL: https://api.postfa.st Auth header: pf-api-key: $POSTFAST_API_KEY

Core Workflow

1. List connected accounts

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

2. Schedule a text post (no media)

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:

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:

curl -X PUT "SIGNED_URL_HERE" \
  -H "Content-Type: image/png" \
  --data-binary @/path/to/file.png

Step C — Create post with media key:

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

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

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:

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:

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:

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. LinkedIn personal accounts are excluded.

Rate limit: 350/hour.

Common Patterns

Pattern 1: Cross-platform campaign

Post the same content to LinkedIn, X, and Threads at the same time:

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 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"

See examples/instagram-reel.json for the request body.

Pattern 3: TikTok video with privacy settings

Upload video, then post with privacy controls:

# controls object:
{
  "tiktokPrivacy": "PUBLIC",
  "tiktokAllowComments": true,
  "tiktokAllowDuet": false,
  "tiktokAllowStitch": false,
  "tiktokBrandContent": true
}

See examples/tiktok-video.json.

Pattern 4: Pinterest pin (board required)

Always fetch boards first, then post:

# 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.

Pattern 5: YouTube Short with tags and playlist

Upload video, then post with YouTube controls:

# 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.

Pattern 6: LinkedIn document post

Documents (PDF, PPTX, DOCX) display as swipeable carousels on LinkedIn.

1. Get signed URL with contentType: "application/pdf"
2. PUT the file to signed URL
3. Create post using linkedinAttachmentKey instead of mediaItems

# controls: { "linkedinAttachmentKey": "file/uuid.pdf", "linkedinAttachmentTitle": "Q1 Marketing Playbook" }
# Note: mediaItems should be [] when using linkedinAttachmentKey

See examples/linkedin-document.json.

Pattern 7: First comment (auto-posted after publish)

Add a firstComment to any post — it's auto-posted ~10 seconds after the main post goes live (up to 3 retries):

{
  "posts": [{ "content": "Main post text", "firstComment": "Link: https://postfa.st", "mediaItems": [], "scheduledAt": "...", "socialMediaId": "X_ID" }],
  "controls": {}
}

Supported on: X, Instagram, Facebook, YouTube, Threads. NOT supported on: TikTok, Pinterest, Bluesky, LinkedIn.

See examples/x-first-comment.json.

Pattern 8: X (Twitter) retweet

Schedule a retweet — content and media are ignored:

{
  "posts": [{ "content": "", "scheduledAt": "...", "socialMediaId": "X_ID" }],
  "controls": { "xRetweetUrl": "https://x.com/username/status/1234567890" }
}

See examples/x-retweet.json. For quote tweets with your own commentary, use xQuoteTweetUrl instead. See examples/x-quote-tweet.json.

Pattern 9: Batch scheduling (a week of posts)

Schedule multiple posts at different times in a single API call (up to 15 posts per request):

See examples/batch-scheduling.json.

Platform-Specific Controls

Pass these in the controls object. See references/platform-controls.md for full details.

Helper Endpoints

• Pinterest boards: GET /social-media/{id}/pinterest-boards → returns [{ boardId, name }]
• YouTube playlists: GET /social-media/{id}/youtube-playlists → returns [{ playlistId, title }]
• Connect link: POST /social-media/connect-link → returns { connectUrl }. Let clients connect accounts without a PostFast account. Params: expiryDays (1-30, default 7), sendEmail (bool), email (required if sendEmail=true)

Rate Limits

Global (per API key): 60/min, 150/5min, 300/hour, 2000/day

Per-endpoint:

• POST /social-posts: 350/day
• GET /social-posts: 200/hour
• GET /social-posts/analytics: 350/hour
• POST /social-media/connect-link: 50/hour

Platform limits:

• X (Twitter) via API: 5 posts per account per day — do not exceed this

Check X-RateLimit-Remaining-* headers. 429 = rate limited, check Retry-After-* header. For batch operations, add a 1-second delay between API calls.

Media Specs Quick Reference