# WoopSocial

> WoopSocial is a social media management platform and unified API for scheduling and publishing posts across Facebook, Instagram, Threads, BlueSky, LinkedIn, LinkedIn Pages, Pinterest, TikTok, X/Twitter, and YouTube. It offers a web UI, a REST API, and a Model Context Protocol (MCP) server — so humans, apps, and AI agents can all manage social content from one place.

Important notes:

- WoopSocial's core job is creating, scheduling, and publishing social media posts across 9 platforms from a single API call.
- The REST API and MCP server share the same backend. Choose MCP when connecting an AI agent; choose the API for server-to-server integrations, webhooks, and custom apps.
- WoopSocial does **not** require you to bring your own platform API keys. OAuth connections are managed through the dashboard or API.
- All plans — including Free — include full API and MCP access with unlimited posts (X/Twitter moves to credit-based posting after complimentary posts).
- WoopSocial also integrates with Zapier and n8n for no-code automation workflows.

## API Quick Reference

Base URL: `https://api.woopsocial.com/v1`

Authentication — all endpoints require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key at https://app.woopsocial.com/api-access

OpenAPI spec: https://docs.woopsocial.com/openapi.yaml

### Core Workflow

1. **Get your Project ID** — `GET /projects` (a project maps to a "Business Profile" in the UI)
2. **List connected social accounts** — `GET /social-accounts`
3. **Upload media** (optional) — `POST /media/upload-sessions` for chunked uploads up to 5 GB, or `POST /media` for single-request uploads
4. **Create a post** — `POST /posts`
5. **Monitor delivery** — use webhooks (`POST /webhooks/endpoints`) or poll `GET /posts/{id}`

### Create Post — Minimal Example

```json
POST /posts
{
  "content": [{ "text": "Hello from WoopSocial! 🚀" }],
  "schedule": { "type": "PUBLISH_NOW" },
  "socialAccounts": [
    {
      "platform": "LINKEDIN",
      "socialAccountId": "YOUR_SOCIAL_ACCOUNT_ID"
    }
  ]
}
```

Schedule types: `DRAFT`, `PUBLISH_NOW`, `SCHEDULE_FOR_LATER` (requires `scheduledFor` in ISO 8601 UTC).

### Create Post — Multi-Platform with Media and Content Override

```json
POST /posts
{
  "content": [
    {
      "text": "Check out our new feature!",
      "media": [{ "type": "MEDIA_LIBRARY", "mediaId": "MEDIA_ID" }]
    }
  ],
  "schedule": {
    "type": "SCHEDULE_FOR_LATER",
    "scheduledFor": "2026-07-01T14:00:00Z"
  },
  "socialAccounts": [
    {
      "platform": "INSTAGRAM",
      "socialAccountId": "IG_ACCOUNT_ID",
      "postType": "REEL"
    },
    {
      "platform": "X",
      "socialAccountId": "X_ACCOUNT_ID"
    },
    {
      "platform": "LINKEDIN_PAGES",
      "socialAccountId": "LI_PAGE_ID",
      "contentOverride": [{ "text": "Professional version of the announcement." }]
    }
  ],
  "autoDeleteMediaAfterPublish": true
}
```

Each social account entry can include `contentOverride` to tailor the text per platform.

### Connect a New Social Account via OAuth

```
POST /social-accounts/oauth
```

Returns an `authUrl` to open in the browser. After the user authorizes, the account is connected to the specified project.

### Key API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /projects | List projects (business profiles) |
| POST | /projects | Create a project |
| DELETE | /projects/{id} | Delete project and all related data |
| GET | /social-accounts | List connected accounts |
| POST | /social-accounts/oauth | Generate OAuth URL to connect an account |
| GET | /social-accounts/{id}/platform-inputs | Get platform-specific options (boards, privacy levels, categories) |
| DELETE | /social-accounts/{id} | Disconnect an account |
| POST | /posts | Create a post |
| GET | /posts/{id} | Get post with delivery status |
| DELETE | /posts/{id} | Delete a scheduled post |
| POST | /posts/validate | Validate without creating |
| GET | /social-account-posts | List social account posts |
| DELETE | /social-account-posts/{id} | Delete a social account post |
| POST | /media | Upload media (single request) |
| POST | /media/upload-sessions | Start chunked upload session (up to 5 GB) |
| POST | /media/upload-sessions/{id}/complete | Finalize chunked upload |
| GET | /media | List media library |
| DELETE | /media/{id} | Delete media item |
| POST | /webhooks/endpoints | Register a webhook |
| GET | /webhooks/endpoints | List webhooks |
| DELETE | /webhooks/endpoints/{id} | Delete a webhook |
| GET | /health | API connectivity check |

### Error Responses

All errors return JSON with `code` and `message`. Post creation additionally returns `validationErrors` with JSON paths to invalid fields.

Error codes for post creation: `INVALID_SOCIAL_ACCOUNT_ID`, `SOCIAL_ACCOUNT_NOT_CONNECTED`, `SOCIAL_ACCOUNTS_MUST_BELONG_TO_SAME_PROJECT`, `DUPLICATE_SOCIAL_ACCOUNT_ID`, `INVALID_MEDIA_ID`, `INVALID_PLATFORM_SPECIFIC_DATA`, `VALIDATION_FAILED`, `INTERNAL_ERROR`.

## MCP Server

WoopSocial exposes a Model Context Protocol server so AI assistants and autonomous agents can manage social content with structured tools.

| Item | Value |
|------|-------|
| MCP URL | `https://api.woopsocial.com/mcp` |
| Transport | Streamable HTTP |
| Auth | OAuth (automatic) or API key fallback: `https://api.woopsocial.com/mcp?api_key=YOUR_API_KEY` |

The MCP server exposes these tools:

**Posts:** `posts_create`, `posts_validate`, `posts_get`, `posts_delete`, `social_account_posts_list`, `social_account_posts_delete`

**Projects:** `projects_create`, `projects_list`, `projects_delete`

**Social Accounts:** `oauth_create_authorization`, `social_accounts_list`, `social_accounts_delete`, `social_accounts_get_platform_inputs`

**Media:** `media_list`, `media_delete`, `media_uploads_create_session`, `media_uploads_get_session`, `media_uploads_complete_session`

**Webhooks:** `webhooks_create_endpoint`, `webhooks_list_endpoints`, `webhooks_delete_endpoint`

**Health:** `health_get`

Note: For media uploads via MCP, presigned URLs are hosted on Cloudflare. If your MCP client restricts domains, add `r2.cloudflarestorage.com` to its allowlist.

### MCP Client Setup

- **Claude Desktop / Claude.ai**: Add the MCP URL in Settings → Connectors or use the API key URL
- **Claude Code**: `claude mcp add woopsocial https://api.woopsocial.com/mcp`
- **Cursor**: Add to MCP settings in `.cursor/mcp.json`
- **ChatGPT**: Use the MCP URL with API key auth

Full client integration guide: https://docs.woopsocial.com/mcp/integrating-clients

## Platform-Specific Requirements

### Facebook
- `postType` required: `TEXT_ONLY`, `IMAGE`, `VIDEO`, or `REEL`
- Optional `link` field for link previews
- Cannot mix images and videos in a single post

### Instagram
- `postType` required: `POST`, `REEL`, or `STORY`
- Stories require media; text-only stories are not supported
- Requires a connected Business or Creator account

### Threads
- Text posts and image posts supported
- Requires a connected Threads account linked to Instagram

### BlueSky
- Text posts and image posts supported
- Requires a connected BlueSky account

### LinkedIn / LinkedIn Pages
- Optional `link` field for link preview cards
- LinkedIn and LinkedIn Pages are separate platform types in the API

### Pinterest
- `pinterestBoardId` required — use `GET /social-accounts/{id}/platform-inputs` to list available boards
- Optional `title` (max 100 chars) and `link` (max 2048 chars)
- Single image or single video per Pin

### TikTok
- `postType` required: `VIDEO` or `PHOTO`
- Required fields: `privacyLevel`, `allowComment`, `allowDuet`, `allowStitch`, `isYourBrand`, `isBrandedContent`, `autoAddMusic`
- Privacy levels: `PUBLIC_TO_EVERYONE`, `SELF_ONLY`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`
- Use `GET /social-accounts/{id}/platform-inputs` to discover which privacy levels are available for the connected account

### X (Twitter)
- No additional platform-specific fields required
- X/Twitter posting includes complimentary posts, then moves to credit-based

### YouTube
- `title` and `privacy` required
- Privacy: `public`, `private`, `unlisted`
- Optional: `category`, `tags`, `madeForKids`
- Requires at least one video in media

## Pricing

All plans include unlimited posts, unlimited projects, full API & MCP access, AI content generation, and all 9 supported platforms.

| Plan | Price | Social Accounts | Cost per Account | Credits/mo | Seats | Storage |
|------|-------|-----------------|------------------|------------|-------|---------|
| Free | $0/mo | 2 | $0.00 | 30 | 1 | 1 GB |
| Pro | $19/mo | 20 | $0.95 | 1,000 | 1 | 10 GB |
| Business | $49/mo | 100 | $0.49 | 5,000 | 3 | 25 GB |
| Max | $799/mo | 2,500 | $0.32 | 42,000 | 43 | 420 GB |

Pro, Business, and Max plans support "stacking" — purchasing the same plan multiple times to add accounts, credits, seats, and storage.

Signup (free, no credit card): https://app.woopsocial.com/signup

## Documentation

- [API Overview](https://docs.woopsocial.com/api-reference/overview): Base URL, authentication, and getting started.
- [API Onboarding](https://docs.woopsocial.com/api-reference/api-onboarding): Step-by-step first post guide for API, Zapier, and n8n.
- [Create Post](https://docs.woopsocial.com/api-reference/posts/create-post): Full OpenAPI schema for the post creation endpoint.
- [Validate Post](https://docs.woopsocial.com/api-reference/posts/validate-post): Dry-run validation without creating.
- [Get Post](https://docs.woopsocial.com/api-reference/posts/get-post): Retrieve a post with delivery status.
- [Delete Post](https://docs.woopsocial.com/api-reference/posts/delete-post): Remove a scheduled post.
- [List Social Account Posts](https://docs.woopsocial.com/api-reference/posts/list-social-account-posts): Query individual platform deliveries.
- [Delete Social Account Post](https://docs.woopsocial.com/api-reference/posts/delete-social-account-post): Remove a single platform delivery.
- [List Projects](https://docs.woopsocial.com/api-reference/projects/list-projects): Discover business profiles.
- [Create Project](https://docs.woopsocial.com/api-reference/projects/create-project): Add a new business profile.
- [Delete Project](https://docs.woopsocial.com/api-reference/projects/delete-project): Remove a project and all related data.
- [List Social Accounts](https://docs.woopsocial.com/api-reference/social-accounts/list-social-accounts): Connected accounts available for publishing.
- [Generate OAuth URL](https://docs.woopsocial.com/api-reference/social-accounts/generate-oauth-url): Start OAuth flow to connect a new account.
- [Get Platform Inputs](https://docs.woopsocial.com/api-reference/social-accounts/get-platform-specific-input-options): Discover boards, privacy levels, categories per account.
- [Delete Social Account](https://docs.woopsocial.com/api-reference/social-accounts/delete-social-account): Disconnect an account.
- [Upload Media](https://docs.woopsocial.com/api-reference/media/upload-media): Single-request upload.
- [Start Upload Session](https://docs.woopsocial.com/api-reference/media/start-media-upload-session): Chunked upload for large files (up to 5 GB).
- [Complete Upload Session](https://docs.woopsocial.com/api-reference/media/complete-media-upload-session): Finalize a chunked upload.
- [Get Upload Session Status](https://docs.woopsocial.com/api-reference/media/get-media-upload-session-status): Check upload progress.
- [List Media](https://docs.woopsocial.com/api-reference/media/list-media): Browse the media library.
- [Delete Media](https://docs.woopsocial.com/api-reference/media/delete-media): Remove a media item.
- [Register Webhook](https://docs.woopsocial.com/api-reference/webhooks/register-webhook-endpoint): Subscribe to post delivery events.
- [List Webhooks](https://docs.woopsocial.com/api-reference/webhooks/list-webhook-endpoints): View registered endpoints.
- [Delete Webhook](https://docs.woopsocial.com/api-reference/webhooks/delete-webhook-endpoint): Remove a webhook.
- [Health Check](https://docs.woopsocial.com/api-reference/health/health-check): Verify API connectivity.
- [OpenAPI Spec](https://docs.woopsocial.com/openapi.yaml): Machine-readable OpenAPI 3.x specification.
- [API Docs llms.txt](https://docs.woopsocial.com/llms.txt): Machine-readable index of all API documentation pages.

## MCP Documentation

- [MCP Overview](https://docs.woopsocial.com/mcp/overview): Server endpoint, auth, and capabilities.
- [MCP Client Integration](https://docs.woopsocial.com/mcp/integrating-clients): Setup for Claude Desktop, Claude Code, Cursor, ChatGPT, and other clients.
- [MCP Tools Reference](https://docs.woopsocial.com/mcp/tools-reference): Complete list of MCP tool names and descriptions.

## Integrations

- [Zapier](https://zapier.com/apps/woopsocial/integrations): No-code automation with WoopSocial.
- [n8n](https://www.npmjs.com/package/@woopsocial/n8n-nodes-woopsocial): Workflow automation nodes for n8n.
- [Cursor Plugin](https://cursor.directory/plugins/woopsocial-social-media-scheduler): WoopSocial plugin for Cursor IDE.

## Optional

- [Homepage](https://woopsocial.com/): Product overview and value proposition.
- [Pricing](https://woopsocial.com/pricing): Full plan comparison and FAQ.
- [Social Media MCP Landing Page](https://woopsocial.com/social-media-mcp): Marketing page for MCP capabilities.
- [Blog](https://woopsocial.com/blog): Social media strategy, automation workflows, and guides.
- [Free Marketing Tools](https://woopsocial.com/tools): UTM builder, engagement calculators, AI post generators, image resizers.
- [About](https://woopsocial.com/about): Team and company information.
- [Contact](https://woopsocial.com/contact): Support and inquiries.
- [Affiliate Program](https://woopsocial.com/affiliate): 30% recurring commission on referrals.
- [X/Twitter Channel Page](https://woopsocial.com/x-twitter): Platform-specific feature details.
- [LinkedIn Channel Page](https://woopsocial.com/linkedin): Platform-specific feature details.
- [Pinterest Channel Page](https://woopsocial.com/pinterest): Platform-specific feature details.
- [Instagram Channel Page](https://woopsocial.com/instagram): Platform-specific feature details.
- [BlueSky Channel Page](https://woopsocial.com/bluesky): Platform-specific feature details.
- [Facebook Channel Page](https://woopsocial.com/facebook): Platform-specific feature details.
- [TikTok Channel Page](https://woopsocial.com/tiktok): Platform-specific feature details.
- [YouTube Channel Page](https://woopsocial.com/youtube): Platform-specific feature details.