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 requests require your API key in the x-access-key header:

curl https://api.postpeer.dev/v1/health/auth \
  -H "x-access-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
  }'

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"
  }'

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	Video uploads
Instagram	Coming soon	Image posts with captions
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