Posts

The Posts API provides comprehensive management of your social media content across multiple networks and profiles. A single post entity in Swonkie represents a unified piece of content that can be distributed to dozens of individual social media posts simultaneously, each tailored to the specific requirements and features of different platforms.

Multi-Network & Multi-Profile Publishing

Posts in Swonkie are designed for efficiency and scale. When you create a post, you can:

Target multiple social networks (Facebook, Instagram, LinkedIn, TikTok, Threads, YouTube, Google My Business) from a single post configuration

Publish to multiple profiles simultaneously, even across different networks

Customize content per network by providing network-specific captions, media, and links

Apply network-specific features like Facebook carousels, Instagram story sharing, TikTok video settings, and LinkedIn document titles

Use shared or unique content - set global captions/media that apply to all networks, or customize each network individually

For example, a single post can simultaneously publish the same product announcement to 3 Facebook pages, 2 Instagram accounts, and 1 LinkedIn profile, with each platform receiving content optimized for its audience and format requirements.

Post Workflow & Stages

Posts follow a structured workflow through various stages, allowing for collaboration, review, and approval before publishing:

IDEA - Initial concept without a scheduled publish date

DRAFT - Post with a scheduled publish date set

TEAM_REVIEW - Submitted for internal team review

TEAM_REVISION - Returned for changes after team review

TEAM_APPROVED - Approved by team reviewers

CLIENT_REVIEW - Submitted for client approval (if applicable)

CLIENT_REVISION - Returned for changes after client review

CLIENT_APPROVED - Approved by client

SCHEDULED - Queued for publishing at the specified time

10.

PUBLISHED - Successfully published to social networks

11.

PUBLISHED_FAILED - Publishing encountered errors

12.

ARCHIVE - Archived for record keeping

Use the PATCH /posts/:postId/stage/:stage endpoint to move posts through these stages. The workflow supports both immediate publishing publishNow and scheduled publishing schedule.

Labels & Organization

Posts can be tagged with multiple labels (tags) to organize your content calendar. Labels help you:

Categorize posts by campaign, content type, or priority

Filter posts when listing them with GET /posts

Track related content across different time periods

Organize multi-phase campaigns

Labels are created via POST /labels and assigned to posts using the labelIds field.

Media Integration

Posts reference media files from your workspace's media library rather than directly embedding files. This approach offers several benefits:

Reusability - Upload a file once, use it in multiple posts

Efficiency - No need to re-upload the same image/video for different posts

Management - Centralized media library for all your assets

Flexibility - Network-specific media assignments when needed

The media workflow:

Upload media via POST /media to receive an upload URL

Upload the actual file to the provided URL

Reference the media in posts using the returned mediaLibId

The same media can be reused across unlimited posts

Publishing & Status Tracking

After scheduling or publishing a post, tracking its status involves two levels:

Post-Level Status (via stage field):

Monitor the overall post stage with GET /posts/:postId

Stage changes to SCHEDULED when queued for publishing

Stage changes to PUBLISHED after successful publishing to all profiles

Stage changes to PUBLISHED_FAILED if any profile encounters errors

Profile-Level Status (via profiles[].publishStatus field):

Each profile in a post has its own publishStatus

PENDING - Queued and waiting to publish

PUBLISHED - Successfully published to this specific network

FAILED - Publishing failed for this profile (check platform for details)

CANCELLED - Publishing was cancelled before completion

Accessing Published Post Links:

Once published, the actual social media post URLs are not directly returned in the API response. To view published posts on their respective platforms:

Published posts remain in your Swonkie system with PUBLISHED stage

The original profiles array shows which accounts received the post

Access your social network accounts directly to view and manage the live posts

Each platform maintains its own post IDs and URLs that can be viewed in their native interfaces

Publishing is asynchronous - a successful schedule/publish API response means the process has started, but actual posting happens in the background. Poll the post's status to confirm completion.

Post Types & Requirements

Different post types support different features:

STATUS - Text-only posts (no media or links)

MEDIA - Posts with images, videos, or albums

STORY - Temporary content (Instagram/Facebook Stories)

LINK - Posts featuring a link preview

REEL - Short-form video content (Instagram Reels, YouTube Shorts)

Each type has specific requirements and supported networks. The API validates your post configuration before allowing scheduling or publishing.

Multi-Network & Multi-Profile Publishing#

Post Workflow & Stages#

Labels & Organization#

Media Integration#