---
name: SocialPoster.pro
description: >-
  use this when a Grok Bot or Cursor agent should draft, schedule, or publish
  social posts through SocialPoster.pro
---

# SocialPoster.pro

SocialPoster.pro is the posting path. Do not log into each social network separately.

Live API contract (always fetch this if anything here disagrees):
https://socialposter.pro/pages/agent-docs.md
JSON: https://socialposter.pro/agent-manifest.json
Human UI: https://socialposter.pro/agent-docs
Grok Bot setup: https://socialposter.pro/pages/grok-bot.md

## Setup (human, once)

1. Sign in at https://socialposter.pro
2. Account → API Keys → New key (starts with `sp_live_`, shown once)
3. Connect social accounts on each project at /dashboard/connections
4. Give the agent this skill plus the docs URL
5. Store the key as a secret named `socialposter` / field `api_key`
   - In Grok Bot: use a secret card, never paste the key into chat
   - Cursor MCP: remote URL https://zqfnpnlzynhugeivtrka.supabase.co/functions/v1/mcp with
     header Authorization: Bearer <key>
   - Elsewhere: `Authorization: Bearer $SOCIALPOSTER_API_KEY`

## Config

- API_BASE_URL: `https://zqfnpnlzynhugeivtrka.supabase.co/functions/v1/agent-api`
- Auth: `Authorization: Bearer <sp_live_...>`
- MCP (if connected): use MCP tools instead of raw HTTP; same rules apply
- MCP URL: `https://zqfnpnlzynhugeivtrka.supabase.co/functions/v1/mcp`
- Rate limits: 120 API requests/hour/key, 5 SocialPoster image generations/hour
- Never print, log, or commit the key

## This agent's job

Own **one** SocialPoster project (one brand / site). Read the project name and site URL from the agent profile. Do not post as a different brand.

## Startup (each run)

1. `GET {API_BASE_URL}/me` (or MCP `socialposter_me`)
   - 401 → stop, tell the user the key is invalid or revoked
2. `GET {API_BASE_URL}/projects` (or `socialposter_list_projects`)
   - Match this agent to a project by name or by the project id in the profile
   - Never invent project ids
3. `GET {API_BASE_URL}/projects/{id}/generation-context`
   - Use `system_prompt` as brand voice
4. `GET {API_BASE_URL}/projects/{id}/connections`
   - Only use returned `platform_id` values
   - If the list is empty, draft in chat only. Do not create a post.

Supported platform ids (must also be connected):
`twitter` `linkedin` `instagram` `facebook` `tiktok` `youtube` `threads` `pinterest` `bluesky` `snapchat` `google_business` `reddit` `discord` `telegram` `wordpress`

## Draft and publish

1. List recent posts for this project (`limit=20`) so you do not repeat one
2. Write **one** post in the project's voice, with a real CTA to the site
3. Character limits: Twitter 280, LinkedIn 3000, Threads 500, Bluesky 300
4. Image (optional, pick one):
   - Preview first: `POST /images` (or `socialposter_generate_image`) with `prompt` + `project_id`. Show the returned `image_url` to the human.
   - Or pass `auto_image: true` / `image_prompt` / an inline marker:
     `[image: a glowing rocket at sunset]` or `/image neon city at night`
   - Or `image_url` of an existing HTTPS image (JPEG/PNG/WebP/GIF, max 5MB)
   - Do not use a third-party image API for SocialPoster post images
5. Show the human the draft (copy, image, platforms, suggested schedule) and **wait**
6. Only after approval, `POST /posts` (or `socialposter_create_post`):

```json
{
  "project_id": "<uuid>",
  "content": "<text>",
  "platforms": ["twitter", "linkedin"],
  "scheduled_at": "2026-04-20T15:00:00Z",
  "image_url": "https://..."
}
```

- Omit `scheduled_at` only if the user said post now
- Convert local times to ISO 8601 UTC
- When `platforms` includes `reddit`, also pass `"reddit_subreddit": "programming"` (name without `r/`)
- `DELETE /posts/{id}` cancels a scheduled post (not a published one)

## Analytics (optional)

- `GET /analytics/profile?project_id={id}`
- `GET /analytics/posts?project_id={id}`
- `GET /analytics/insights?project_id={id}`

Use insights when choosing the next angle. Do not invent metrics.

## Errors

- 401: stop, key invalid
- 403: missing scope, tell the user
- 429: back off (120/hr API, 5/hr images)
- 4xx: quote the response body to the user

## Never

- Store the API key in a secret card or MCP header — never in chat or logs
- Invent project ids or platform names
- Post to a platform not in `/connections`
- Publish, email, or spend without approval
- Invent testimonials, prices, reviews, or availability