Building on the fediverse means working with a platform that is both powerful and fragmented. The Mastodon API follows the REST model, but every instance is its own walled garden when it comes to authentication. If you are building a bot, a scheduling tool, or a full client, you need to know which endpoints matter and which libraries save you from writing boilerplate OAuth code yourself.

The core Mastodon REST API endpoints you need

The Mastodon REST API is documented at docs.joinmastodon.org. It uses standard OAuth 2.0 with a twist: you must register your application on each target instance. The base URL for every request looks like https://[instance]/api/v1/. Here are the endpoints that matter most.

Statuses and timelines

The GET /api/v1/timelines/home endpoint returns the home feed for the authenticated user. Pagination uses max_id and since_id parameters, which is similar to the old Twitter API. For posting, POST /api/v1/statuses accepts status, media_ids[], visibility, and spoiler_text. Visibility levels are public, unlisted, private, and direct.

Media uploads

Uploading media requires two steps. First, POST /api/v2/media with the file data. The response includes an id. Second, attach that id to a status post. This two-step flow lets you upload large files before composing the text.

Streaming

The streaming API uses WebSockets at wss://[instance]/api/v1/streaming. You can subscribe to user, public, or hashtag streams. This is useful for real time bots or analytics tools.

Accounts and relationships

GET /api/v1/accounts/:id returns profile details. POST /api/v1/accounts/:id/follow and POST /api/v1/accounts/:id/unfollow handle follows. For checking if you are already following someone, use GET /api/v1/accounts/relationships with an array of account IDs.

Notifications

GET /api/v1/notifications returns recent events like mentions, follows, and boosts. You can filter by types[] to get only mentions if you are building a reply bot.

Filters and moderation

POST /api/v1/filters lets you create server side filters that hide or warn about content matching keywords. This is useful for moderation tools or custom content warning systems.

A numbered process for getting started with the Mastodon API

Follow these steps to go from zero to a working API call.

1. Register your application on a target instance. Visit https://[instance]/settings/applications and create a new app. Save the client key and client secret.
2. Get an access token. Use OAuth 2.0 with the authorization_code grant. The redirect URI must match what you registered. For headless bots, you can use the client_credentials grant, but not all instances allow it.
3. Choose your library. Pick one from the list below that matches your language.
4. Make your first GET request to https://[instance]/api/v1/timelines/public with the Authorization: Bearer [token] header.
5. Handle pagination. Every timeline response includes a Link header with next and prev URLs. Use those instead of constructing your own pagination logic.
6. Test with a POST to create a status. Use visibility unlisted to avoid spamming the public feed.

Client libraries that save you time

The community maintains libraries for most popular languages. Here are the ones that are actively maintained in 2026.

Python

• Mastodon.py by halcy is the most mature Python library. It handles OAuth, rate limiting, and all major endpoints. Install with pip install Mastodon.py.
• Toot-Toot is a newer library that focuses on async support. Good if you are building an asyncio based application.

JavaScript and Node.js

• mastodon-api by Natalie C. is a solid choice for Node.js. It supports both REST and streaming endpoints.
• megalodon is a fork that adds TypeScript types and better error handling. It is worth switching to if you use TypeScript.

Ruby

• mastodon-api by Gargron is the official reference library. It is well documented and matches the API closely. If you are building a Ruby on Rails integration, start here.

Go, Rust, and others

• mastodon for Go is maintained by the community and covers the full API.
• megalodon-rs is a Rust library that uses async/await. It is newer but already used in production bots.

A table of common API mistakes and how to fix them

Mistake	What happens	How to fix it
Using the wrong base URL	404 or 401 errors	Always use /api/v1/ for REST and /api/v2/media for uploads
Forgetting to scope the token	403 forbidden	Request read write follow scopes during OAuth
Sending too many requests	429 rate limited	Check the X-RateLimit-Remaining header and back off
Using max_id wrong	Missing posts	Use the Link header URLs instead of guessing IDs
Not handling instance variants	Broken federation	Some instances run forks like Glitch or Hometown, which add extra fields

“The most common issue I see in open source Mastodon bots is hardcoded instance URLs. Always make the instance configurable, because your bot will break the moment someone tries to run it on a different server.” — Community maintainer, 2026

Streaming versus polling: when to use each

Polling the REST API every few seconds works for low volume bots. But if you need real time replies or notifications, the streaming API is better. Here is a bullet list of tradeoffs.

• Polling is easier to debug. You can test with curl.
• Polling uses more bandwidth and risks rate limits.
• Streaming gives you instant delivery. No delay.
• Streaming requires a persistent WebSocket connection. Your server must handle reconnects.
• For a bot that posts once per hour, polling is fine.
• For a bot that replies to mentions within seconds, use streaming.

How to choose the right library for your project

Consider these factors.

• Language familiarity. If your team already uses Python, Mastodon.py is the safest choice.
• Async support. If you are building a high throughput service, pick a library with native async.
• Type safety. TypeScript projects benefit from megalodon’s type definitions.
• Community activity. Check the GitHub repository for recent commits. A library that has not been updated in two years may miss API changes.
• Documentation quality. Mastodon.py has a full set of examples. Some newer libraries only have a README.

You can also read more about https://getmammoth.app/how-to-leverage-mastodon-s-api-for-custom-integrations/ for deeper examples.

Putting it all together in a real project

Let us say you want to build a cross instance bot that posts a daily summary. You would need to register the app on each target instance, store the access tokens, and call the POST status endpoint once per day. The libraries listed above handle the OAuth flow so you only write the business logic.

For a more detailed walkthrough of building a bot, check out

What to do when the API changes

Mastodon follows semantic versioning for the REST API. Breaking changes are rare, but they happen. Subscribe to the Mastodon release notes and watch the api/ directory for deprecation warnings. The community also maintains a changelog on docs.joinmastodon.org.

The tools that make federation easier

Federation adds complexity because each instance can run a different software version. Tools like GetMammoth help you manage multiple instances from a single interface. If you are building for the fediverse, consider using a service that abstracts away per instance OAuth.

For more context on where the platform is headed, read

Your next steps as a Mastodon developer

Start with a single endpoint. Post a status. Then add media uploads. Then build a simple bot. The Mastodon API is approachable because it follows familiar REST patterns. The libraries are mature enough that you do not need to write your own OAuth handler. Pick one library, read its documentation, and make your first call today. The fediverse is waiting for the tools you will build.