Posts API

Create, schedule, and manage posts across all platforms.

Create Post

POST /v1/posts

Create and optionally publish a post to one or more platforms.

Request Body

{
  "content": "Hello from SocialSyncerAPI!",
  "mediaItems": [
    {"type": "image", "url": "https://example.com/photo.jpg"}
  ],
  "platforms": [
    {"platform": "instagram", "accountId": "ig_123"},
    {"platform": "twitter", "accountId": "tw_456"}
  ],
  "publishNow": true,
  "scheduledFor": null,
  "isDraft": false,
  "timezone": "UTC",
  "tags": ["marketing"],
  "tiktokSettings": {},
  "facebookSettings": {}
}

Fields

content — string — Post text/caption. Optional when media is attached or all platforms have customContent.
mediaItems — array — Array of media objects with type (image/video/gif) and url.
platforms — array — Array of platform targets. Required for non-draft posts.
publishNow — boolean — Publish immediately.
scheduledFor — string — ISO 8601 datetime for scheduled posts.
isDraft — boolean — Save as draft.
timezone — string — IANA timezone string (default: UTC).

 tags — array of strings — Tags for organization.
 tiktokSettings — object — Root-level TikTok settings (merged into all TikTok targets).
 facebookSettings — object — Root-level Facebook settings (merged into all Facebook targets).

 Platform Target
 {
  "platform": "instagram",
  "accountId": "ig_123",
  "customContent": "Platform-specific caption override",
  "customMedia": [{"type": "image", "url": "..."}],
  "platformSpecificData": {}
}
 Examples
 Python
 import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "Hello from SocialSyncerAPI!",
        "mediaItems": [
            {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
        ],
        "platforms": [
            {"platform": "instagram", "accountId": "ig_123"},
            {"platform": "twitter", "accountId": "tw_456"}
        ],
        "publishNow": True
    }
)
data = resp.json()
print(f"Post ID: {data['id']}, Status: {data['status']}")
 curl
 curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from SocialSyncerAPI!",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/photo.jpg"}
    ],
    "platforms": [
      {"platform": "instagram", "accountId": "ig_123"},
      {"platform": "twitter", "accountId": "tw_456"}
    ],
    "publishNow": true
  }'
 Node.js
 const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Hello from SocialSyncerAPI!",
    mediaItems: [
      { type: "image", url: "https://cdn.example.com/photo.jpg" }
    ],
    platforms: [
      { platform: "instagram", accountId: "ig_123" },
      { platform: "twitter", accountId: "tw_456" }
    ],
    publishNow: true
  })
});
const data = await resp.json();
console.log("Post ID:", data.id, "Status:", data.status);
 Response
 {
  "id": "post_abc123",
  "status": "published",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostId": "17841400123456789",
      "platformPostUrl": "https://instagram.com/p/ABC123"
    },
    {
      "platform": "twitter",
      "status": "published",
      "platformPostId": "1234567890",
      "platformPostUrl": "https://x.com/i/status/1234567890"
    }
  ],
  "createdAt": "2026-01-15T10:00:00Z"
}
 Error Responses
 // 400 - Invalid request
{
  "error": "content is required when no media is attached",
  "type": "invalid_request_error",
  "code": "missing_required_field",
  "param": "content"
}

// 401 - Unauthorized
{
  "error": "Invalid API key",
  "type": "authentication_error",
  "code": "invalid_credentials"
}

// 422 - Platform-specific error
{
  "error": "Instagram requires media for all posts",
  "type": "invalid_request_error",
  "code": "invalid_field_value",
  "param": "mediaItems"
}
  Idempotency: Include an Idempotency-Key header with a unique UUID to safely retry requests. The same key will return the original response without creating a duplicate post. Keys expire after 24 hours.
 List Posts
  GET /v1/posts 
 Returns a paginated list of posts.
 Query Parameters
  status — Filter by status: draft, scheduled, published, failed, partial
 platform — Filter by platform name (e.g. instagram, twitter)
 limit — Number of results per page (default: 20, max: 100)
 cursor — Pagination cursor from previous response
 fromDate — ISO 8601 date filter (inclusive)
 toDate — ISO 8601 date filter (inclusive)
 
 Example
 curl "https://api.socialsyncerapi.com/v1/posts?status=published&platform=instagram&limit=10" \
  -H "Authorization: Bearer sk_your_api_key"
 Response
 {
  "posts": [
    {
      "id": "post_abc123",
      "content": "Hello from SocialSyncerAPI!",
      "status": "published",
      "platforms": [...],
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "cursor": "eyJpZCI6InBvc3RfYWJjMTIzIn0",
  "hasMore": true
}
 Get Post
  GET /v1/posts/{postId} 
 Returns a single post with full details including per-platform status.
 Schedule Post
 Set scheduledFor to an ISO 8601 datetime and publishNow to false:
 {
  "content": "Scheduled post",
  "platforms": [{"platform": "twitter", "accountId": "tw_456"}],
  "publishNow": false,
  "scheduledFor": "2026-02-01T14:00:00Z",
  "timezone": "America/New_York"
}
 Edit Published Tweet
  POST /v1/posts/{postId}/edit 
 Edit a published tweet (Twitter/X only, requires X Premium, within 1 hour of publish, max 5 edits per tweet, text-only).
 Delete Post
  DELETE /v1/posts/{postId} 
 Delete a post. Cannot delete published posts from platforms (only removes from SocialSyncerAPI).
 Retry Failed Post
  POST /v1/posts/{postId}/retry 
 Retry publishing to platforms that failed. Only failed platforms are retried; already-published platforms are skipped.
 Example
 curl -X POST https://api.socialsyncerapi.com/v1/posts/post_abc123/retry \
  -H "Authorization: Bearer sk_your_api_key"