Getting Started

Get up and running with the PostPeer API in minutes. Connect a social account and publish your first post.

What is PostPeer?

PostPeer is a unified social media posting API. One integration to publish, schedule, and manage content across Twitter/X, Instagram, YouTube, Facebook, and more.

No OAuth headaches. No platform SDKs. One API, every platform.

Base URL:

https://api.postpeer.dev/v1

Authentication

All clients use the same access key. The SDKs read POSTPEER_API_KEY automatically.

curl https://api.postpeer.dev/v1/health/auth \
  -H "x-access-key: YOUR_API_KEY"

npm install @postpeer/node
export POSTPEER_API_KEY="YOUR_API_KEY"

pip install postpeer
export POSTPEER_API_KEY="YOUR_API_KEY"

Get your API key from the PostPeer Dashboard. You get 20 free credits on signup — no credit card required.

Step 1: Create a Profile (Optional)

A profile is a label that groups one or more connected social accounts. It's optional — you can skip straight to step 2 — but creating one before the connect step lets your backend know exactly which integration was just created (filter /v1/connect/integrations?profileId=... after the OAuth completes). Useful when your end-users connect their own accounts from your app.

curl -X POST https://api.postpeer.dev/v1/profiles \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co" }'

Response:

{
	"success": true,
	"profile": {
		"id": "65ab123",
		"name": "Acme Co",
		"description": null,
		"integrationCount": 0,
		"createdAt": "2026-05-03T08:33:36.445Z",
		"updatedAt": "2026-05-03T08:33:36.445Z"
	}
}

Save profile.id — you'll pass it as profileId in the next step. Full reference: Profiles.

Connect a social account via OAuth. Pass profileId if you created one in step 1; otherwise omit it.

curl https://api.postpeer.dev/v1/connect/{platform} \
  -H "x-access-key: YOUR_API_KEY"

For example, to connect Twitter:

curl "https://api.postpeer.dev/v1/connect/twitter?profileId=65ab123" \
  -H "x-access-key: YOUR_API_KEY"

Response:

{
	"url": "https://twitter.com/i/oauth2/authorize?..."
}

Redirect the user to the url. After they authorize, the account is connected to your project (and bound to the profile if you passed one).

Step 3: Get Your Account ID

List your connected accounts to get the accountId needed for posting. If you used a profile, filter to it so you see only the integration you just created:

curl "https://api.postpeer.dev/v1/connect/integrations?profileId=65ab123" \
  -H "x-access-key: YOUR_API_KEY"

Response:

{
	"success": true,
	"integrations": [
		{
			"id": "abc123",
			"platform": "twitter",
			"platformUserId": "123456789",
			"profileId": "65ab123",
			"createdAt": "2026-03-28T10:00:00Z"
		}
	]
}

Step 4: Publish Your First Post

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from PostPeer! 🚀",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123"
      }
    ],
    "publishNow": true
  }'

import PostPeer from '@postpeer/node';

const client = new PostPeer();
const { data } = await client.posts.create({
	body: {
		content: 'Hello from PostPeer! 🚀',
		platforms: [{ platform: 'twitter', accountId: 'abc123' }],
		publishNow: true,
	},
});

from postpeer import PostPeer

with PostPeer() as client:
    post = client.posts.create(
        content="Hello from PostPeer! 🚀",
        platforms=[{"platform": "twitter", "accountId": "abc123"}],
        publish_now=True,
    )

Response:

{
	"success": true,
	"status": "published",
	"postId": "post_xyz789",
	"platforms": [
		{
			"platform": "twitter",
			"success": true,
			"platformPostUrl": "https://twitter.com/you/status/123456"
		}
	]
}

That's it — one request, your content is live.

Step 5: Schedule a Post (Optional)

Want to post later? Add scheduledFor and timezone:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This goes live tomorrow morning!",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "scheduledFor": "2026-03-29T09:00:00",
    "timezone": "America/New_York"
  }'

const { data } = await client.posts.create({
	body: {
		content: 'This goes live tomorrow morning!',
		platforms: [{ platform: 'twitter', accountId: 'abc123' }],
		scheduledFor: '2026-03-29T09:00:00',
		timezone: 'America/New_York',
	},
});

post = client.posts.create(
    content="This goes live tomorrow morning!",
    platforms=[{"platform": "twitter", "accountId": "abc123"}],
    scheduled_for="2026-03-29T09:00:00",
    timezone="America/New_York",
)

Supported Platforms

PostPeer supports publishing to all major social platforms:

Platform	Status	Features
Twitter/X	Live	Posts, threads, polls, images, videos, GIFs
YouTube	Live	Video uploads, Shorts, metadata
LinkedIn	Live	Posts, images, videos
Pinterest	Live	Pins with images
Bluesky	Live	Text posts, images, link cards
TikTok	Live	Videos, photos, photo carousels
Instagram	Live	Feed posts, Reels, carousels
Facebook	Live	Posts, photos, photo carousels, videos, link previews
Threads	Live	Text, images, image carousels, videos

Next Steps

Authentication — API keys, credits, and rate limits
Connect Accounts — OAuth flows for each platform
Publishing — Full request/response reference
Scheduling — Schedule, cancel, and reschedule posts

On this page