Copy page

Platforms

Mastodon API: Posting Reference

Mastodon is supported via the standard Mastodon API. OmniSocials posts to the specific instance and account that completed OAuth. Because Mastodon is decentralized, every account lives on a different server and is identified by its full [email protected] handle.

Channel ID: mastodon

Supported content types

Type	Supported
Feed post (toot)	✅
Story	-
Reel	-

Minimal example

Code
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Posting from the API 🐘" },
    "accounts": ["your-mastodon-account-id"]
  }'

Platform-specific options

Field	Type	Description
mastodon.thread_parts	array	Publish as a chained thread instead of a single toot. See Posting threads.

Content warnings and per-post visibility are not yet exposed and may be added as optional keys in the future.

Posting threads

To publish a thread, pass mastodon.thread_parts. Each part becomes its own toot, replying to the previous one natively.

Code
{
  "accounts": ["your-mastodon-account-id"],
  "content": { "default": "" },
  "mastodon": {
    "thread_parts": [
      { "text": "1/3: a thread on the fediverse 🐘" },
      { "text": "2/3: every instance sets its own rules" },
      { "text": "3/3: and that is a feature, not a bug" }
    ]
  }
}

Rules:

• 2 to 25 parts. For a single toot, omit thread_parts and use content.mastodon (or content.default) instead.
• Each text is required, non-empty, and within your instance's character limit (500 on mastodon.social; OmniSocials reads your instance's real limit at connect time).
• media_urls is optional per part (max 4 items per part).

Media requirements

Mastodon media limits vary by instance. OmniSocials validates against the default mastodon.social limits:

Media	Requirement (default)
Image	JPEG, PNG, GIF, or WebP. Max 16 MB. Up to 4 per post.
Video	MP4, max 99 MB. Duration is instance-dependent; OmniSocials does not enforce a fixed cap.

Mastodon does not support mixing images and video in the same status: attach images only, or a single video. Mixed media returns a 400 validation_error at create/schedule time.

Some instances are more permissive. Some are stricter. A post that passes OmniSocials validation may still be rejected by a custom instance with tighter limits. In that case the error body includes the instance's rejection message.

Alt text

The Mastodon community strongly values alt text on images; several instances even run bots reminding users to add descriptions. Pass it per media item by using an object entry instead of a bare string (works in media_urls, media_ids, and per-part thread media; max 1500 characters). It is sent as the media's description, and the same alt also delivers to Bluesky, X, Pinterest, Instagram (images), and LinkedIn (images):

Code
{
  "content": { "default": "Morning ride before work 🐘" },
  "accounts": ["your-mastodon-account-id"],
  "media_urls": [
    { "url": "https://example.com/bike.jpg", "alt": "A red bicycle leaning against a brick wall" }
  ]
}

Character limit

Your instance's real limit applies. When you connect a Mastodon account, OmniSocials reads the instance's configured max_characters and validates against that, so an instance with a 5,000-character limit really gets 5,000. The fallback is 500 (the mastodon.social default) when the instance does not report a limit.

Limitations

• Content warnings (CW) are not currently exposed through the API
• Per-post visibility (public, unlisted, private, direct) defaults to the account's default. A field to override this is planned but not shipped.
• Federation delays may mean the post is not immediately visible on other instances even after a successful publish response