Openclaw Skill

Schedule and manage social media posts across TikTok, Instagram, Facebook, X (Twitter), YouTube, LinkedIn, Threads, Bluesky, Pinterest, and Telegram using th...

Security Scan

The skill's requests and runtime instructions are consistent with a SaaS social-post scheduling integration that uses a single workspace API key; nothing in the package is disproportionate or unrelated to its stated purpose.

Purpose & Capability

Name/description, examples, and API reference all describe a social-media scheduling/integration service (PostFast). The only required environment variable is POSTFAST_API_KEY (declared as primaryEnv) which matches the documented pf-api-key header used by every endpoint. No unrelated binaries, configs, or credentials are requested.

Instruction Scope

SKILL.md contains concrete curl examples for listing accounts, scheduling/deleting posts, and a 3-step signed-S3 media upload flow that requires PUTting local files to signed URLs. This is within scope for a posting/upload skill; note that following the upload examples requires reading local media files (e.g., --data-binary @/path/to/file.png), which is expected but means the agent will access those local file paths if it executes the commands.

Install Mechanism

No install spec and no code files (instruction-only). No remote downloads or package installs — lowest risk for disk persistence and execution of unreviewed code.

Credentials

Only POSTFAST_API_KEY is required. That is proportionate: the key is needed to authenticate API calls the skill documents. Treat this key as sensitive because it grants workspace-level API access (list accounts, create/delete posts, access analytics).

Persistence & Privilege

Skill does not request always:true and is user-invocable. There is no installation step that modifies other skills or system-wide settings. Autonomous invocation is allowed (platform default) but not combined with elevated privileges here.

Assessment

This skill appears coherent for controlling the PostFast SaaS API. Before installing: only provide POSTFAST_API_KEY if you trust PostFast and the skill publisher; treat that key like a password because it can list connected accounts and post on your behalf. Verify the vendor/homepage (https://postfa.st), read their privacy and API-key permissions, and consider creating a workspace key with limited scope if PostFast supports it. Be aware that the runtime examples upload local media files (the curl PUT uses a local file path) — running the agent's commands will read and transmit those files to the signed S3 URLs. If you have sensitive files on the host, avoid using those paths or test with non-sensitive media first. Rotate the key if you stop using the skill or if you suspect misuse.

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": "[e-mail]" }'

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.

Supported platforms for analytics: Facebook, Instagram, Threads, LinkedIn, TikTok. Other platforms are not yet supported. 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 5b: YouTube video with custom thumbnail

Upload both video and thumbnail image, then reference the thumbnail key in controls:

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

Thumbnail specs: JPEG/PNG recommended, max 2MB, 1280x720 (16:9), min width 640px. Requires phone-verified YouTube channel. If thumbnail upload fails, the video still publishes without the custom thumbnail.

See examples/youtube-video-thumbnail.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.

Platform	Key Controls
TikTok	tiktokPrivacy, tiktokAllowComments, tiktokAllowDuet, tiktokAllowStitch, tiktokIsDraft, tiktokBrandOrganic, tiktokBrandContent, tiktokAutoAddMusic
Instagram	instagramPublishType (TIMELINE/STORY/REEL), instagramPostToGrid, instagramCollaborators
Facebook	facebookContentType (POST/REEL/STORY), facebookReelsCollaborators
YouTube	youtubeIsShort, youtubeTitle, youtubePrivacy, youtubePlaylistId, youtubeTags, youtubeMadeForKids, youtubeCategoryId, youtubeThumbnailKey
LinkedIn	linkedinAttachmentKey, linkedinAttachmentTitle (for document posts)
X (Twitter)	xQuoteTweetUrl (quote tweet), xRetweetUrl (retweet), xCommunityId (post to community)
Pinterest	pinterestBoardId (required), pinterestLink
Bluesky	No platform-specific controls — text + images only
Threads	No platform-specific controls — text + images/video
Telegram	No platform-specific controls — text + images/video/mixed media

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

Platform	Images	Video	Carousel
TikTok	Carousels only	≤250MB, MP4/MOV, 3s-10min	2-35 images
Instagram	JPEG/PNG	≤1GB, 3-90s (Reels)	Up to 10
Facebook	≤30MB, JPG/PNG	1 per post	Up to 10 images
YouTube	—	Shorts ≤3min, H.264	—
LinkedIn	Up to 9	≤10min	Up to 9, or documents (PDF/PPTX/DOCX)
X (Twitter)	Up to 4	—	—
Pinterest	2:3 ratio ideal	Supported	2-5 images
Bluesky	Up to 4	Not supported	—
Threads	Supported	Supported	Up to 10
Telegram	Up to 10	Supported	Up to 10 mixed media

Common Gotchas

1. Always fetch accounts first — socialMediaId is a UUID, not a platform name. Call GET /social-media/my-social-accounts to get valid IDs.
2. Media MUST go through 3-step upload — No external URLs. Always: get signed URL → PUT to S3 → use the key in mediaItems.
3. scheduledAt must be in the future — ISO 8601 UTC format. Past dates return 400.
4. Pinterest ALWAYS requires pinterestBoardId — Fetch boards first with GET /social-media/{id}/pinterest-boards.
5. TikTok requires video for standard posts — Images only work in carousels (2-35 images).
6. LinkedIn documents use linkedinAttachmentKey — NOT mediaItems. Set mediaItems: [] when posting documents.
7. Content-Type on S3 PUT must match — The Content-Type header in your S3 PUT must match what you requested in get-signed-upload-urls.
8. Instagram Reels need video 3-90 seconds — Outside this range returns an error.
9. YouTube Shorts need video under 3 minutes — H.264 codec with AAC audio recommended.
10. X (Twitter) has a 280 character limit — Longer content is silently truncated.
11. Cross-posting shares controls — The controls object applies to ALL posts in the batch. Platform-irrelevant controls are ignored.
12. X (Twitter) API limit is 5 posts/account/day — Exceeding this risks account restrictions.
13. firstComment only works on 5 platforms — X, Instagram, Facebook, YouTube, Threads. TikTok, Pinterest, Bluesky, LinkedIn return a validation error.
14. Cannot use xQuoteTweetUrl and xRetweetUrl together — Pick one. Retweets ignore content/media.
15. LinkedIn documents support PDF, DOC, DOCX, PPT, PPTX — Max 60MB. Cannot mix with regular media.
16. Pagination is 0-based — page=0 returns the first page. Response pageInfo.page shows 1-based display number.
17. YouTube custom thumbnails require phone verification — youtubeThumbnailKey only works if the YouTube channel is phone-verified. If it fails, the video still publishes without the custom thumbnail.

Supporting Resources

Reference docs:

• references/api-reference.md — Complete API endpoint reference with response examples
• references/platform-controls.md — All platform-specific controls with types and defaults
• references/media-specs.md — Media size, format, and dimension limits per platform
• references/upload-flow.md — Detailed media upload walkthrough

Ready-to-use examples:

• examples/EXAMPLES.md — Index of all 19 examples
• examples/cross-platform-post.json — Multi-platform posting
• examples/tiktok-video.json — TikTok with privacy settings
• examples/tiktok-carousel.json — TikTok image carousel
• examples/tiktok-draft.json — TikTok saved as draft
• examples/instagram-reel.json — Instagram Reel
• examples/instagram-story.json — Instagram Story
• examples/instagram-carousel.json — Instagram carousel
• examples/facebook-reel.json — Facebook Reel
• examples/facebook-story.json — Facebook Story
• examples/youtube-short.json — YouTube Short with tags
• examples/youtube-video-thumbnail.json — YouTube video with custom thumbnail
• examples/pinterest-pin.json — Pinterest with board
• examples/linkedin-document.json — LinkedIn document post
• examples/x-quote-tweet.json — X quote tweet
• examples/x-retweet.json — X scheduled retweet
• examples/x-first-comment.json — X post with auto first comment
• examples/threads-carousel.json — Threads image carousel
• examples/batch-scheduling.json — Week of scheduled posts
• examples/telegram-mixed-media.json — Telegram mixed media

Quick Reference

# Auth
Header: pf-api-key: $POSTFAST_API_KEY

# List accounts
GET /social-media/my-social-accounts

# Schedule post
POST /social-posts  { posts: [{ content, mediaItems, scheduledAt, socialMediaId, firstComment? }], status?, approvalStatus?, controls: {} }

# Draft post (no scheduledAt needed)
POST /social-posts  { posts: [...], status: "DRAFT", controls: {} }

# List posts (page is 0-based, limit max 50)
GET /social-posts?page=0&limit=20
GET /social-posts?page=0&limit=50&platforms=X,LINKEDIN&statuses=SCHEDULED&from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z

# Delete post
DELETE /social-posts/:id

# Upload media (3 steps)
POST /file/get-signed-upload-urls  { contentType, count }
PUT  <signedUrl>  (raw file, matching Content-Type)
# then use key in mediaItems

# Pinterest boards
GET /social-media/:id/pinterest-boards

# YouTube playlists
GET /social-media/:id/youtube-playlists

# Post analytics (published posts with metrics)
GET /social-posts/analytics?startDate=...&endDate=...&platforms=...

# Connect link (for clients)
POST /social-media/connect-link  { expiryDays?, sendEmail?, email? }

Tips for the Agent

• Always call my-social-accounts first to get valid socialMediaId values.
• For media posts, complete the full 3-step upload flow (signed URL → S3 PUT → create post).
• scheduledAt must be ISO 8601 UTC and in the future.
• Pinterest always requires pinterestBoardId — fetch boards first.
• LinkedIn documents use linkedinAttachmentKey instead of mediaItems.
• For carousels, include multiple items in mediaItems with sequential sortOrder.
• TikTok video thumbnails: set coverTimestamp (seconds) in mediaItems.
• When cross-posting, adjust content length for each platform's limits (X: 280, Bluesky: 300, TikTok: 2200).
• If the user doesn't specify a time, suggest tomorrow at 9:00 AM in their timezone.
• Batch up to 15 posts per API call for efficiency.
• Use firstComment for CTAs and links — keeps the main post clean and gets better engagement.
• X (Twitter) allows only 5 posts per account per day via API — warn the user if they're batching many X posts.
• For draft posts, set status: "DRAFT" and omit scheduledAt — the user can finalize in the PostFast dashboard.
• Use GET /social-posts with from/to filters to check what's already scheduled before adding more.