PostEverywhere Account Connection Guide

Everything else in this API assumes a connected social account. This page is how you get one without touching the dashboard: from a script, a CLI, or an AI agent (the MCP tools create_connect_link, create_reconnect_link, and connect_credential_account wrap these endpoints).

There are two connection styles, decided by the platform:

Style	Platforms	Browser needed?
OAuth connect link	x, instagram, facebook, youtube, pinterest, threads, linkedin, tiktok, google_business	One click by the account owner (the platform's own consent screen; that hop is imposed by the platforms, not us)
Direct credentials	telegram, discord, bluesky	None. Fully in-API

Connect an OAuth platform with a hosted link: POST /v1/accounts/connect-link#

curl -X POST https://app.posteverywhere.ai/api/v1/accounts/connect-link \
  -H "Authorization: Bearer pe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram"}'

{
  "data": {
    "platform": "instagram",
    "url": "https://www.instagram.com/oauth/authorize?...",
    "expires_in_seconds": 600,
    "instructions": "Have the instagram account owner open this URL in any browser within 10 minutes..."
  },
  "error": null
}

The flow, gh auth login style:

1. Mint the link (requires the write scope; expires in 10 minutes).
2. Hand it to the account owner. They can open it in any browser; they do not need to be logged in to PostEverywhere there, since the link carries a signed, single-org grant of who initiated it.
3. They approve on the platform's consent screen.
4. The account lands in your organization. Poll GET /v1/accounts until the new account appears (typically seconds after approval), then post to it.

Security properties: the link is HMAC-signed and bound to your organization and workspace, expires after 10 minutes, and can only ever ADD an account to the organization that minted it. It grants the clicker nothing. Treat it like any invite link: send it to the account owner directly, not somewhere public.

Connect a credential platform such as Telegram, Discord or WordPress: POST /v1/accounts/connect-credential#

No browser, validated live against the platform before saving:

# Telegram: bot from @BotFather, bot must be an ADMIN of the channel
curl -X POST .../v1/accounts/connect-credential \
  -H "Authorization: Bearer pe_live_..." -H "Content-Type: application/json" \
  -d '{"platform": "telegram", "bot_token": "123456:ABC...", "channel": "@mychannel"}'

# Discord: Server Settings > Integrations > Webhooks
  -d '{"platform": "discord", "webhook_url": "https://discord.com/api/webhooks/..."}'

# Bluesky: Settings > App Passwords (never the main account password)
  -d '{"platform": "bluesky", "handle": "me.bsky.social", "app_password": "xxxx-xxxx-xxxx-xxxx"}'

# WordPress (self-hosted, 5.6+, HTTPS): Users > Profile > Application Passwords
  -d '{"platform": "wordpress", "site_url": "https://example.com", "username": "editor", "app_password": "abcd efgh ijkl mnop qrst uvwx"}'

WordPress refuses a normal login password (WP_NOT_APP_PASSWORD) and checks the user can publish posts and upload media. WordPress.com sites connect in the dashboard with a WordPress.com login; connect-link returns 400 credential_platform for WordPress. See the WordPress guide.

Bad credentials return a 4xx with the platform's reason in error.details (400 for Telegram, 401 for Discord and Bluesky, 409 if another organization already holds the account), so agents can self-correct. Re-submitting credentials for an already-connected account updates it in place: that is also how these platforms reconnect.

Reconnect an account whose token expired: POST /v1/accounts/{id}/reconnect#

When GET /v1/accounts/{id}/health reports needs_reconnection or token_expired, mint a repair link:

curl -X POST https://app.posteverywhere.ai/api/v1/accounts/1234/reconnect \
  -H "Authorization: Bearer pe_live_..."

Same mechanics as connect-link, with one rule: the owner must approve while logged in to the platform as that same profile. Matching is by the platform's account id: authorizing as a different profile connects a new account instead of repairing this one. Verify with the health endpoint afterwards.

Connecting accounts from an AI agent#

• list_accounts before and after is the confirmation loop: mint link, wait for the human, poll until the platform appears, then proceed to posting.
• A connect link that expires unclicked costs nothing; mint a fresh one.
• Connecting an account someone ELSE's PostEverywhere workspace already holds is blocked by an anti-hijack guard; the human will see an explanatory error and should contact support if they believe they own the account.

Full account endpoint reference#

Every connect flow, headless: Create connect link · Create reconnect link · Connect credential account · Start social connect · Poll social connect.

Related: checking an account can post · test accounts · Instagram API guide · Bluesky app-password connect · the Discord guide · the Telegram guide