postiz

name	postiz
version	1.0.0
author	G-HunterAi
license	MIT
description	Schedule and publish social media posts to 28+ channels including X, LinkedIn, Instagram, TikTok, YouTube, Discord, Slack, and more. Perfect for content calendars and multi-platform distribution.
homepage	https://docs.postiz.com/public-api/introduction
tags	["social-media","scheduling","multi-platform","automation","content-distribution"]
platforms	["all"]
category	content
emoji	📅
metadata	{"clawdbot":{"emoji":"📅","requires":{"bins":[],"env":["POSTIZ_API_KEY"]}}}

Postiz Skill

Schedule and publish social media and chat posts to 28+ channels:

X, LinkedIn, LinkedIn Page, Reddit, Instagram, Facebook Page, Threads, YouTube, Google My Business, TikTok, Pinterest, Dribbble, Discord, Slack, Kick, Twitch, Mastodon, Bluesky, Lemmy, Farcaster, Telegram, Nostr, VK, Medium, Dev.to, Hashnode, WordPress, ListMonk

---

When to Use

• Scheduling posts across multiple platforms simultaneously
• Managing content calendars with precise publish times
• Distributing the same content to many channels at once
• Automating recurring social media campaigns
• Batch-uploading media to multiple platforms

When NOT to Use

• Publishing immediately without scheduling (use direct platform uploads instead)
• Creating content from scratch (use content generation skills first)
• Detailed content creation or editing (use text/image skills first)

---

Prerequisites

1. Postiz Account — Create at https://postiz.com/
2. API Key — Available at https://platform.postiz.com/settings
3. Connected Integration IDs — Each social platform requires a connected account

---

Setup

Step 1: Get Your API Key

1. Log in to https://platform.postiz.com/
2. Navigate to "Settings"
3. Click "Reveal" to display your API key
4. Copy the key (starts with pk_)

Step 2: Set Environment Variable

export POSTIZ_API_KEY="your-api-key-here"

Step 3: Get Your Integration IDs

View all connected channels and their IDs:

curl -X GET "https://api.postiz.com/public/v1/integrations" \
  -H "Authorization: $POSTIZ_API_KEY"

This returns a list of integrations with their id values (you'll use these in post requests).

---

Core Operations

1. List All Connected Integrations

Use this first to find your channel/integration IDs.

curl -X GET "https://api.postiz.com/public/v1/integrations" \
  -H "Authorization: $POSTIZ_API_KEY"

Response includes:

• Integration IDs for each connected platform
• Channel names and types
• Connection status

---

2. Find Available Slot for Scheduling

Check the next available time slot for a specific channel to avoid conflicts.

curl -X GET "https://api.postiz.com/public/v1/find-slot/INTEGRATION_ID" \
  -H "Authorization: $POSTIZ_API_KEY"

Example:

curl -X GET "https://api.postiz.com/public/v1/find-slot/int_abc123def456" \
  -H "Authorization: $POSTIZ_API_KEY"

---

3. Upload Media (Local File)

Upload an image or video from your computer.

curl -X POST "https://api.postiz.com/public/v1/upload" \
  -H "Authorization: $POSTIZ_API_KEY" \
  -F "file=@/path/to/your/image.png"

Supported formats: PNG, JPG, GIF, MP4, WebM

Response:

{
  "id": "img_abc123",
  "path": "https://uploads.postiz.com/photo.jpg"
}

---

4. Upload Media from URL

Use an existing image URL instead of uploading a file.

curl -X POST "https://api.postiz.com/public/v1/upload-from-url" \
  -H "Authorization: $POSTIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.png"
  }'

---

5. Schedule a Post to Multiple Platforms

Schedule a single post across multiple channels with the same content.

curl -X POST "https://api.postiz.com/public/v1/posts" \
  -H "Authorization: $POSTIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "schedule",
  "date": "2026-03-25T10:00:00.000Z",
  "shortLink": false,
  "tags": ["social-media", "announcement"],
  "posts": [
    {
      "integration": {
        "id": "int_x_integration_id"
      },
      "value": [
        {
          "content": "Excited to announce our new feature! 🚀 Check it out now and let us know what you think.",
          "image": [
            {
              "id": "img_abc123",
              "path": "https://uploads.postiz.com/feature-announce.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "x"
      }
    },
    {
      "integration": {
        "id": "int_linkedin_integration_id"
      },
      "value": [
        {
          "content": "We're thrilled to unveil our latest innovation! This feature has been built with your feedback in mind. Learn more in the blog post.",
          "image": [
            {
              "id": "img_abc123",
              "path": "https://uploads.postiz.com/feature-announce.jpg"
            }
          ]
        }
      ],
      "settings": {
        "__type": "linkedin"
      }
    }
  ]
}'

Key parameters:

• date — ISO 8601 timestamp (must be in the future)
• posts[].integration.id — Integration ID for each platform
• posts[].value[].content — Text content (platform-specific character limits apply)
• posts[].value[].image — Array of uploaded media
• posts[].settings.__type — Platform type (x, linkedin, instagram, tiktok, etc.)

---

6. List Recent Posts

Retrieve posts scheduled or published within a date range.

curl -X GET "https://api.postiz.com/public/v1/posts?startDate=2026-03-01T00:00:00.000Z&endDate=2026-03-31T23:59:59.000Z" \
  -H "Authorization: $POSTIZ_API_KEY"

Parameters:

• startDate — Start of date range (ISO 8601)
• endDate — End of date range (ISO 8601)
• customer — Optional: filter by customer ID

---

7. Delete a Scheduled Post

Remove a scheduled post before it publishes.

curl -X DELETE "https://api.postiz.com/public/v1/posts/POST_ID" \
  -H "Authorization: $POSTIZ_API_KEY"

Example:

curl -X DELETE "https://api.postiz.com/public/v1/posts/post_xyz789" \
  -H "Authorization: $POSTIZ_API_KEY"

---

Complete Workflow Example

Scenario: Schedule an announcement to X, LinkedIn, and Instagram simultaneously.

# Step 1: Get your integration IDs
curl -X GET "https://api.postiz.com/public/v1/integrations" \
  -H "Authorization: $POSTIZ_API_KEY"

# Step 2: Upload campaign image
UPLOAD_RESPONSE=$(curl -X POST "https://api.postiz.com/public/v1/upload" \
  -H "Authorization: $POSTIZ_API_KEY" \
  -F "file=@./campaign-banner.png")

IMG_ID=$(echo $UPLOAD_RESPONSE | jq -r '.id')
IMG_PATH=$(echo $UPLOAD_RESPONSE | jq -r '.path')

# Step 3: Schedule the multi-platform post
curl -X POST "https://api.postiz.com/public/v1/posts" \
  -H "Authorization: $POSTIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
  \"type\": \"schedule\",
  \"date\": \"2026-03-25T14:00:00.000Z\",
  \"shortLink\": true,
  \"tags\": [\"campaign\", \"announcement\"],
  \"posts\": [
    {
      \"integration\": { \"id\": \"YOUR_X_INTEGRATION_ID\" },
      \"value\": [{
        \"content\": \"Big news! 🎉 Join us for our latest launch.\",
        \"image\": [{ \"id\": \"$IMG_ID\", \"path\": \"$IMG_PATH\" }]
      }],
      \"settings\": { \"__type\": \"x\" }
    },
    {
      \"integration\": { \"id\": \"YOUR_LINKEDIN_INTEGRATION_ID\" },
      \"value\": [{
        \"content\": \"We're thrilled to announce our latest innovation. Check back for more details!\",
        \"image\": [{ \"id\": \"$IMG_ID\", \"path\": \"$IMG_PATH\" }]
      }],
      \"settings\": { \"__type\": \"linkedin\" }
    },
    {
      \"integration\": { \"id\": \"YOUR_INSTAGRAM_INTEGRATION_ID\" },
      \"value\": [{
        \"content\": \"Something amazing is coming... stay tuned! ✨\",
        \"image\": [{ \"id\": \"$IMG_ID\", \"path\": \"$IMG_PATH\" }]
      }],
      \"settings\": { \"__type\": \"instagram\" }
    }
  ]
}"

# Step 4: Verify the post was scheduled
curl -X GET "https://api.postiz.com/public/v1/posts?startDate=2026-03-25T00:00:00.000Z&endDate=2026-03-25T23:59:59.000Z" \
  -H "Authorization: $POSTIZ_API_KEY"

---

Platform-Specific Settings

Different platforms require different settings objects. Refer to the Postiz API documentation for detailed settings for each platform.

Common settings format:

{
  "settings": {
    "__type": "platform_name",
    // platform-specific options here
  }
}

For example:

• X: "__type": "x"
• LinkedIn: "__type": "linkedin"
• Instagram: "__type": "instagram"
• TikTok: "__type": "tiktok"
• Discord: "__type": "discord"

---

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or missing API key	Check POSTIZ_API_KEY environment variable
404 Not Found	Integration ID doesn't exist	Verify integration ID with /integrations endpoint
400 Bad Request	Invalid post format or past date	Check date format (ISO 8601) and integration IDs
422 Unprocessable Entity	Content exceeds platform limits	Reduce text length or image count
429 Too Many Requests	Rate limit exceeded	Wait before making more requests

---

Works Well With

• upload-post — For sharing Postiz results immediately
• image-gen — Generate campaign images to upload
• workflow-orchestrator — Automate multi-step posting campaigns
• mission-control — Manage posting schedule and track campaign performance

---

Tips & Best Practices

1. Always get slots first — Use /find-slot to avoid scheduling conflicts
2. Test with short timeframes — Schedule a test post for 5 minutes from now
3. Use tags — Organize posts by campaign, date, or theme
4. Platform character limits — X: 280 chars, LinkedIn: 3000 chars, Instagram: 2200 chars
5. Timezone handling — Always use ISO 8601 with timezone offset (e.g., 2026-03-25T10:00:00-08:00)
6. Batch uploads — Group related media files before uploading to save API calls
7. Image specifications — 1200x628px recommended for most platforms

---

Links & Resources

• API Docs: https://docs.postiz.com/public-api/introduction
• Platform Settings Reference: https://docs.postiz.com/public-api/introduction (left menu)
• Postiz Dashboard: https://platform.postiz.com/

---

Last updated: March 2026