--- name: postiz description: | Schedule and manage social media posts via Postiz API (self-hosted or cloud). Direct API integration — no n8n dependency. Supports X/Twitter, LinkedIn, Bluesky with platform-specific character limits. Includes deduplication, scheduling, media upload, and thread creation.

WHAT IT CAN DO: - Schedule posts to 28+ channels (X, LinkedIn, Bluesky, Reddit, Instagram, Facebook, Threads, YouTube, TikTok, Pinterest, Mastodon, and more) - Multi-platform posting in a single API call with platform-adapted content - X/Twitter thread creation for longer content - Media upload (file and URL) - Find next available posting slot per channel - List, query, update, and delete scheduled posts - Deduplication workflow (check existing before posting) - Platform-specific character limits and content tone guidance - Post state management (QUEUE, PUBLISHED, ERROR, DRAFT) - Helper script for quick posting with auto-validation

USE WHEN: scheduling social media posts, creating multi-platform content, managing a posting calendar, uploading media for social posts, checking post status, creating X/Twitter threads, or automating social media workflows. ---

Postiz Social Media Scheduler

Direct API integration for social media posting. No n8n workflows needed.

Setup

Required Environment Variables

# Core configuration
export POSTIZ_URL="https://your-postiz-instance.com"
export POSTIZ_EMAIL="[email protected]"
export POSTIZ_PASSWORD="your-password"

# Integration IDs (get from Postiz dashboard → Integrations)
export POSTIZ_X_ID="your-x-integration-id"
export POSTIZ_LINKEDIN_ID="your-linkedin-integration-id"
export POSTIZ_BLUESKY_ID="your-bluesky-integration-id"

To find your integration IDs:

1. Go to your Postiz dashboard
2. Navigate to Integrations or Channels
3. Each connected account shows an ID (or use the API: GET /api/integrations/list)

Platform Limits

| Platform | Character Limit | Notes | |----------|-----------------|-------| | X/Twitter | 280 | Links count as 23 chars (t.co shortening) | | LinkedIn | 3,000 | First 140 chars show in preview | | Bluesky | 300 | Growing tech/developer audience |

Platform Content Guidelines

X/Twitter (280 chars)

• Short, punchy content
• 1-2 hashtags max
• Threads for longer content (multiple tweets)

LinkedIn (3,000 chars)

• Professional tone
• Can be longer-form
• Hashtags at end (3-5 recommended)
• First 140 chars show in preview — make them count!

Bluesky (300 chars)

• Similar to X but slightly more room
• No official hashtag support (use sparingly)
• Growing tech/developer audience

Authentication

# Login and save cookie (required before any API call)
curl -s -c /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$POSTIZ_EMAIL\",\"password\":\"$POSTIZ_PASSWORD\",\"provider\":\"LOCAL\"}"

Cookie expires periodically. Re-run login if you get 401 errors.

Find Next Available Slot

curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/posts/find-slot/$POSTIZ_X_ID"

Returns the next open time slot for a given channel. Useful for auto-scheduling without conflicts.

Upload Media from URL

curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/media/upload-from-url" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/image.png"}'

Creating Posts

Schedule a Post (Single Platform)

curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/posts" \
  -H 'Content-Type: application/json' \
  -d "{
    \"type\": \"schedule\",
    \"date\": \"2026-02-05T15:00:00Z\",
    \"posts\": [{
      \"integration\": {\"id\": \"$POSTIZ_X_ID\"},
      \"value\": [{\"content\": \"Your tweet here (max 280 chars)\", \"image\": []}],
      \"settings\": {\"__type\": \"x\"}
    }]
  }"

Multi-Platform Post (Adapted Content)

curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/posts" \
  -H 'Content-Type: application/json' \
  -d "{
    \"type\": \"schedule\",
    \"date\": \"2026-02-05T15:00:00Z\",
    \"posts\": [
      {
        \"integration\": {\"id\": \"$POSTIZ_X_ID\"},
        \"value\": [{\"content\": \"Short X version (280 chars max)\", \"image\": []}],
        \"settings\": {\"__type\": \"x\"}
      },
      {
        \"integration\": {\"id\": \"$POSTIZ_LINKEDIN_ID\"},
        \"value\": [{\"content\": \"Longer LinkedIn version with more context and professional tone. Can be up to 3000 characters.\", \"image\": []}],
        \"settings\": {\"__type\": \"linkedin\"}
      },
      {
        \"integration\": {\"id\": \"$POSTIZ_BLUESKY_ID\"},
        \"value\": [{\"content\": \"Bluesky version (300 chars max)\", \"image\": []}],
        \"settings\": {\"__type\": \"bluesky\"}
      }
    ]
  }"

Post Types

• schedule — Auto-publish at specified date/time
• draft — Save for review (won't auto-publish)
• now — Publish immediately

Listing & Querying Posts

Get Posts by Date Range (Required!)

curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/posts?startDate=2026-02-01T00:00:00Z&endDate=2026-02-08T00:00:00Z" \
  | jq '.posts[] | {id, state, publishDate, platform: .integration.providerIdentifier, content: .content[0:60]}'

Check for Duplicates Before Posting

# Get recent posts and check content similarity
curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/posts?startDate=2026-02-01T00:00:00Z&endDate=2026-02-08T00:00:00Z" \
  | jq -r '.posts[] | "\(.integration.providerIdentifier): \(.content[0:80])"'

Post States

| State | Description | |-------|-------------| | QUEUE | Scheduled, waiting to publish | | PUBLISHED | Successfully posted | | ERROR | Failed to publish | | DRAFT | Saved but not scheduled |

Media Upload

Upload Image

# Upload returns {id, path}
curl -s -b /tmp/postiz-cookies.txt \
  "$POSTIZ_URL/api/media/upload-simple" \
  -F 'file=@/path/to/image.png'

Use in Post

"value": [{
  "content": "Post with image",
  "image": [{"id": "MEDIA_ID", "path": "/uploads/..."}]
}]

Twitter/X Threads

For longer content on X, create a thread:

"value": [
  {"content": "Tweet 1/3: Introduction to the topic...", "image": []},
  {"content": "Tweet 2/3: The main point explained...", "image": []},
  {"content": "Tweet 3/3: Conclusion and call to action.", "image": []}
]

Managing Posts

Delete Post

curl -s -b /tmp/postiz-cookies.txt -X DELETE \
  "$POSTIZ_URL/api/posts/POST_ID"

Update Schedule

curl -s -b /tmp/postiz-cookies.txt -X PUT \
  "$POSTIZ_URL/api/posts/POST_ID/date" \
  -H 'Content-Type: application/json' \
  -d '{"date": "2026-02-06T10:00:00Z"}'

Best Practices

Avoid Duplicates

1. Always query existing posts before creating new ones
2. Use unique identifiers in content (dates, specific references)
3. Check both QUEUE and PUBLISHED states

Scheduling

• Space posts at least 2-4 hours apart per platform
• Best times: 9 AM, 12 PM, 5 PM (audience timezone)
• Avoid posting same content to all platforms simultaneously

Content Adaptation

Don't just truncate! Rewrite for each platform:

• X: Hook + key insight + CTA
• LinkedIn: Context + value + engagement question
• Bluesky: Casual tech-friendly tone

Helper Scripts

Post to Multiple Platforms

# Single platform
uv run scripts/post.py \
  --platform x \
  --content "Your tweet here" \
  --schedule "2026-02-05T15:00:00Z"

# Multi-platform with different content
uv run scripts/post.py \
  --x "Short X version" \
  --linkedin "Longer LinkedIn version with more detail" \
  --bluesky "Bluesky version" \
  --schedule "2026-02-05T15:00:00Z"

# Post immediately
uv run scripts/post.py \
  --platform x \
  --content "Posting now!" \
  --now

# Validate without posting
uv run scripts/post.py \
  --x "Test content" \
  --validate

...