Mastodon API for developersThe Mastodon API,without per-server setup
Publish posts, images, polls and threads to any Mastodon server, checked against that server’s own limits. Read likes, boosts and poll results. One API key, whichever server the account is on.
Webhooksyour-app.com/hooks
post.scheduledpost 1024just now200
post.publishedpost 10192 h ago200
post.approvedpost 10193 h ago200
POST/v1/posts/createapplication/json
01{
02 "content": "New: OmniSocials SDKs in 8 languages",
03 "accounts": ["mastodon"],
04 "media_urls": [
05 {
06 "url": "https://cdn.example.com/sdks.png",
07 "alt": "Code that creates a post with the Node.js SDK"
08 }
09 ],
10 "schedule_at": "2026-10-22T18:00:00Z"
11}
Sending201 Created412 ms
Send12{
13 "data": {
14 "id": "1024",
15 "status": "scheduled",
16 "app_url": "https://app.omnisocials.com/create-post/1024"
17 }
18}
A request schedules a Mastodon status with an image and its description for Thu at 18:00; it appears in the OmniSocials calendar and the webhook post.scheduled fires.
Your coding agent runs the same calls through the CLI
Skip the setup on every server
Mastodon has no app review, but every server is its own API: an app to register on each one, OAuth per server, its own limits, media that processes before it can post and threads chained reply by reply. OmniSocials does that for any server.
On your own
Server appsOAuthLimitsCountingUploadsProcessingReply chainRetriesFirst postOn OmniSocials
Sign inAPI keyPOSTFirst postRegistered on any server for youEvery format, one request
Text posts, images, polls and threads share one request shape. Add media URLs with their descriptions, poll options or thread parts, and a time. OmniSocials checks the post against your server’s limits before it goes out.
Omnisocials
@omnisocials@mastodon.social
New: OmniSocials SDKs in 8 languages
POST/v1/posts/create
01{
02 "content": "New: OmniSocials SDKs in 8 languages",
03 "accounts": ["mastodon"],
04 "media_urls": [
05 {
06 "url": "https://cdn.example.com/sdks.png",
07 "alt": "Code that creates a post with the Node.js SDK"
08 }
09 ],
10 "schedule_at": "2026-10-22T18:00:00Z"
11}
201 Createdstatus: "scheduled"
Text and link cards
Up to your server’s limit, 500 on mastodon.social, with links counted as 23 characters. A post without media gets the link’s card.
content
Images, video and polls
Up to 4 images or one video, each with a description. Or a poll in place of the media, with as many options as your server allows.
media_urlsmastodon.poll
Threads
2 to 25 statuses in one request, each a reply to the one before, with up to 4 media each.
mastodon.thread_parts
Any server, with its own limits
Type the server, or paste @you@server, and OmniSocials registers its app there for you. It reads that server’s character limit, link length and poll ranges, and checks every post against them before it goes out.
Omnisocials
@omnisocials@mastodon.social
Threads
Single posts
Vote0 people · 3 days left · results hidden until it ends
Threads or single posts on Mastodon?
Connect Mastodon
Enter the server your account is on. Any Mastodon server works.
mastodon.social
You sign in on your server next.
POST/v1/posts/createapplication/json
01{
02 "content": "Threads or single posts on Mastodon?",
03 "accounts": ["mastodon"],
04 "schedule_at": "2026-10-24T11:00:00Z",
05 "mastodon": {
06 "poll": {
07 "options": ["Threads", "Single posts"],
08 "expires_in": 259200,
09 "multiple": false,
10 "hide_totals": true
11 }
12 }
13}
201 Created402 msstatus: "scheduled"
Any server
Type the server, or paste @you@server. OmniSocials registers its app on that server, and you sign in there once.
The server’s own limits
The character limit, how long a link counts and the poll ranges come from the server. Every post is checked against them.
Polls
Options and a duration in the server’s range, 2 to 4 options by default, one answer or several, totals hidden until it ends. The results come back with the analytics.
mastodon.poll
The Mastodon account connects on its own server, then one request schedules a poll, and the composer shows the poll options with the limits of that server.
Connect any server, post from code
Type your server in OmniSocials once and sign in there. Create an API key, and your code posts and reports for that account.
OmniSocials
Name, icon, social channels and who can open this workspace.
GeneralMembersClientsApproval workflowsAPI
Workspace iconJPG or PNG, up to 2 MB.
Workspace nameOmniSocials
Social channels
The accounts this workspace posts to.
Connected
@omnisocials_
Instagram
@omnisocials_
Threads
OmniSocials
LinkedIn Page
@omnisocials_
X
Add a channel
MastodonAny server
FacebookPosts, Stories & ReelsLinkedIn ProfilePosts & Carousels
YouTubeShorts
TikTokVideos & Photo posts
PinterestPins & Carousels
BlueskyPosts & Threads
Google BusinessUpdates, Events & Offers
TelegramChannels and groupsComing soon
Danger zone
Delete workspace
Deletes this workspace with its posts, media and settings for good. This cannot be undone.
OmniSocials
Name, icon, social channels and who can open this workspace.
GeneralMembersClientsApproval workflowsAPI
API keys
Keys that can only reach this workspace.
| Name | Key | Last used | |
|---|---|---|---|
Claude | omsk_live_••••7c2e | Oct 20, 2026 |
GET/v1/accounts?platform=mastodon
200 OK88 ms
01{
02 "data": [
03 {
04 "id": "4127_mastodon",
05 "platform": "mastodon",
06 "username": "omnisocials",
07 "display_name": "Omnisocials",
08 "content_types": ["post"],
09 "status": "active"
10 }
11 ],
12 "workspace_name": "OmniSocials"
13}
Authorization: Bearer $OMNISOCIALS_API_KEY
Your server, over OAuth
OmniSocials registers its app on the server you type. Mastodon tokens do not expire, so nothing needs refreshing.
A key per workspace
A key only reaches its own workspace. Each workspace connects one Mastodon account.
What the account can post
The accounts call lists the account with its username and the formats it takes.
GET /v1/accountscontent_types
“Very easy to use and very handy to schedule posts across platforms for my marketing agency.”
Niels Koelewijn
Founder of Frizzer
Read what Mastodon reports
Likes, replies and boosts per status, summed across a thread, quotes on Mastodon 4.5 or later, poll results and the account’s followers per day. The API returns the same numbers the app charts.
AnalyticsReports
All
Followers
6427.7%
Engagements
27433.7%
Published Posts
716.7%
Posts7Accounts8
Post | Channels | Impressions | Likes | Comments | Shares | Eng. rate | |
|---|---|---|---|---|---|---|---|
 New: Mastodon threads Oct 21, 2026 | | N/A | 49 | 9 | 21 | N/A | |
Building on OmniSocials? Start with the API docs. Oct 20, 2026 | | N/A | 14 | 3 | 6 | N/A | |
 Sidebar update:
1. New Home tab
2. New Drafts tab
Save a post as a draft, find it waiting for you under Drafts. Simple. Oct 20, 2026 | | N/A | 22 | 2 | 7 | N/A | |
 New: PDF uploads Oct 19, 2026 | | N/A | 18 | 1 | 4 | N/A | |
 New: Bluesky threads Oct 19, 2026 | | N/A | 26 | 4 | 9 | N/A | |
Custom Mastodon & Bluesky servers Oct 12, 2026 | | N/A | 24 | 7 | 11 | N/A | |
 New: LinkedIn in the Social Inbox Sep 30, 2026 | | N/A | 20 | 3 | 8 | N/A |
GET/v1/analytics/posts/1019
Authorization: Bearer $OMNISOCIALS_API_KEY
200 OK143 ms
01{
02 "data": {
03 "post_id": "1019",
04 "platforms": {
05 "mastodon": {
06 "metrics": {
07 "likes": 49, "comments": 9,
08 "reposts": 21, "quotes": 2
09 },
10 "thread_parts": 1
11 }
12 }
13 }
14}
Per status and per thread
Likes, replies, boosts, and quotes on Mastodon 4.5 or later. A thread reports the sum of its statuses, and thread_parts says how many.
/analytics/posts/:id
Poll results
Each option’s votes, the number of voters and whether the poll has ended, with the post’s other numbers.
metrics.poll
Per account and workspace
A daily snapshot of the account: followers, following and posts. Plus a workspace overview and best times to post.
/analytics/accounts/analytics/best-times
Under the hood
Built for production
Signed webhooks, automatic retries, SDKs in 8 languages and a key per workspace. Create a key and send your first request in minutes.
Mastodon’s rules, in one place
OmniSocials checks every post against them, with your server’s own numbers, before it reaches the server. A status that is too long fails in your request, not at publish time.
TextYour server’s limit, 500 on mastodon.social
LinksCount as 23 characters, or your server’s length
MediaUp to 4 images or one video, not both
ImagesJPEG, PNG, GIF or WebP, up to 16 MB
VideoUp to 99 MB
Alt text1,500 characters per item
PollsYour server’s range, by default 2 to 4 options, 5 minutes to a month
Thread2 to 25 statuses, 4 media each
VisibilityEvery status goes out public
Rate limit100 requests a minute per API key
Your first status in three steps
About five minutes from sign-up to a scheduled status on your server. Then hand the key to your coding agent.
Create an API key
Start your trial, open Settings, API and create a key. It is shown once.
Settings › APIStep 1
Connect your server
Type your server or paste @you@server in OmniSocials once and sign in there. Then list the account from your code.
GET /v1/accountsStep 2
Send your first status
Post now with create-and-publish, or add schedule_at to plan it. Add mastodon.poll or thread_parts when you need them.
POST /v1/posts/createStep 3
Frequently
Asked Questions
Robert LigthartFounder of OmniSocials
Ship your Mastodon
integration this week.
From $10 per seat a month, API included. 14-day free trial.
https://docs.omnisocials.com