Post See Social Scheduler

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

1. Create a Post See account at post-see.com. 2. Connect your social accounts and link them into a workspace. 3. Enable API access and create an API key (pk_live_… as shown in the API docs “Try it”). 4. Store your API key in workspace .env:

   POST_SEE_API_KEY=pk_live_xxxxx
   

5. Optional: save the OpenAPI document locally for offline reference:

   curl -sS https://api.post-see.com/openapi.yaml -o post-see-openapi.yaml
   

6. 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 
Content-Type: application/json

Base URL: https://api.post-see.com/api/v1

Responses

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=

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=&status=&platform=&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"]
}

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=&post_id=&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

1. Store videos in a local folder. 2. Extract a frame with ffmpeg to read any text overlays:

   ffmpeg -i video.mp4 -ss 00:00:04 -frames:v 1 frame.jpg -y
   

3. Write caption from content + hashtags; upload media to HTTPS storage and copy URLs. 4. POST /posts with media_urls, connection_id, platform, and schedule (or draft). 5. Move posted assets to a posted/ subfolder to avoid duplicates. 6. After the scheduled time, GET /post-results?post_id=... to confirm status and external_post_url.

Tips

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.

1. Create a Post See account at post-see.com. 2. Connect your social accounts and link them into a workspace. 3. Enable API access and create an API key (pk_live_… as shown in the API docs “Try it”). 4. Store your API key in workspace .env:

   POST_SEE_API_KEY=pk_live_xxxxx
   

5. Optional: save the OpenAPI document locally for offline reference:

   curl -sS https://api.post-see.com/openapi.yaml -o post-see-openapi.yaml
   

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