PostPal is an AI-powered social media content creation, scheduling, and publishing platform built with Next.js 16, React 19, and Supabase.

Agent Platform

PostPal includes a production-oriented external integration layer for Codex, Claude, and other AI agents:

• Versioned HTTP API at /api/v1
• API-key auth for external integrations
• Official Node CLI: postpal
• MCP stdio bridge via postpal mcp serve
• Webhook callbacks for run and publish events

Quickstart

1. Start PostPal locally:

yarn install
yarn dev

2. Create an API key from an authenticated PostPal session:

curl -X POST http://localhost:3000/api/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-postpal-session-bearer-token>" \
  -d '{"name":"Local agent key"}'

3. Save the key for the CLI in the current workspace:

node scripts/postpal-cli.mjs auth login-key \
  --api-key ppk_live_your_postpal_api_key \
  --api-base-url http://localhost:3000

4. Verify access:

node scripts/postpal-cli.mjs brands list --json
node scripts/postpal-cli.mjs accounts list --json

CLI

node scripts/postpal-cli.mjs auth login-key --api-key <key> --api-base-url http://localhost:3000
node scripts/postpal-cli.mjs brands list --json
node scripts/postpal-cli.mjs pals list --json
node scripts/postpal-cli.mjs accounts list --platform twitter --json
node scripts/postpal-cli.mjs content generate --file payload.json --json
node scripts/postpal-cli.mjs drafts create --file payload.json --json
node scripts/postpal-cli.mjs drafts list --json
node scripts/postpal-cli.mjs drafts get --id <draft-id> --json
node scripts/postpal-cli.mjs schedules create --file payload.json --json
node scripts/postpal-cli.mjs publishes create --file payload.json --json
node scripts/postpal-cli.mjs runs get --id <run-id> --json
node scripts/postpal-cli.mjs reddit subreddits search --query "indie saas" --json
node scripts/postpal-cli.mjs reddit subreddit get --name r/SaaS --json
node scripts/postpal-cli.mjs reddit posts list --subreddit SaaS --sort top --time week --json
node scripts/postpal-cli.mjs reddit posts search --query "scheduling tool" --subreddit SaaS --json
node scripts/postpal-cli.mjs reddit comments get --post-id <id> --json
node scripts/postpal-cli.mjs reddit comments post --post-id <id> --file comment.json --confirm --json
node scripts/postpal-cli.mjs webhook endpoints list --json
node scripts/postpal-cli.mjs webhook endpoints create --file payload.json --json
node scripts/postpal-cli.mjs mcp serve

API Endpoints

• GET /api/v1/health
• GET /api/v1/brands
• GET /api/v1/pals
• GET /api/v1/accounts
• POST /api/v1/content/generate
• GET /api/v1/drafts
• GET /api/v1/drafts/:id
• POST /api/v1/drafts
• POST /api/v1/schedules
• POST /api/v1/publishes
• GET /api/v1/runs/:id
• GET /api/v1/reddit/subreddits/search
• GET /api/v1/reddit/subreddits/:name
• GET /api/v1/reddit/subreddits/:name/posts
• GET /api/v1/reddit/posts/search
• GET /api/v1/reddit/posts/:id/comments
• POST /api/v1/reddit/posts/:id/comments (requires exact user-approved text and confirmed: true)
• GET /api/v1/webhooks
• POST /api/v1/webhooks
• GET /api/v1/openapi

All /api/v1 endpoints expect:

• Authorization: Bearer ppk_live_...
• JSON bodies for write requests
• Optional Idempotency-Key for safe retries

Success responses use { data, meta? }. Errors use { error: { code, message, details?, request_id } }.

Example: Generate Drafts

curl -X POST http://localhost:3000/api/v1/content/generate \
  -H "Authorization: Bearer ppk_live_your_postpal_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-001" \
  -d '{
    "topic": "Launch our new analytics dashboard",
    "brand_id": "your-brand-id",
    "platforms": ["twitter", "linkedin", "facebook"],
    "platform_settings": {
      "twitter": "short",
      "linkedin": "medium",
      "facebook": "medium"
    },
    "persist_drafts": true
  }'

Portable Skills: zadahmed/postpal-skills

Use PostPal from any other project's agent (Claude Code, Codex, Cursor) — research subreddits, posts, and comments through your connected Reddit account, then generate, draft, schedule, or publish posts. The skills are self-contained (they talk to the v1 API directly) so consuming projects don't need this repo. API access is included on every plan.

# Claude Code: install as a plugin (skills + MCP server)
/plugin marketplace add zadahmed/postpal-skills
/plugin install postpal@postpal-skills

# Codex / Cursor: install as skills
curl -fsSL https://raw.githubusercontent.com/zadahmed/postpal-skills/main/install.sh | bash

# In the consuming project, provide credentials
export POSTPAL_API_KEY=ppk_live_...

Then ask the agent things like "research r/SaaS for pain points around scheduling tools" or "schedule a Reddit post about our launch for Friday 9am". The postpal-reddit skill source lives in skills/postpal-reddit/ here — keep it in sync with the public repo.

Example: MCP

For Claude or Codex, register a stdio MCP server that runs:

{
  "mcpServers": {
    "postpal": {
      "command": "node",
      "args": ["scripts/postpal-cli.mjs", "mcp", "serve"]
    }
  }
}

Webhooks

Create webhook endpoints with POST /api/v1/webhooks. Deliveries are signed with:

• X-PostPal-Event
• X-PostPal-Timestamp
• X-PostPal-Signature

The signature is an HMAC SHA-256 over timestamp + "." + rawBody using the endpoint signing secret.

Full web docs: /docs/ai-agent-integrations

Getting Started

First, run the development server:

yarn dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

Utility Scripts

Clean Up User Usage

Reset usage counters for a specific user. Useful for debugging, customer support, or testing.

# Reset by email
npm run cleanup-usage -- --email [email protected]

# Reset by user ID
npm run cleanup-usage -- --user-id abc-123

# Preview changes without applying them
npm run cleanup-usage -- --email [email protected] --dry-run

# Also reset the billing period to a fresh 30-day window
npm run cleanup-usage -- --email [email protected] --reset-period

Requires NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY in your .env file.

TikTok Integration

PostPal now supports TikTok integration for video publishing. To enable TikTok functionality:

Environment Variables

Add the following environment variables to your .env.local file:

# TikTok API Configuration
TIKTOK_CLIENT_KEY=your_tiktok_client_key_here
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret_here
TIKTOK_REDIRECT_URI=http://localhost:3000/api/tiktok/callback

Setup Instructions

1. Create a TikTok App: Visit the TikTok for Developers portal
2. Register your app and get your Client ID and Client Secret
3. Configure OAuth Redirect URI to match your TIKTOK_REDIRECT_URI
4. Request necessary permissions for video upload and publishing
5. Add environment variables to your project

Features

• Video Upload: Upload and publish videos directly to TikTok
• Content Management: Schedule and manage TikTok content
• Multi-Platform Publishing: Publish the same content across multiple platforms
• Analytics Integration: Track performance across all connected platforms

API Endpoints

• GET /api/tiktok/auth - Initiate TikTok OAuth flow
• GET /api/tiktok/callback - Handle OAuth callback
• POST /api/tiktok/post - Upload and publish videos

Usage

1. Connect your TikTok account in the Connections page
2. Create content using the Content Creator
3. Select TikTok as a platform
4. Upload your video and add description
5. Publish directly to TikTok

Limitations

• TikTok API requires special approval for video publishing
• Video files must be in MP4 format
• Maximum video duration and file size limits apply
• Some features may require additional permissions