Social Media Assistant (via Post See / post-see.com)
Autonomously manage social scheduling and publishing through the Post See REST API.
Canonical spec: download or reference https://api.post-see.com/openapi.yaml (same host as the docs).
Bundled helpers (optional): this package includes prompts/generate-post.txt, prompts/schedule-post.txt, skill.json, and Node CLIs under actions/*.js (Node 18+). The runtime instructions below are sufficient without executing those files.
Setup
-
Create a Post See account at post-see.com.
-
Connect your social accounts and link them into a workspace.
-
Enable API access and create an API key (pk_live_… as shown in the API docs “Try it”).
-
Store your API key in workspace .env:
POST_SEE_API_KEY=pk_live_xxxxx
-
Optional: save the OpenAPI document locally for offline reference:
curl -sS https://api.post-see.com/openapi.yaml -o post-see-openapi.yaml
-
ffmpeg — used when you work from local video files (extract a frame to read on-screen text before writing captions). Post See accepts public HTTPS URLs in media_urls; host files on your storage/CDN first.
Auth
All requests use a Bearer token:
Authorization: Bearer <POST_SEE_API_KEY>
Content-Type: application/json
Base URL: https://api.post-see.com/api/v1
Responses
- Success:
{ "data": …, "meta": { "api_version": "1.0", … } }
- Error:
{ "error": { "code", "message", "details?" }, "meta": … } — branch on error.code (e.g. unauthorized, workspace_forbidden, post_locked, validation_error).
Workspace scope
Pass workspace_id as a query parameter (or X-Workspace-Id where supported). Resolve membership before trusting any id. Roles: readonly can read; creating/updating/deleting posts requires collaborator, admin, or owner.
Optional: timezone query or X-Timezone (IANA) for schedule display or naive local times.
Platform slugs (platform field)
Documented today (lowercase; treat as opaque — new values may appear): bluesky, discord, facebook, instagram, linkedin, mastodon, pinterest, threads, x, youtube. X uses x, not twitter. Always match the platform string returned from GET /social-accounts for the chosen connection.
Immediate publish on create (POST /posts, per OpenAPI): linkedin, facebook, instagram, x, pinterest, bluesky, threads. Others (e.g. youtube, mastodon, discord) support drafts and scheduled posts via scheduled_at / worker — do not assume synchronous publish in the create response.
Core workflow
1. List workspaces (get workspace_id)
GET /workspaces
Use data.workspaces[] → id, name, myRole.
2. Get linked social accounts
GET /social-accounts?workspace_id=<workspace_id>
Returns data.connections[] with id (use as connection_id), platform, platform_username, is_connected, needs_reauth, and for Pinterest optionally default_pin_destination_link. OAuth tokens are never returned. If needs_reauth is true, the user must reconnect in the product before publish will succeed.
3. List and inspect posts
GET /posts?workspace_id=<id>&status=<draft|scheduled|published|fail>&platform=<slug>&page=1&limit=20
GET /posts/{id}
4. Create post
POST /posts
Required: workspace_id.
Typical JSON body:
{
"workspace_id": 7,
"connection_id": 42,
"platform": "instagram",
"text": "Caption and #hashtags",
"caption": "Optional alias for text",
"scheduled_at": "2026-04-01T14:00:00Z",
"media_urls": ["https://cdn.example.com/asset.jpg"]
}
- Omit
scheduled_at / date_time for drafts.
media_urls: public HTTPS URLs only (upload to your storage first).- Pinterest:
board_id or boardId; optional default outbound URL may exist on the connection.
- YouTube:
post_title, youtube_options (object, default {}) for product-specific hints (privacy, category, shorts vs long-form, etc.).
- All platforms:
platform_options (object, default {}) for forward-compatible flags (visibility, audience, etc.).
Deprecated: social_account_ids — prefer connection_id.
201 may include data.publish_results when immediate publish was attempted.
5. Update or delete posts
PUT /posts/{id}
DELETE /posts/{id}
Use PUT, not PATCH. 409 post_locked if the post is published or cannot be changed.
6. Check publish results
GET /post-results?workspace_id=<id>&post_id=<optional>&page=1&limit=20
GET /post-results/{id}
Inspect data.results[]: status (pending | success | fail), external_post_url, nested error (e.g. publish_failed).
7. Current user (optional)
GET /me
PATCH /me
Team / workspace admin (optional)
Routes under /workspaces/... (members, invitations, transfer) are destructive or role-sensitive. Use only when the user explicitly asks; see OpenAPI for owner vs admin requirements.
Recommended workflow for video content
-
Store videos in a local folder.
-
Extract a frame with ffmpeg to read any text overlays:
ffmpeg -i video.mp4 -ss 00:00:04 -frames:v 1 frame.jpg -y
-
Write caption from content + hashtags; upload media to HTTPS storage and copy URLs.
-
POST /posts with media_urls, connection_id, platform, and schedule (or draft).
-
Move posted assets to a posted/ subfolder to avoid duplicates.
-
After the scheduled time, GET /post-results?post_id=... to confirm status and external_post_url.
Tips
- Resolve
workspace_id and connection_id before every create/update; guessing ids causes 403 or empty lists.
- Stagger posts across the day for better reach when scheduling manually.
- Keep hashtags focused (roughly 4–5 where appropriate for the network).
- Re-fetch
openapi.yaml when integrating — new fields and platforms appear there first.
- Use a test workspace and non-production accounts before automating brands you care about.
Safety
Use a least-privilege API key; revoke from the dashboard if leaked. This skill implies the agent may read .env, workspace files, and public media URLs you provide — avoid sensitive paths and shared/synced folders you do not trust. If you do not want autonomous posting, require human confirmation before POST /posts or restrict agent autonomy in your OpenClaw config.
