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. Any Mastodon-compatible server works: you type the server address when you connect, and OmniSocials registers its app on that server for you.

For an overview and use cases, see Mastodon API.

Channel ID: mastodon

Supported content types

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

Minimal example

Terminal
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.
mastodon.poll	object	Attach a poll; the toot text is the question. See Polls.

Every toot is published as public. Visibility, content warnings and a language setting are not exposed.

Posting threads

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

JSON
{
  "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).

Polls

Pass mastodon.poll to attach a poll. The toot text is the question.

JSON
{
  "accounts": ["your-mastodon-account-id"],
  "content": { "mastodon": "Which feature should we ship next?" },
  "mastodon": {
    "poll": {
      "options": ["Inbox", "Reports", "Ads"],
      "expires_in": 259200,
      "multiple": false,
      "hide_totals": true
    }
  }
}

Field	Type	Description
options	array of strings	The answers. Count and length follow your server's limits (Mastodon's defaults: 2 to 4 options of up to 50 characters). Options must differ from each other.
expires_in	integer	How long the poll runs, in seconds, within your server's range (Mastodon's default: 5 minutes to about 1 month). Leave it out and the poll runs for 86400 seconds (one day). The composer in the OmniSocials dashboard offers 5 minutes to 30 days, limited to your server's range.
multiple	boolean	Let people pick several answers (default false).
hide_totals	boolean	Hide the vote counts until the poll ends (default false).

A poll and media do not go together on Mastodon: a request with both is refused with 400 validation_error. On a thread (thread_parts), the poll goes on the first toot. GET /posts/:id returns the poll under mastodon.poll; on PATCH /posts/:id, mastodon.poll: null removes it. Poll results come back in analytics under metrics.poll.

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, MOV, or WebM, max 99 MB. Duration is instance-dependent; OmniSocials does not enforce a fixed cap. OmniSocials waits for the server to finish processing a video before it sends the toot.

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, Threads, Pinterest, Instagram (images), and LinkedIn (images):

JSON
{
  "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.

Characters are counted the way Mastodon counts them: every http(s) link counts as 23 characters (or your server's own URL length), a remote mention counts by its local part (@user@server counts as @user), and an emoji counts as 1.

Limitations

• Content warnings (CW) are not currently exposed through the API
• Posts are always public. Per-post visibility (unlisted, private, direct) is not available, and the account's default visibility is not used.
• Mastodon comments and mentions are not part of the Social Inbox
• Analytics report likes, comments (replies), reposts (boosts) and quotes per toot, but no views or reach. Quotes are only reported by servers on Mastodon 4.5 or later.
• Federation delays may mean the post is not immediately visible on other instances even after a successful publish response