postnext-social-manager

Manage social media through PostNext - schedule, publish, and analyze posts across Twitter/X, Instagram, LinkedIn, Threads, YouTube, TikTok, and Bluesky via the PostNext public API. Use when the user wants to draft, schedule, or publish social posts, upload media for posts, check what is queued, cancel a scheduled post or delete a post from PostNext, read social analytics (engagement, best time to post, audience growth) or refresh them with an analytics sync, and has a PostNext account and API key. Publishing, scheduling, cancelling, deleting and uploading always preview first and need the user's approval.

Drive a PostNext account programmatically: connect channels, upload media, compose and schedule or publish posts across platforms, and read analytics. Wraps the PostNext public REST API with an API key.

Setup

1. The user creates an API key at https://postnext.io/account/api-keys (shown only once).
2. Export it: export POSTNEXT_API_KEY=<key>
3. Base URL is https://api-app.postnext.io. Auth header on every request: x-api-key: $POSTNEXT_API_KEY.

Two ways to use this skill:

• Helper (recommended where a shell is available): the bundled postnext script (needs curl + jq). It handles the fiddly, error-prone parts for you. Run ./postnext help.
• Raw curl (works anywhere, including no-filesystem sandboxes): every operation has a copy-paste curl recipe in references/.

The core loop

1. Connect (one-time, done by the user in the PostNext web app - there is no API to connect a channel). Confirm what is connected: postnext channels.

2. Upload media if the post has an image or video: postnext upload ./clip.mp4 prints an asset URL (or pass the file straight to --media in step 3).

3. Compose + publish now or schedule:

   • postnext post --provider twitter --text "..." --media ./a.png
   • postnext schedule --provider instagram --text "..." --media ./a.jpg --at 2026-07-25T14:00:00Z

   Every command that changes the account (post, schedule, cancel, delete, upload) first prints a preview and sends nothing (exit code 3). Show the preview to the user. Only after they approve it, run the identical command again with --confirm <code> from the preview. The code covers that exact operation: if the text, media, time or target changes, preview again and get a fresh approval.

4. Measure: postnext analytics overview, postnext analytics best-time twitter, postnext results.

Safety

• The API key acts on the user's real social accounts. Use a dedicated key, and never paste it into posts, logs or URLs.
• Confirm with the user before any publish, schedule, cancel, delete or upload. The helper enforces this: without the --confirm code from its own preview it sends nothing. Never pass a code the user has not approved, and never reuse one for a changed operation.
• delete removes the post from PostNext only. It does not remove an already-published post from the platform.
• The helper only talks to https://api-app.postnext.io. Do not point raw curl recipes at any other host with the key.

Four traps this skill exists to prevent

The PostNext API has four behaviors that silently produce broken posts. The postnext helper handles all four; if you use raw curl, you must handle them yourself (see references/posts.md and references/media.md).

1. Key posts by the bare provider name (twitter), never twitter:@handle. A colon key is rejected at publish. Select the account with the entry's providerId + channelName.
2. Attach media by its URL, never by assetId. A post that carries only assetIds publishes with no media and no error. Put the uploaded asset.url into content.media.
3. providerId is the connection's providerId (the platform-native account id from GET /api/connections), not uniqueId. A wrong or missing providerId fails at the publish worker silently.
4. Only twitter and threads thread. An array of posts sent to any other provider is silently reduced to the first item.

When to read which reference

Task	Read
Build a post, threads, per-provider rules, char limits	references/posts.md
Upload an image or video, size routing, the 3-step flow	references/media.md
List or check connected channels, resolve providerId	references/channels.md
Read analytics, best time to post, sync	references/analytics.md
Response envelope shapes, error codes, rate limits	references/errors.md

Known limitations

• No channel connect over the API (browser-only in PostNext).
• No team switching: the key operates on its account's default team.
• One entry per provider per request (no multi-account-per-provider in a single post).
• Analytics and per-post metrics require PUBLISHED posts.
• Not supported by this skill: WordPress/blog posts, brand-profile edits, team management (use the PostNext MCP or web app).