API guide

The Mastodon API in 2026.Every server is its own API.

To post to Mastodon from code, register an app on the person's server with POST /api/v1/apps, send them through OAuth there, then call POST /api/v1/statuses with their token. Media goes up first through /api/v2/media. It's free and open, tokens don't expire, and each server sets its own character limit: 500 on mastodon.social, more on many others.

Checked October 7, 2026. Breakreach is our product.

# 1. Upload each photo (write:media); video answers 202, poll until 200curl -X POST https://mastodon.social/api/v2/media \  -H "Authorization: Bearer $TOKEN" \  -F file=@pourover.jpg -F description="Pour-over of Morning Light" # 2. Post with the media ids (write:statuses)curl -X POST https://mastodon.social/api/v1/statuses \  -H "Authorization: Bearer $TOKEN" \  -H "Idempotency-Key: morning-light-launch" \  -d status="Morning Light is out tomorrow. Honey, orange and cocoa, our lightest roast yet, brewed here as a pour-over and as a latte." \  -d "media_ids[]=113270442165342091" \  -d "media_ids[]=113270442412805244" \  -d visibility=public

1/2 POST /api/v2/mediaSending

Published · now

northbeam

@northbeam@mastodon.social

now

Morning Light is out tomorrow. Honey, orange and cocoa, our lightest roast yet, brewed here as a pour-over and as a latte.

The Mastodon API at a glanceWhat it takes before the first post.

Price: No fees; Mastodon is open-source software under AGPL-3.0
Access: An app registered on each server with POST /api/v1/apps, then OAuth there. No review
Tokens: Don't expire, and there are no refresh tokens. Users revoke them in Authorized apps
Posting: POST /api/v1/statuses with write:statuses; media first through POST /api/v2/media
Text: 500 characters by default, set per server: 1,000 on mas.to, 11,000 on infosec.exchange. Links count 23
Media: Up to 4 attachments, or one video. Images 16 MB, video 99 MB on default servers
Rate limit: 300 requests per 5 minutes per token, 300 posts per 3 hours, 30 uploads per 30 minutes
Scheduling: scheduled_at, at least 5 minutes ahead, 25 a day and 300 in total

Checked on October 7, 2026, from Mastodon's developer documentation and terms.

Our recommendation

To post to Mastodon from your product, use Breakreach's API.We built it, so here's the case.

See the request

No app to register per server, no OAuth to build: people type their server and approve Breakreach there
The same request posts to Bluesky, Threads, X and your other networks, each trimmed to its own limit
Likes, replies and boosts per post come back, with followers and post count

When to use Mastodon's API directly. Breakreach posts publicly, without content warnings, alt text, polls, quote posts or threads, and doesn't read timelines or notifications. For a client or a bot that does more, use Mastodon's API directly: it's free and well documented.

How to get access to the Mastodon APIFrom a developer account to your first real post.

1Ask for the server firstThere's no central developer portal: each server is its own OAuth provider. Mastodon's guidelines ask apps to let people type any server.
2Register your app therePOST /api/v1/apps with client_name, redirect_uris and the scopes you need. Keep the client_id and client_secret per server; clients don't expire since 4.3.
3Send the person through OAuthGET /oauth/authorize on their server, with PKCE (S256, since 4.3), then POST /oauth/token for the access token. The password grant was removed in 4.4.
4Ask for granular scopeswrite:statuses to post and write:media to upload. read:accounts reads the profile. Mastodon's page lists them before the person approves.

No review and no fee. Dynamic client registration (RFC 7591) isn't supported; POST /api/v1/apps is Mastodon's own version of it.

How to post with the Mastodon APIThe requests in the demo above, one by one.

1Upload the mediaPOST /api/v2/media with the file and a description (alt text, up to 10,000 characters). Images answer 200. Video answers 202: poll GET /api/v1/media/:id until it stops answering 206.
2Post the statusPOST /api/v1/statuses with status, media_ids[], visibility (public, unlisted, private or direct), spoiler_text, language, and an optional scheduled_at. It returns the Status with its id and url.
3Send an Idempotency-KeyMastodon keeps it for an hour per account: a retry with the same key returns the first post instead of making a second.

Read the server's real limits from GET /api/v2/instance: configuration.statuses.max_characters and configuration.media_attachments. A scheduled_at in the past publishes at once; one less than 5 minutes ahead is refused.

Common Mastodon API errorsWhat they mean and how to fix them.

Error	What it means	Fix
`401 The access token is invalid`	The person revoked your app, or the token belongs to another server.	Send them through OAuth again.
`403 This action is outside the authorized scopes`	The token lacks write:statuses or write:media.	Register the scope on the app and ask for it at authorize.
`422 Text character limit of 500 exceeded`	Over the server's max_characters.	Read the limit from /api/v2/instance and trim.
`422 Cannot attach files that have not finished processing`	The video was still processing.	Poll GET /api/v1/media/:id until it answers 200.
`422 Cannot attach a video to a post that already contains images`	A video mixed with photos.	Post the video alone.
`429 Too many requests`	A per-token, per-user, upload or posting limit.	Wait until X-RateLimit-Reset.

Mastodon API limitsRate limits, text and media.

Text500 characters in vanilla Mastodon, more on servers that change it. Counted as people see characters; a link counts 23, a mention only its username, and a content warning counts too.
MediaUp to 4 attachments, and a video or audio file goes alone. On default servers, images up to 16 MB and video up to 99 MB, 3840×2160 and 120 fps at most.
Rate limits300 requests per 5 minutes per token and 1,500 per user, 30 media uploads per 30 minutes, and 300 posts per 3 hours per account, which the rate-limit page doesn't list.
SchedulingAt least 5 minutes ahead, 25 scheduled posts per day and 300 in total, limits set in Mastodon's source, not its docs.

Is the Mastodon API free?

Yes. Mastodon has no paid API and no developer program; the software is open source under AGPL-3.0, and each server is run by its own admins.

What it asks for is care: every server sets its own rules, and mastodon.social, for one, asks for generative AI use to be disclosed and doesn't allow accounts that only post AI content.

Through Breakreach, a Mastodon account counts like any other connected account: $5 a month each up to 20, $3 up to 100, then $2.

Ways to post to Mastodon from code

	What you set up	Price	Posts to Mastodon
Breakreach	An API key. Accounts connect on their own server, or your users connect theirs on a hosted page	$5 a month per account, less from 21	Yes, On any server
Mastodon's own API	An app registered on each server, and OAuth per server	Free	Yes
Upload-Post	An API key	Free for 2 profiles and 10 uploads a month; Basic $24 a month for 5 profiles	Yes, On paid plans
Zernio	An API key	First 2 accounts free, then $6 per account up to 10, $3 up to 100, $1 after	No
Ayrshare	An API key	From $149 a month for 1 profile, no free plan	No
Outstand	An API key	$19 a month for 3,000 posts, then per post	No

Checked on October 7, 2026, from Mastodon's developer documentation and each company's pricing page. Breakreach is our product.

What the Mastodon API can't do

Register once for every server: each one needs its own app
Report views or impressions: only likes, boosts, replies and quotes
Post more than 4 attachments, or a video with photos
Schedule less than 5 minutes ahead, or more than 25 posts a day
Refresh a token: they last until revoked

Post to Mastodon with Breakreach's APIOne request, scheduled, with retries.

POST /v1/posts

curl https://api.breakreach.com/v1/posts \  -H "Authorization: Bearer $BREAKREACH_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "content": "Morning Light is out tomorrow. Honey, orange and cocoa, our lightest roast yet, brewed here as a pour-over and as a latte.",    "accountIds": ["6701a2f4c9e84b0012a3b4d2"],    "media": ["https://cdn.northbeam.coffee/pourover.jpg", "https://cdn.northbeam.coffee/latte.jpg"],    "scheduledAt": "2026-10-07T09:00:00"  }'

What it posts on Mastodon

Text postsPublic, on any Mastodon server; the server's own limit applies, 500 characters on most.
Photos or a videoUp to 4 photos, or one video that Breakreach waits on while Mastodon processes it, up to 5 minutes.
No double postsEvery post is sent with an Idempotency-Key, so a retry never posts twice.
StatsLikes, replies and boosts per post; followers and post count for the account.

Not yet

Content warnings, alt text and polls
Unlisted, followers-only or private posts
Threads and quote posts
Reading timelines or notifications

The full reference, webhooks and the price per connected account are on the developers page, and the OpenAPI spec is at api.breakreach.com/v1/openapi.json.

FAQ

Questions, answered.

Short answers about the Mastodon API.

Yes. There's no paid tier and no developer program: you register an app on each server with POST /api/v1/apps and send people through OAuth there.

For your own account, Preferences, Development, New application, then copy Your access token. For other people's accounts, register your app on their server and use the OAuth authorization code flow.

POST /api/v1/statuses with status and, for photos, media_ids from POST /api/v2/media, using a token with write:statuses. Add an Idempotency-Key header so a retry doesn't post twice.

500 characters on a default server, but each server can change it: read configuration.statuses.max_characters from GET /api/v2/instance. Links count as 23 characters and mentions only count the username.

Yes, with scheduled_at on POST /api/v1/statuses, at least 5 minutes ahead. Mastodon's source caps scheduled posts at 25 a day and 300 in total.

300 requests per 5 minutes per access token, 30 media uploads per 30 minutes, and 300 new posts per 3 hours per account, with X-RateLimit headers on each answer. Servers can change them.

$5 a month per connected account up to 20, $3 up to 100, then $2. You pay per connected account, never per post or per request.