Quickstart
- Create a bearer token as an administrator.
- Store it server-side or in your MCP client.
- Use
POST /mcpor the REST endpoints. - Use a real site ID for site-scoped data.
POST https://pocketpapi.com/mcp Authorization: Bearer YOUR_TOKEN
Authentication
Authorization: Bearer YOUR_SITE_COMMANDER_TOKEN
Discovery
/mcp · /llms.txt · /.well-known/ai-plugin.json · /openapi.json · /api/control-plane/guide.md
Public effects catalog
The public catalog contains 63 recipes and requires no bearer token. It includes dependency-free native recipes for advanced motion plus free MIT-licensed library starters. The Help Center page provides a working preview for every recipe.
GET /api/effects?q=scroll
GET /api/effects/{effect_id}
POST /api/effects/compose
{"effect_id":"scroll-scrub-scale","target_selector":".hero-art","reduced_motion":true}
Open the full effects library and previews →
Control-plane reads
GET /api/control-plane/status GET /api/control-plane/projects GET /api/control-plane/sites GET /api/control-plane/easyapp GET /api/control-plane/sync-health GET /api/control-plane/tasks GET /api/control-plane/activity?site_id=SITE_ID GET /api/control-plane/conversations?site_id=SITE_ID GET /api/control-plane/messages?conversation_id=CONVERSATION_ID GET /api/control-plane/tickets?site_id=SITE_ID GET /api/control-plane/ticket-messages?ticket_id=TICKET_ID
Sender photos and BIMI
Manage site-scoped sender profiles and domain-level BIMI from the authenticated site page or the bearer API. Hosted sender photos are available to systems that support public avatar assets; they cannot override recipient-managed Gmail, Microsoft 365, or Outlook contact photos.
GET /api/control-plane/mail/profiles?site_id=SITE_ID POST /api/control-plane/mail/profiles GET /api/control-plane/bimi/status?site_id=SITE_ID POST /api/control-plane/bimi/prepare POST /api/control-plane/bimi/verify GET /api/control-plane/bimi/record?site_id=SITE_ID
Use photo_base64 for a PNG, JPEG, or WebP up to 4 MB. Use svg_base64 for a validated SVG Tiny PS logo and certificate_pem_base64 for an optional VMC/CMC chain. The prepare response gives the DNS name and TXT record; PocketPapi never changes DNS.
{"site_id":123,"sender_email":"hello@example.com","sender_name":"Example Company","photo_base64":"data:image/png;base64,..."}
{"site_id":123,"selector":"default","dkim_selector":"resend","avatar_preference":"brand","svg_base64":"data:image/svg+xml;base64,..."}
The verify response distinguishes `ready`, `yahoo_eligible`, and `not_ready`. Gmail generally needs a VMC or CMC for BIMI display; Yahoo also considers volume, reputation, and engagement; Outlook profile photos are normally controlled by the Microsoft account, Exchange directory, or contact.
Activity and custom fields
Send messages, subscriptions, contacts, and leads with your own taxonomy:
POST /api/control-plane/events
{"site_id":123,"type":"message","external_id":"crm-8842","category":"support","subcategory":"billing","folder":"vip","source":"contact-widget","status":"open","priority":"high","tags":["enterprise"],"custom_fields":{"plan":"pro"},"message":"I need help."}
Additional keys are preserved as metadata. Duplicate external IDs for the same site are ignored.
Site-scoped server connection
Open a site's details in the authenticated command center and choose Connect site to command center. The owner receives a site-scoped scc_... bearer token exactly once. Store it in the site's server environment and rotate it from the same page if it is lost or exposed. It cannot access another site or the protected internal Current Site workspace.
COMMAND_CENTER_URL=https://YOUR-COMMAND-CENTER.example.com
SITE_COMMANDER_SITE_ID=123
SITE_COMMANDER_TOKEN=scc_...
POST /api/control-plane/events
Authorization: Bearer SITE_COMMANDER_TOKEN
{"site_id":123,"type":"lead","source":"website-form","email":"jordan@example.com","message":"Please call me."}
Use this credential for site-scoped REST reads, approved chat replies, and POST /mcp. The command center records the interface, action, site, result, duration, and safe error text in Audit Logs.
Google reviews
GET /api/control-plane/reviews?site_id=SITE_ID GET /api/control-plane/zernio/reviews?site_id=SITE_ID POST /api/control-plane/reviews/reply
Conversations and support tickets
Website conversations and their messages are shared across the visitor widget, Support Inbox, MCP, API, and PocketPapi mobile app. Support tickets created from the site are available through the tickets and ticket-messages reads.
POST /api/control-plane/messages/reply
{"conversation_id":456,"message":"Thanks — we will follow up.","metadata":{"category":"support","folder":"vip"}}
PocketPapi mobile client
PocketPapi is the shared iOS and Android client for connected sites. Public sites appear automatically; private sites are added with a configuration code generated by the site owner in Apps. Discovery is not data access: users still sign in with an existing site workspace account before the app can load leads or reply to live chats.
GET /api/easyapp/sites
POST /api/easyapp/configure
{"configuration_code":"EA-..."}
POST /api/easyapp/auth/login
{"site_key":"...","email":"owner@example.com","password":"..."}
Authorization: Bearer EA_TOKEN
GET /api/easyapp/me
GET /api/easyapp/leads
POST /api/easyapp/leads/status
GET /api/easyapp/conversations
GET /api/easyapp/messages?conversation_id=456
POST /api/easyapp/messages/reply
PocketPapi sessions expire after 30 days and are stored only as hashes. Never put an MCP token in a mobile bundle. Replies are written to the same conversation records used by the website widget and Support Inbox.
Authorized MCP/API clients can idempotently prepare the connected app workspace from the builder without receiving private configuration codes or signing credentials:
POST /api/control-plane/easyapp
Authorization: Bearer SC_TOKEN
{"site_id":123,"app_name":"PocketPapi","enabled":true,"visibility":"private"}
MCP: sitecommander_easyapp_ensure
Optional PocketPapi command-center app
The Apps page also offers a standalone PocketPapi iOS/Android app for users who want the command center in a native shell. It uses the existing account, returns only accessible projects/sites/tasks/activity, and does not include the protected internal Current Site workspace.
POST /api/command-center/auth/login
{"email":"owner@example.com","password":"..."}
Authorization: Bearer SCM_TOKEN
GET /api/command-center/summary
GET /api/command-center/projects
GET /api/command-center/sites
GET /api/command-center/tasks
GET /api/command-center/activity
GET /api/command-center/integration-logs
The integration-log endpoint is permission-gated for administrator troubleshooting and never returns bearer tokens or request bodies.
Central Zernio gateway
GET /api/control-plane/zernio/accounts?site_id=SITE_ID GET /api/control-plane/zernio/reviews?site_id=SITE_ID POST /api/control-plane/zernio/posts?site_id=SITE_ID
The gateway uses encrypted central Zernio credentials, enforces site scope, and audit logs operations. It does not forward arbitrary Zernio URLs.
MCP
Connect to https://pocketpapi.com/mcp. Use sitecommander_api_guide to read the complete Markdown contract. Read tools include the token creator’s accessible projects/sites, status, tasks, activity, conversations, chat messages, support tickets, ticket messages, reviews, and Zernio accounts. sitecommander_send_message replies to live website chats and appears in the site widget and Support Inbox.
Security
- Bearer tokens are private credentials.
- Site-scoped requests require a site ID.
- The internal Current Site workspace is never exposed.
- Zernio keys are never returned.
- Gateway actions are audit logged.