mastodon
mastodon
Mastodon REST API — statuses, timelines, accounts, notifications, search, media, lists, polls, conversations, trends, filters, and instance info. Base URL must be set to the target Mastodon instance (e.g. https://mastodon.social).
Source: Mastodon REST API v1/v2
Coverage
86% (112 of ~130 endpoints)
Focus: accounts (lookup + verify + follow/unfollow + mute/block + relationships + search), statuses (CRUD + favourite + reblog + bookmark + pin + context + translate), timelines (home + public + hashtag + list), notifications (list + dismiss + clear + unread count), search (v2 full-text), media (upload + update), lists (CRUD + members), polls (view + vote), conversations (list + read + delete), trends (tags + statuses + links), filters v2 (CRUD + keywords), bookmarks, favourites, mutes, blocks, follow requests, suggestions, instance info, scheduled statuses (CRUD), markers (get + save), reports (create), featured tags (CRUD + suggestions), announcements (list + dismiss), endorsements, preferences, admin accounts (list + get + approve + reject + action + unsuspend + unsilence), admin domain blocks (CRUD)
Missing: streaming WebSocket, email confirmations, canonical email blocks, ip blocks, dimensions, measures, retention, trends admin, admin reports, admin audit log
Setup
- Open your Mastodon instance (e.g. https://mastodon.social)
- Go to Preferences → Development → New Application
- Enter an application name (e.g. 'ToolMesh')
- Select required scopes: read, write (or granular scopes as needed)
- Click 'Submit' to create the application
- Copy the 'Your access token' value — this is your Bearer token
Environment variable: CREDENTIAL_MASTODON_ACCESS_TOKEN
The base_url must be set to the user's Mastodon instance. Each instance is independent — tokens from mastodon.social do not work on other instances. For app-level access (public data only), use OAuth2 client_credentials grant. For user-level access, use the authorization_code grant or generate a token via the web UI under Preferences → Development.
Install
Add to your backends.yaml:
- name: mastodon
transport: rest
dadl: mastodon.dadl
url: "https://mastodon.social"
Set the credential:
CREDENTIAL_MASTODON_ACCESS_TOKEN=your-token-hereTools (115)
GET get_instance Get server information including version, configuration, usage stats, rules, and supported features GET get_instance_peers List domains that this instance is aware of (connected via federation) GET get_instance_activity Get weekly activity statistics (statuses, logins, registrations) GET get_instance_rules List server rules displayed on the about page GET get_instance_extended_description Get the extended description of the instance (admin-defined HTML) GET verify_credentials Verify the access token and get the authenticated user's account PATCH update_credentials Update the authenticated user's display name, bio, avatar, header, fields, and privacy settings GET get_account View a profile by account ID GET lookup_account Lookup an account by WebFinger address (user@domain or local username) GET get_account_statuses Get statuses posted by the given account GET get_account_followers List accounts that follow the given account GET get_account_following List accounts that the given account follows GET get_relationships Check relationship (following, blocked, muted, etc.) with one or more accounts GET get_familiar_followers Find mutual followers between you and given accounts GET search_accounts Search for accounts by username or display name POST follow_account Follow an account POST unfollow_account Unfollow an account POST remove_follower Remove an account from your followers POST block_account Block an account POST unblock_account Unblock an account POST mute_account Mute an account (hide from timelines and optionally notifications) POST unmute_account Unmute an account POST set_account_note Set a private note on an account (only visible to you) POST create_status Create a new status (post/toot). Requires status text or media_ids. GET get_status View a single status by ID PUT edit_status Edit an existing status DELETE delete_status Delete a status. Returns the deleted status with a text field for redraft. GET get_status_context Get the thread context — ancestors (parents) and descendants (replies) of a status GET get_status_source Get the plaintext source of a status for editing GET get_status_history Get the edit history of a status POST translate_status Translate a status into the user's language (if translation is supported by the instance) GET get_reblogged_by List accounts that boosted/reblogged a status GET get_favourited_by List accounts that favourited a status POST favourite_status Favourite/like a status POST unfavourite_status Undo favourite on a status POST reblog_status Boost/reblog a status to your followers POST unreblog_status Undo a boost/reblog POST bookmark_status Bookmark a status (private, only visible to you) POST unbookmark_status Remove a status from your bookmarks POST mute_status Mute notifications for a status thread POST unmute_status Unmute notifications for a status thread POST pin_status Pin a status to your profile POST unpin_status Unpin a status from your profile GET timeline_home Get home timeline (statuses from followed accounts and hashtags) GET timeline_public Get public timeline (federated or local) GET timeline_hashtag Get statuses with the given hashtag GET timeline_list Get timeline for a specific list GET list_notifications List notifications (mentions, favourites, boosts, follows, polls, etc.) GET get_notification Get a single notification by ID POST dismiss_notification Dismiss a single notification POST clear_notifications Dismiss all notifications (irreversible) GET get_unread_notification_count Get count of unread notifications GET search_v2 Full-text search across accounts, statuses, and hashtags. Returns { accounts, statuses, hashtags } arrays. POST upload_media Upload a media attachment (image, video, audio). Returns 200 or 202 (processing). Attach to a status via media_ids. GET get_media Check media attachment processing status. Returns 200 when ready, 206 when still processing. PUT update_media Update media description or focal point (before attaching to a status) GET get_poll View a poll and its current results POST vote_poll Vote on a poll GET list_lists Get all lists created by the authenticated user GET get_list Get a single list by ID POST create_list Create a new list PUT update_list Update a list's title or settings DELETE delete_list Delete a list GET get_list_accounts List accounts that are members of a list POST add_list_accounts Add accounts to a list (must be accounts you already follow) DELETE remove_list_accounts Remove accounts from a list GET list_conversations List direct message conversations DELETE delete_conversation Remove a conversation from your list (does not delete messages) POST mark_conversation_read Mark a conversation as read GET trending_tags Get trending hashtags over the past week GET trending_statuses Get trending statuses GET trending_links Get trending links (news articles shared frequently) GET list_bookmarks List bookmarked statuses GET list_favourites List favourited statuses GET list_muted_accounts List muted accounts GET list_blocked_accounts List blocked accounts GET list_follow_requests List pending follow requests POST authorize_follow_request Accept a pending follow request POST reject_follow_request Reject a pending follow request GET get_suggestions Get follow suggestions (staff picks and accounts based on past interactions) DELETE remove_suggestion Remove an account from follow suggestions GET list_filters List all content filters GET get_filter Get a single filter by ID POST create_filter Create a content filter with keywords PUT update_filter Update a content filter DELETE delete_filter Delete a content filter POST create_app Register a new OAuth application. Returns client_id and client_secret. GET verify_app_credentials Verify that the app token is valid and get application info GET list_scheduled_statuses List scheduled statuses (posts queued for future publication via scheduled_at) GET get_scheduled_status Get a single scheduled status by ID PUT update_scheduled_status Update the scheduled publication time of a status DELETE delete_scheduled_status Cancel and delete a scheduled status GET get_markers Get saved reading positions for home timeline and/or notifications POST save_markers Save reading positions for home timeline and/or notifications POST create_report Report an account to instance moderators GET list_featured_tags List hashtags featured on your profile POST create_featured_tag Feature a hashtag on your profile DELETE delete_featured_tag Remove a featured hashtag from your profile GET get_featured_tag_suggestions Get suggested hashtags to feature (based on your most used tags) GET list_announcements List server announcements (active and recent) POST dismiss_announcement Mark an announcement as read/dismissed GET list_endorsements List accounts endorsed (featured) on your profile GET get_preferences Get user preferences (default visibility, language, sensitive flag, expand media, expand spoilers) GET admin_list_accounts List accounts with admin-level detail (email, IP, status). Requires admin:read:accounts scope. GET admin_get_account Get admin-level detail for a single account POST admin_approve_account Approve a pending account registration POST admin_reject_account Reject a pending account registration POST admin_disable_account Perform a moderation action on an account (disable, silence, suspend, none) POST admin_unsuspend_account Unsuspend a suspended account POST admin_unsilence_account Unsilence a silenced account GET admin_list_domain_blocks List blocked domains. Requires admin:read:domain_blocks scope. GET admin_get_domain_block Get a single domain block by ID POST admin_create_domain_block Block a domain from federating. Requires admin:write:domain_blocks scope. PUT admin_update_domain_block Update a domain block DELETE admin_delete_domain_block Remove a domain block (re-enable federation)