Create Post

Endpoint

POST https://api.postpeer.dev/v1/posts

Request Body

Field	Type	Required	Description
`content`	string	Yes	The text body of your post
`publishNow`	boolean	Yes*	Set to `true` to publish immediately
`scheduledFor`	string	No	ISO 8601 datetime for scheduled posts
`timezone`	string	No	IANA timezone (default: `"UTC"`)

*Required when scheduledFor is not provided.

`platforms` (required)

An array of platform targets (min 1).

Field	Type	Required	Description
`platform`	string	Yes	`"twitter"`, `"instagram"`, `"youtube"`, `"tiktok"`, `"pinterest"`, `"linkedin"`, or `"reddit"`
`accountId`	string	Yes	Integration ID from `/v1/connect/integrations`
`platformSpecificData`	object	No	Platform-specific options (see Platforms)

`mediaItems` (optional)

An array of media attachments.

Field	Type	Required	Description
`type`	string	Yes	`"image"`, `"video"`, or `"gif"`
`url`	string	Yes	Public URL to the media file
`thumbnail`	string	No	Thumbnail URL (YouTube only)

Example: Publish Now

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Launching our new feature today!",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" },
      { "platform": "instagram", "accountId": "def456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/image.png" }
    ],
    "publishNow": true
  }'

Example: Cross-Post to Multiple Platforms

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out our latest video!",
    "platforms": [
      { "platform": "twitter", "accountId": "tw_123" },
      { "platform": "youtube", "accountId": "yt_456", "platformSpecificData": { "title": "Our Latest Video", "privacyStatus": "public" } }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://example.com/video.mp4" }
    ],
    "publishNow": true
  }'

Response

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

Status Codes

Code	Meaning
`202`	Post accepted — published, scheduled, partial, or failed
`400`	Validation error (bad request body)
`402`	Not enough credits
`403`	Forbidden
`503`	Scheduling unavailable

Partial Failures

When posting to multiple platforms, some may succeed and others fail. A 202 response with "status": "partial" includes per-platform results:

{
  "success": true,
  "status": "partial",
  "postId": "post_abc123",
  "platforms": [
    { "platform": "twitter", "success": true, "platformPostUrl": "..." },
    { "platform": "instagram", "success": false, "error": "Image URL is not publicly accessible" }
  ]
}

Failed platform posts don't consume credits.

On this page