Mastodon API Reference

Post to any Mastodon instance with visibility control, content warnings, and polls.

Quick reference

authOAuth 2.0 (dashboard)
text Limit500 characters
max Media4 images or 1 video
media RuleText or media required (text-only and media-only both work)
max Video DurationNo hard limit (99 MB size cap)
entity SelectionNone
first CommentSupported — instance-defined limit

Content types

✓Text

Up to 500 characters (instance default).

✓Images

Up to 4 images. JPEG, PNG, GIF, WebP, HEIC, AVIF. Max 16 MB each.

✓Video

MP4, MOV, WebM, M4V. Max 99 MB.

✓GIF

Animated GIFs supported

✓Carousel

Up to 4 images attached to one post

✓Polls

Via platformSettings.mastodon.poll — polls and media are mutually exclusive

Media requirements

Constraints enforced by Mastodon's API. Requests that violate these limits will be rejected.

ConstraintValue
Max image size16 MB
Max video size99 MB
Image formatsJPEG, PNG, GIF, WEBP, HEIF, HEIC, AVIF
Video formatsMP4, QUICKTIME, WEBM, X-M4V
Max media items4
GIF supportYes

Platform settings

Pass these fields inside platformSettings.mastodon in the request body.

visibility
stringOptional

Who can see the post.

Default: public

publicunlistedprivatedirect
spoilerText
stringOptional

Content warning text. The post body is hidden behind this warning until the reader expands it.

sensitive
booleanOptional

Mark attached media as sensitive (blurred until clicked).

Default: false

language
stringOptional

ISO 639-1 language code for the post (e.g. 'en', 'de').

poll
objectOptional

Attach a poll: { options: string[] (2-4, max 50 chars each), expiresIn: seconds (default 86400), multiple: boolean, hideTotals: boolean }. Mastodon rejects polls combined with media.

Code examples

Basic post

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello fediverse from the API!",
    "platforms": [
      { "platform": "mastodon" }
    ],
    "platformSettings": {
      "mastodon": { "visibility": "unlisted" }
    },
    "publishNow": true
  }'

Post with media

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Photo post with a content warning",
    "platforms": [
      { "platform": "mastodon" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/photo.jpg" }
    ],
    "platformSettings": {
      "mastodon": {
        "visibility": "public",
        "spoilerText": "Photography",
        "sensitive": false
      }
    },
    "publishNow": true
  }'

Quirks & gotchas

!

Connect via the dashboard for now — POST /api/v1/connect/mastodon returns a clear error; API-based connect is coming.

!

visibility defaults to public — set platformSettings.mastodon.visibility explicitly if you want unlisted, private (followers-only), or direct.

!

Character limit is the instance default (500 on mastodon.social); some instances allow more, but the API validates against 500.

!

Polls and media are mutually exclusive (a Mastodon rule) — if you send both, the poll is posted and the media is skipped.

!

spoilerText (content warning) hides the whole post body, not just media — use sensitive: true to blur media only.

Related

Posts API — Create and schedule posts across all platformsMedia API — Platform-specific media constraints and upload limitsConnecting Accounts — OAuth, App Password, and Bot Token flowsAll Platforms — Compatibility matrix and overview of all 12 platforms