---
name: postjay
version: 1.0.0
description: AI social-media scheduler for 13 platforms — connect over MCP or REST and schedule posts on the user's behalf.
homepage: https://postjay.com
metadata:
  category: social-media-scheduling
  mcp_endpoint: https://postjay.com/api/mcp
  api_base: https://postjay.com/api/v1
  docs: https://postjay.com/api
---

# PostJay — Skill for AI agents

**PostJay** lets people schedule and publish social posts to **13 platforms** —
Instagram, TikTok, X (Twitter), LinkedIn, YouTube, Facebook, Pinterest, Threads,
Bluesky, Mastodon, Discord, Telegram and Tumblr — from one place. This file tells you (an AI assistant) how to connect
to a user's PostJay account and do the work for them: list their connected
accounts, draft captions, and schedule or publish posts.

## What should you do? (read this first)

Figure out the user's intent, then jump to the matching section:

| The user wants to… | Do this |
|---|---|
| "Connect PostJay to you / set this up" | **§1 Connect** — get them authenticated, then confirm with `list_accounts` |
| "Post/schedule something" | Ensure connected (§1), then **§3 Schedule a post** |
| "What's scheduled / how did a post do?" | **§4 Read posts & analytics** |
| Build an integration / script | **§5 REST API** |

If you support **MCP** (Claude, ChatGPT, Cursor, Claude Code, …), prefer it — the
tools are listed in §2. If you can only make HTTP requests, use the REST API (§5).
Both use the same account and the same API key / token.

---

## 1. Connect

There are two ways to authenticate. Both need a free PostJay account
(https://postjay.com) with at least one social account connected under
**Accounts**.

### Option A — One-click connect (OAuth, best for ChatGPT & Claude Desktop)
Add PostJay as an MCP connector using this URL:

```
https://postjay.com/api/mcp
```

The client will send the user to a PostJay consent screen to sign in and approve
— **no API key to copy**. PostJay uses standard OAuth 2.0 with PKCE and Dynamic
Client Registration, discoverable at
`https://postjay.com/.well-known/oauth-authorization-server`. The user can revoke
access anytime under **Settings → API & Agents → Connected apps**.

### Option B — API key (best for Claude Code, Cursor, CLIs, scripts)
Ask the user to create a key at **https://postjay.com/settings/api** (starts with
`pj_live_`). Then connect. Examples:

**Claude Code**
```bash
claude mcp add --transport http postjay https://postjay.com/api/mcp \
  --header "Authorization: Bearer pj_live_YOUR_KEY"
```

**Cursor / Windsurf / VS Code** (`mcp.json`)
```json
{ "mcpServers": { "postjay": { "url": "https://postjay.com/api/mcp",
  "headers": { "Authorization": "Bearer pj_live_YOUR_KEY" } } } }
```

Treat the key like a password. It is shown only once and can be revoked anytime.

After connecting, **always call `list_accounts` first** to confirm auth works and
to get the account IDs you'll need for scheduling.

---

## 2. MCP tools

The MCP server is at `https://postjay.com/api/mcp` (Streamable HTTP). Tools:

| Tool | Purpose | Key arguments |
|---|---|---|
| `list_accounts` | List connected social accounts | — |
| `schedule_post` | Create + schedule a post, or publish now | `text`, `accountIds[]`, `scheduledAt?`, `mediaUrls?`, `firstComment?` |
| `list_posts` | List the user's posts | `page?`, `pageSize?` |
| `get_post` | Get one post + per-platform status | `id` |
| `delete_post` | Delete a post | `id` |
| `get_analytics` | Engagement summary, top posts, 30-day trend | — |

`schedule_post` arguments:
- `text` — the caption / post body.
- `accountIds` — array of IDs from `list_accounts` (one or more; you can post to
  several platforms at once).
- `scheduledAt` — ISO 8601 time (e.g. `2026-01-20T09:00:00Z`). **Omit or use a
  past time to publish immediately.**
- `mediaUrls` — optional array of public image/video URLs (downloaded + stored by
  PostJay). Max 10.
- `firstComment` — optional first comment auto-posted after publishing (Instagram
  / Facebook — great for hashtags).

---

## 3. Schedule a post (recommended flow)

1. `list_accounts` → show the user their accounts, get the IDs they want.
2. Draft the caption. Tailor tone/length per platform when it matters (X is short;
   LinkedIn is professional; Instagram leans visual + hashtags).
3. Confirm the time with the user. Convert their local time to ISO 8601.
4. Call `schedule_post` with `text`, the chosen `accountIds`, and `scheduledAt`.
5. Read back the result (it returns the created post + per-platform status). If
   something isn't ready (e.g. Instagram needs an image), tell the user plainly.

Good habits: confirm before publishing immediately; never invent account IDs;
respect each platform's limits (X ~280 chars, Bluesky ~300, Threads ~500).

---

## 4. Read posts & analytics
- `list_posts` (paginated) → drafts, scheduled, and published posts.
- `get_post { id }` → one post with its per-platform publish status.
- `get_analytics` → totals, top posts, and a 30-day engagement trend across all
  connected platforms.

---

## 5. REST API (for scripts / no-MCP clients)

Base URL: `https://postjay.com/api/v1`
Auth header: `Authorization: Bearer pj_live_YOUR_KEY` (or `x-api-key: pj_live_…`)
Responses are `{ "data": … }` on success, `{ "error": "…" }` on failure.
Rate limit: 120 requests/minute per user.

| Method | Path | Purpose |
|---|---|---|
| GET | `/accounts` | List connected accounts |
| GET | `/posts` | List posts (`?page=&pageSize=`) |
| POST | `/posts` | Create + schedule/publish a post |
| GET | `/posts/{id}` | Get one post |
| DELETE | `/posts/{id}` | Delete a post |
| GET | `/analytics` | Engagement overview |

**Create a post**
```bash
curl -X POST https://postjay.com/api/v1/posts \
  -H "Authorization: Bearer pj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Launch day! 🚀",
    "accountIds": ["acc_123", "acc_456"],
    "scheduledAt": "2026-01-20T09:00:00Z",
    "mediaUrls": ["https://example.com/launch.jpg"],
    "firstComment": "#launch #startup"
  }'
```
Omit `scheduledAt` (or use a past time) to publish immediately.

---

## Tips for agents
- **Always `list_accounts` before scheduling** — never guess IDs.
- **Confirm destructive or immediate actions** (publish now, delete) with the user.
- **Times are ISO 8601, usually UTC.** Convert from the user's local time and read
  it back to them so they can catch mistakes.
- **Media**: pass public URLs in `mediaUrls`; PostJay downloads and stores them.
- **Instagram** generally requires an image/video. If a post to Instagram has no
  media, say so instead of failing silently.
- If auth fails (401), the key was revoked or the OAuth grant was removed — ask the
  user to reconnect (§1).

## Links
- App: https://postjay.com
- Connection guide (human-readable): https://postjay.com/api
- Create/revoke API keys: https://postjay.com/settings/api
- OAuth discovery: https://postjay.com/.well-known/oauth-authorization-server