Developers · API · MCP

Build on PurrPlan.

A REST API and a native MCP server to schedule, publish and drive your 12 networks from your code, your AI agent (Claude, Cursor…) or your terminal.

Connect to Claude / Cursor See the REST API

REST · /app/api MCP · /api/mcp JSON-RPC 2.0 · 2025-06-18

01 · Authentication

One token, two surfaces.

The same bearer token opens the REST API and the MCP server. Create it in 30 seconds from your account, with the scopes you choose.

1. Open app.purrplan.ai/app/mcp-integration
2. Create a token: name, expiration (30/90/365 days or never), and the scopes you want.
3. Copy the token (shown only once) and pass it as a header.

# auth header (REST & MCP)

Authorization: Bearer $TOKEN

# bases

REST app.purrplan.ai/app/api

MCP app.purrplan.ai/api/mcp

OAuth-compatible MCP clients can also register a client dynamically (DCR + PKCE) on /app/oauth.

02 · REST API

Create and schedule over HTTP.

Base https://app.purrplan.ai/app/api. The {workspace} is the uuid of your workspace.

Method	Endpoint	Role
GET	/me	Current user
GET	/workspaces	Your workspaces
GET	/{workspace}/accounts	Connected social accounts
GET	/{workspace}/posts	List posts (paginated)
POST	/{workspace}/posts	Create a post (draft, scheduled, queued or immediate)
POST	/{workspace}/posts/schedule/{post}	Schedule an existing post
POST	/{workspace}/posts/add-to-queue/{post}	Add to the next open slot
GET	/{workspace}/media	Media library
POST	/{workspace}/media	Upload media
POST	/{workspace}/ai/text/generate	Generate text with AI

Example — create & schedule a post

# POST /app/api/{workspace}/posts curl -X POST https://app.purrplan.ai/app/api/$WS/posts \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "accounts": [12, 18], "date": "2026-07-25", "time": "09:30", "timezone": "Europe/Paris", "schedule": true, "versions": [ { "account_id": 0, "is_original": true, "content": [{ "body": "Our product is here 🎉" }] } ] }'

201 → the post (uuid, versions, scheduled_at)

account_id: 0 = "original" version applied to all. Replace schedule with queue: true (next open slot) or schedule_now: true (immediate publishing). Without a date or flag → draft.

03 · MCP Server

Plug in your AI agent.

Native MCP server (Model Context Protocol, spec 2025-06-18, JSON-RPC 2.0 over HTTP + SSE). Connect Claude Desktop, Cursor or any MCP client and let your AI plan for you — with permissions you control.

Client config (URL + Bearer)

{ "mcpServers": { "purrplan": { "url": "https://app.purrplan.ai/api/mcp", "headers": { "Authorization": "Bearer $TOKEN" } } } }

stdio-only client? Use a bridge like mcp-remote.

7 tools · required scope

list_workspaces read

Lists your workspaces.

—

list_accounts read

Connected social accounts (id, provider…).

workspace_uuid

list_posts read

List of posts (content, status, date).

workspace_uuid, status?, limit?

get_post read

Post details (versions per network).

workspace_uuid, post_uuid

generate_ai_text ai

Generates a post text (consumes credits).

workspace_uuid, prompt, tone?…

create_draft_post write

Creates a post — draft, or scheduled if scheduled_at.

workspace_uuid, account_ids, content, scheduled_at?

upload_media_from_url media

Ingests media from a public URL.

workspace_uuid, url, type?

Scopes

Grant exactly what's needed.

read Read — workspaces, accounts, posts

write Write — create / schedule posts

ai AI — text generation (consumes credits)

media Media — upload, library management

Limits

Default rate limits.

REST & MCP API 100 requests / min / user

AI generation 20 / min / user

Media upload 30 / min / user

OAuth (token) 10 / min / IP

Exceeded → 429.

Ready to build?

Create your token and wire up your first call in minutes. From €9/month, 7-day trial.

Start for free Create a token