Posta — Social Media Content & Scheduling

Posta is a social media management platform that lets you create, schedule, and publish posts across Instagram, TikTok, Facebook, X/Twitter, LinkedIn, YouTube, Pinterest, Threads, and Bluesky.

This skill enables you to interact with the Posta API to manage social media content end-to-end: authenticate, list accounts, upload media, create/schedule/publish posts, generate AI content, and view analytics.

Setup

Authentication (one of the following)

• - POSTA_API_TOKEN — Recommended. Personal API token (starts with posta_). Long-lived, revocable, no password exposure.
• INLINECODE2 + POSTA_PASSWORD — Legacy login. The skill logs in and caches a JWT automatically.

If POSTA_API_TOKEN is set, email/password are not needed and the login flow is skipped entirely.

Optional Environment Variables

• - POSTA_BASE_URL — API base URL (default: https://api.getposta.app/v1)
• INLINECODE7 — Fireworks.ai API key (for image generation). Keys start with fw_. Get one at https://fireworks.ai/account/api-keys. The skill auto-discovers this from env vars, ~/.posta/credentials, or .env files.
• INLINECODE11 — Google Gemini API key (for caption/text generation)
• INLINECODE12 — OpenAI API key (alternative text generation)

Credentials Auto-Discovery

The skill searches a fixed list of dedicated config files for POSTA_API_TOKEN (or legacy POSTA_EMAIL/POSTA_PASSWORD). Only exact variable names are matched — no other file content is read. Shell profiles (~/.zshrc, ~/.bashrc) are never accessed. Search order:

1. 1. Already-set environment variables (no file access)
2. INLINECODE18 — dedicated Posta config file (preferred)
3. INLINECODE19, .env.local, .env.production in the working directory

If POSTA_API_TOKEN is found, the skill uses it immediately and skips email/password lookup. See SECURITY.md in the repo root for full details.

Helper Script

Source the bash helper for all API interactions:

CODEBLOCK0

This provides:

• - Auth & Core: posta_login, posta_get_token, posta_api, INLINECODE27
• Media: posta_detect_mime, posta_upload_media, posta_upload_from_url, posta_list_media, posta_get_media, posta_delete_media, INLINECODE34
• Posts: posta_list_posts, posta_create_post, posta_create_post_from_file, posta_get_post, posta_update_post, posta_delete_post, posta_schedule_post, posta_publish_post, posta_cancel_post, INLINECODE44
• Platform Discovery: posta_list_platforms, posta_get_platform_specs, posta_get_aspect_ratios, posta_get_platform, INLINECODE49
• Analytics: posta_get_analytics_overview, posta_get_analytics_capabilities, posta_get_analytics_posts, posta_get_post_analytics, posta_get_analytics_trends, posta_get_best_times, posta_get_content_types, posta_get_hashtag_analytics, posta_compare_posts, posta_get_benchmarks, posta_export_analytics_csv, posta_export_analytics_pdf, posta_refresh_post_analytics, INLINECODE63
• User: posta_get_plan, posta_get_profile, INLINECODE66
• Fireworks: INLINECODE67

Reference Docs

• - Posta API Reference — Full REST API documentation
• Content Generation Patterns — Fireworks/Gemini/OpenAI usage
• Workflow Examples — Full example conversations

Core Workflows

1. Authenticate

Authentication is automatic. If POSTA_API_TOKEN is set, the skill uses it directly — no login step needed. Otherwise it falls back to email/password login with JWT caching. If a request returns 401:

• - API token: reports the token is invalid/revoked (no retry)
• JWT: re-authenticates and retries once

CODEBLOCK1

To verify credentials are working:
CODEBLOCK2

2. List Connected Social Accounts

CODEBLOCK3

Display as a table showing: Platform, Username, Active status, Last used.

Note: Account IDs from posta_list_accounts are integers (e.g. 35). Wrap them in quotes when passing to socialAccountIds: INLINECODE72

3. Upload Media

The upload flow has 3 steps: create signed URL → PUT binary → confirm upload. MIME type is auto-detected from the file — no need to specify it manually.

From a local file (auto-detect MIME):
CODEBLOCK4

From a local file (explicit MIME):
CODEBLOCK5

From a URL (auto-detect from extension):
CODEBLOCK6

Detect MIME type separately:
CODEBLOCK7

Supported formats:

• - Images: image/jpeg, image/png, image/webp, image/gif (max 20MB)
• Videos: video/mp4, video/quicktime, video/webm (max 500MB)

After upload, the media enters processing status. For images this is fast (thumbnails/variants). For videos it takes longer. Check status with:
CODEBLOCK8

List media library:
CODEBLOCK9

Delete media:
CODEBLOCK10

Generate carousel PDF from images:
CODEBLOCK11

4. Create, Schedule & Publish Posts

Create a draft post:
CODEBLOCK12

Create a post with multiline caption (from file):
CODEBLOCK13

Schedule for a specific time:
CODEBLOCK14

Reschedule an already-scheduled post:
The API only allows scheduling posts in draft status. To reschedule, cancel first, then schedule again:
CODEBLOCK15

Publish immediately:
CODEBLOCK16

Platform-specific configuration (optional):
CODEBLOCK17

Note: Either caption or at least one mediaIds entry is required. Text-only posts work for X/Twitter.

5. Generate AI Content

Generate an image with Fireworks SDXL:
CODEBLOCK18

Generate a caption with Gemini:
CODEBLOCK19

See content-generation.md for full patterns including OpenAI and hashtag generation.

6. View Analytics

Overview stats:
CODEBLOCK20

Best posting times:
CODEBLOCK21

Top performing posts:
CODEBLOCK22

Trends over time:
CODEBLOCK23

Check plan and usage:
CODEBLOCK24

7. Platform Discovery

Query platform capabilities, character limits, media requirements, and supported features before creating posts.

List all supported platforms:
CODEBLOCK25

Get full specs (char limits, media requirements, features):
CODEBLOCK26

Get specs for a specific platform:
CODEBLOCK27

Get aspect ratio reference:
CODEBLOCK28

Get Pinterest boards for a connected account:
CODEBLOCK29

Use platform discovery to validate content before posting — check character limits, required media dimensions, and supported post types.

8. Calendar View

View scheduled and posted content on a calendar:
CODEBLOCK30

9. Extended Analytics

Analytics capabilities (what your plan supports):
CODEBLOCK31

Top performing posts (sorted, paginated):
CODEBLOCK32

Single post analytics:
CODEBLOCK33

Trends over time with custom period:
CODEBLOCK34

Content type performance breakdown:
CODEBLOCK35

Hashtag performance (pro plan):
CODEBLOCK36

Compare posts side by side (2-4 posts, pro plan):
CODEBLOCK37

Engagement benchmarks (pro plan):
CODEBLOCK38

Export analytics:
CODEBLOCK39

Refresh analytics:

posta_refresh_post_analytics "$POST_RESULT_ID"
posta_refresh_all_analytics  # Rate limited: 1 per hour

Guidelines

1. 1. Always show a preview before publishing. Display the caption, target platforms, media description, and scheduled time. Ask for confirmation before calling publish or schedule.

1. 2. Suggest optimal posting times. When the user wants to schedule, fetch best-times analytics and recommend the highest-engagement time slot.

1. 3. Ask before spending API credits. Image generation (Fireworks) and text generation (Gemini/OpenAI) cost money. Confirm with the user before making generation API calls.

1. 4. Handle errors gracefully. If an API call fails, show the error message and suggest next steps (check credentials, verify account connection, check plan limits).

1. 5. Respect plan limits. Check the user's plan with posta_get_plan before attempting operations that may exceed limits (posts, accounts, storage).

1. 6. Use appropriate aspect ratios. Match the content format to the target platform — portrait for TikTok/Reels, square for Instagram feed, landscape for LinkedIn/X.

1. 7. Create posts as drafts first. Always set isDraft: true when creating posts, then schedule or publish after user confirmation.

1. 8. Combine media types strategically. For maximum reach, generate both an image (for Instagram/LinkedIn) and a video (for TikTok/Reels) from the same content.

1. 9. Preview generated images before uploading. After generating an image with Fireworks, use the Read tool to preview it visually before uploading to Posta. This prevents wasted uploads and media quota.

1. 10. Use posta_create_post_from_file for multiline captions. Write the caption to a temp file and use the file-based helper instead of trying to embed multiline text in JSON strings. This avoids escaping issues.

1. 11. Suggest hashtags for posts. When creating a post, suggest 5–10 relevant hashtags based on the caption content, target platform, and topic. Mix broad reach tags (e.g. #AI, #Marketing) with niche tags (e.g. #LaborMarket, #FutureOfWork). Show the suggested hashtags to the user and include them in the post only after the user approves or edits them.

1. 12. Use /tmp/.posta_last_response for captured output. When capturing posta_api output in a variable with $(), avoid using echo to re-output it — macOS echo corrupts \n in JSON strings. Instead pipe directly (posta_api ... | jq) or read from the file (jq ... /tmp/.posta_last_response).

1. 13. Use platform discovery for validation. Before creating posts for unfamiliar platforms, call posta_get_platform_specs or posta_get_platform "<platform>" to check character limits, required media dimensions, and supported features. This prevents failed posts due to platform constraints.

1. 14. Auto MIME detection for uploads. When uploading media, you can omit the MIME type parameter — posta_upload_media and posta_upload_from_url auto-detect it from the file content or extension. Only specify MIME type manually when the auto-detection might be wrong (e.g., .bin files).

1. 15. Always set TikTok privacy level. When creating posts that include TikTok, you MUST include platformConfigurations.tiktok.privacyLevel — TikTok requires it and publishing will fail without it. Use "PUBLIC_TO_EVERYONE" unless the user specifies otherwise. Valid values: PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, SELF_ONLY, FOLLOWER_OF_CREATOR.