API Reference / Posts

Create a draft

PostPiper API: create an unpublished post draft with text and/or images for X or LinkedIn, or one video for TikTok. Draft creation does not publish the post.

POSThttps://api.postpiper.ai/v1/posts

Provide text or at least one image attachment. The selected account must be active and owned by you. If platform is omitted, it comes from the account, or defaults to x.

Use either media_urls or asset_ids in one request. Uploaded asset IDs support X drafts. Draft creation does not publish the post.

Request body

NameTypeDescription
platform_fieldsobject, optionalOptional platform-specific fields.
account_idUUID, optionalConnected account to use later when publishing or scheduling.
platformstring, optionalLowercase platform identifier; must match account_id when supplied.
contentstring, optionalPost text, up to 25,000 characters. Required unless an attachment is supplied.
media_urlsstring[], optionalPublic HTTPS image URLs. Up to 4 for X, 20 for LinkedIn or other draft platforms.
asset_idsUUID[], optionalUp to 4 owned image assets from Media endpoints for X drafts.

Example request

Terminal
curl -X POST "https://api.postpiper.ai/v1/posts" \
  -H "Authorization: Bearer $POSTPIPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"<account-uuid>","content":"Hello from PostPiper"}'

Response

201 Created. Returns the draft post.

JSON
{
  "post": {
    "id": "<post-uuid>",
    "content": "Hello from PostPiper",
    "media_urls": [],
    "asset_ids": [],
    "platform": "x",
    "status": "draft",
    "account_id": "<account-uuid>",
    "created_at": "2030-10-12T01:00:00.000Z"
  }
}

Errors

  • 400INVALID_CONTENT, MEDIA_FORMAT_CONFLICT, PLATFORM_MISMATCH, or TOO_MANY_MEDIA.
  • 401Missing or invalid API key.
  • 403API key lacks the required scope.
  • 404ACCOUNT_NOT_FOUND or MEDIA_NOT_FOUND.