Skip to main content

​
Overview

Postiz supports Mastodon and other fediverse instances using the Mastodon API, allowing you to post text, images, and videos to the decentralized social network.
Custom Instances Supported: Connect to any Mastodon-compatible instance by configuring the instance URL.

​
Authentication

Mastodon uses OAuth 2.0 authentication.
1

Configure Instance

Set MASTODON_URL environment variable (default: https://mastodon.social)
2

Connect Account

Click “Connect Mastodon” in Integrations
3

Authorize

Grant permissions on your Mastodon instance

​
Required Permissions

  • write:statuses - Create and delete posts
  • profile - Read profile information
  • write:media - Upload media files

​
Custom Instance Setup

To connect to a custom instance:
  1. Set environment variables: 
    MASTODON_URL=https://your-instance.social
MASTODON_CLIENT_ID=your_client_id
MASTODON_CLIENT_SECRET=your_client_secret
  2. Register OAuth application on your instance
  3. Configure redirect URI: {FRONTEND_URL}/integrations/social/mastodon

​
Supported Features

​
Content Types

  • Maximum: 500 characters (instance may vary)
  • Plain text
  • URLs automatically linked
  • Hashtags supported

​
Visibility Settings

All posts are set to public visibility. Future support may include:
  • Unlisted
  • Followers-only
  • Direct messages

​
Media Upload

Media upload process:
1

Fetch Media

Download media from provided URL
2

Upload to Instance

POST to /api/v1/media endpoint
3

Get Media ID

Receive media ID for post attachment
4

Attach to Post

Include media IDs in post creation
const form = new FormData();
form.append('file', await fetch(fileUrl).then(r => r.blob()));

const media = await fetch(`${instanceUrl}/api/v1/media`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}` },
  body: form
});

const { id } = await media.json();

​
Posting Content

Create posts with text and media: 
{
  status: "Your post text",
  visibility: "public",
  media_ids: ["123", "456"]  // Optional
}
Response includes:
  • Post ID
  • Post URL: {instanceUrl}/statuses/{postId}

​
Replies & Threads

Create threaded conversations:
1

Main Post

Create initial post
2

Reply

Set in_reply_to_id to parent post ID
3

Thread Chain

Continue referencing previous post
{
  status: "Reply text",
  visibility: "public",
  in_reply_to_id: "12345",
  media_ids: []  // Optional
}

​
Rate Limits

Mastodon Rate Limits:
  • 5 concurrent posting jobs
  • Rate limits vary by instance
  • Typically generous for posting
  • Media uploads count separately

​
Instance Compatibility

Postiz is compatible with:
  • Mastodon - Official implementation
  • Pleroma - Lightweight alternative
  • Akkoma - Pleroma fork
  • Misskey - May require adapter
  • Other Mastodon API-compatible servers
Compatibility depends on instance implementing Mastodon’s API correctly.

​
Best Practices

Character Limits

Respect your instance’s character limit (usually 500)

Content Warnings

Add CW for sensitive content (future feature)

Hashtags

Use relevant hashtags for discovery

Instance Rules

Follow your instance’s community guidelines

​
Troubleshooting

If can’t connect to instance:
  • Verify instance URL is correct
  • Check instance is online
  • Ensure OAuth app is registered
  • Verify client ID and secret
Media upload issues:
  • Check file format is supported
  • Verify file size within limits
  • Ensure instance has storage available
  • Try smaller file size
If post doesn’t show:
  • Check post was created (response has ID)
  • Verify visibility settings
  • Instance may be federating slowly
  • Check local vs federated timeline
Authentication issues:
  • Mastodon tokens are long-lived
  • If expired, reconnect account
  • Check instance hasn’t reset tokens
  • Verify OAuth app still exists

Build docs developers (and LLMs) love

Get started for freeTalk to us