1. Posts
swonkie.dev
  • Introduction
  • Quick Start
  • Changelog
  • Social Networks
    • Facebook
    • Instagram
    • LinkedIn
    • TikTok
    • Threads
  • Profiles
    • My Profiles
      GET
    • Competitors
      GET
  • Insights
    • Getting Started
    • My Profile Insights
      GET
    • My Profile Insights Posts
      GET
    • Competitor Insights
      GET
    • Competitor Insights Posts
      GET
  • Posts
    • Getting Started
    • List Posts
      GET
    • Get a Post
      GET
    • Create a Post
      POST
    • Update a Post
      PUT
    • Validate a Post
      GET
    • Delete a Post
      DELETE
    • Change Post Stage
      PATCH
  • Labels
    • Getting Started
    • List Labels
      GET
    • Create a Label
      POST
  • Media
    • Get a Media
    • Create a Media
    • Upload File to Media
    • Confirm Uploaded Media
    • Delete a Media
  • Examples
    • Publish
Back to Home
Back to Home
Login
  1. Posts

Getting Started

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:
1.
IDEA - Initial concept without a scheduled publish date
2.
DRAFT - Post with a scheduled publish date set
3.
TEAM_REVIEW - Submitted for internal team review
4.
TEAM_REVISION - Returned for changes after team review
5.
TEAM_APPROVED - Approved by team reviewers
6.
CLIENT_REVIEW - Submitted for client approval (if applicable)
7.
CLIENT_REVISION - Returned for changes after client review
8.
CLIENT_APPROVED - Approved by client
9.
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:
1.
Upload media via POST /media to receive an upload URL
2.
Upload the actual file to the provided URL
3.
Reference the media in posts using the returned mediaLibId
4.
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:
1.
Published posts remain in your Swonkie system with PUBLISHED stage
2.
The original profiles array shows which accounts received the post
3.
Access your social network accounts directly to view and manage the live posts
4.
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.
Modified at 2026-03-07 15:20:10
Previous
Posts
Next
List Posts
Built with