nevo-david_postiz/INTEGRATION_SETTINGS_DISCOVERY.md

Integration Settings Discovery

The CLI now has a powerful feature to discover what settings are available for each integration!

New Command: integrations:settings

Get the settings schema, validation rules, and maximum character limits for any integration.

Usage

postiz integrations:settings <integration-id>

What It Returns

{
  "output": {
    "maxLength": 280,
    "settings": {
      "properties": {
        "who_can_reply_post": {
          "enum": ["everyone", "following", "mentionedUsers", "subscribers", "verified"],
          "description": "Who can reply to this post"
        },
        "community": {
          "pattern": "^(https://x.com/i/communities/\\d+)?$",
          "description": "X community URL"
        }
      },
      "required": ["who_can_reply_post"]
    }
  }
}

Workflow

1. List Your Integrations

postiz integrations:list

Output:

[
  {
    "id": "reddit-abc123",
    "name": "My Reddit Account",
    "identifier": "reddit",
    "provider": "reddit"
  },
  {
    "id": "youtube-def456",
    "name": "My YouTube Channel",
    "identifier": "youtube",
    "provider": "youtube"
  },
  {
    "id": "twitter-ghi789",
    "name": "@myhandle",
    "identifier": "x",
    "provider": "x"
  }
]

2. Get Settings for Specific Integration

postiz integrations:settings reddit-abc123

Output:

{
  "output": {
    "maxLength": 40000,
    "settings": {
      "properties": {
        "subreddit": {
          "type": "array",
          "items": {
            "properties": {
              "value": {
                "properties": {
                  "subreddit": {
                    "type": "string",
                    "minLength": 2,
                    "description": "Subreddit name"
                  },
                  "title": {
                    "type": "string",
                    "minLength": 2,
                    "description": "Post title"
                  },
                  "type": {
                    "type": "string",
                    "description": "Post type (text or link)"
                  },
                  "url": {
                    "type": "string",
                    "description": "URL for link posts"
                  },
                  "is_flair_required": {
                    "type": "boolean",
                    "description": "Whether flair is required"
                  },
                  "flair": {
                    "properties": {
                      "id": "string",
                      "name": "string"
                    }
                  }
                },
                "required": ["subreddit", "title", "type", "is_flair_required"]
              }
            }
          }
        }
      },
      "required": ["subreddit"]
    }
  }
}

3. Use the Settings in Your Post

Now you know what settings are available and required!

postiz posts:create \
  -c "My post content" \
  -p reddit \
  --settings '{
    "subreddit": [{
      "value": {
        "subreddit": "programming",
        "title": "Check this out!",
        "type": "text",
        "url": "",
        "is_flair_required": false
      }
    }]
  }' \
  -i "reddit-abc123"

Examples by Platform

Reddit

postiz integrations:settings reddit-abc123

Returns:

• Max length: 40,000 characters
• Required settings: subreddit, title, type
• Optional: flair

YouTube

postiz integrations:settings youtube-def456

Returns:

• Max length: 5,000 characters (description)
• Required settings: title, type (public/private/unlisted)
• Optional: tags, thumbnail, selfDeclaredMadeForKids

X (Twitter)

postiz integrations:settings twitter-ghi789

Returns:

• Max length: 280 characters (or 4,000 for verified)
• Required settings: who_can_reply_post
• Optional: community

LinkedIn

postiz integrations:settings linkedin-jkl012

Returns:

• Max length: 3,000 characters
• Optional settings: post_as_images_carousel, carousel_name

TikTok

postiz integrations:settings tiktok-mno345

Returns:

• Max length: 150 characters (caption)
• Required settings: privacy_level, duet, stitch, comment, autoAddMusic, brand_content_toggle, brand_organic_toggle, content_posting_method
• Optional: title, video_made_with_ai

Instagram

postiz integrations:settings instagram-pqr678

Returns:

• Max length: 2,200 characters
• Required settings: post_type (post or story)
• Optional: is_trial_reel, graduation_strategy, collaborators

No Additional Settings Required

Some platforms don't require specific settings:

postiz integrations:settings threads-stu901

Returns:

{
  "output": {
    "maxLength": 500,
    "settings": "No additional settings required"
  }
}

Platforms with no additional settings:

• Threads
• Mastodon
• Bluesky
• Telegram
• Nostr
• VK

Use Cases

1. Discovery

Find out what settings are available before posting:

# What settings does YouTube support?
postiz integrations:settings youtube-123

# What settings does Reddit support?
postiz integrations:settings reddit-456

2. Validation

Check maximum character limits:

postiz integrations:settings twitter-789 | jq '.output.maxLength'
# Output: 280

3. AI Agent Integration

AI agents can call this endpoint to:

• Discover available settings dynamically
• Validate settings before posting
• Adapt to platform-specific requirements

# Get settings schema
INTEGRATION_ID="your-integration-id"
SETTINGS=$(postiz integrations:settings "$INTEGRATION_ID")

# Extract max length
MAX_LENGTH=$(echo "$SETTINGS" | jq '.output.maxLength')

# Check and truncate content if needed
CONTENT="Your post content"
if [ ${#CONTENT} -gt "$MAX_LENGTH" ]; then
  CONTENT="${CONTENT:0:$MAX_LENGTH}"
fi

# List required settings
echo "$SETTINGS" | jq '.output.settings.required // []'

4. Form Generation

Use the schema to generate UI forms:

# Inspect the settings schema for form generation
postiz integrations:settings reddit-123 | jq '.output.settings'

# Extract specific field properties
postiz integrations:settings reddit-123 \
  | jq '.output.settings.properties.subreddit.items.properties.value.properties'
# → subreddit (text, minLength: 2)
# → title (text, minLength: 2)
# → type (select: text/link)
# → etc.

Combined Workflow

Complete workflow for posting with correct settings:

#!/bin/bash
export POSTIZ_API_KEY=your_key

# 1. List integrations
echo "📋 Available integrations:"
postiz integrations:list

# 2. Get settings for Reddit
echo ""
echo "⚙️  Reddit settings:"
SETTINGS=$(postiz integrations:settings reddit-123)
echo $SETTINGS | jq '.output.maxLength'
echo $SETTINGS | jq '.output.settings'

# 3. Create post with correct settings
echo ""
echo "📝 Creating post..."
postiz posts:create \
  -c "My post content" \
  -p reddit \
  --settings '{
    "subreddit": [{
      "value": {
        "subreddit": "programming",
        "title": "Interesting post",
        "type": "text",
        "url": "",
        "is_flair_required": false
      }
    }]
  }' \
  -i "reddit-123"

API Endpoint

The command calls:

GET /public/v1/integration-settings/:id

Returns:

{
  output: {
    maxLength: number;
    settings: ValidationSchema | "No additional settings required";
  }
}

Error Handling

Integration Not Found

postiz integrations:settings invalid-id
# ❌ Failed to get integration settings: Integration not found

API Key Not Set

postiz integrations:settings reddit-123
# ❌ Error: POSTIZ_API_KEY environment variable is required

Tips

1. Always check settings first before creating posts with custom settings
2. Use the schema to validate your settings object
3. Check maxLength to avoid exceeding character limits
4. For AI agents: Cache the settings to avoid repeated API calls
5. Required fields must be included in your settings object

Comparison: Before vs After

Before ❌

# Had to guess what settings are available
# Had to read documentation or source code
# Didn't know character limits

After ✅

# Discover settings programmatically
postiz integrations:settings reddit-123

# See exactly what's required and optional
# Know the exact character limits
# Get validation schemas

Summary

✅ Discover settings for any integration ✅ Get character limits ✅ See validation schemas ✅ Know required vs optional fields ✅ Perfect for AI agents ✅ No more guesswork!

Now you can discover what settings each platform supports! 🎉