Mastodon

Mastodon API Specification (https://github.com/mastodon/mastodon)

Mastodon API Specification (https://github.com/mastodon/mastodon) endpoints from Mastodon

Social#openapi#social

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Mastodon API Specification (https://github.com/mastodon/mastodon) endpoints from Mastodon

Endpoints 127

TODOSecurity

  • POSTPOST /api/v1/accounts/api/v1/accountsCreates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and…

accounts

  • GETGET /api/v1/accounts/relationships/api/v1/accounts/relationships?id=stringSets a private note on a user.
  • GETGET /api/v1/accounts/search/api/v1/accounts/search?q=string&limit=40&resolve=string&following=trueSearch for matching accounts by username or display name.
  • PATCHPATCH /api/v1/accounts/update_credentials/api/v1/accounts/update_credentialsUpdate the user's display and preferences.
  • GETGET /api/v1/accounts/verify_credentials/api/v1/accounts/verify_credentialsTest to make sure that the user token works.
  • GETGET /api/v1/accounts/{id}/api/v1/accounts/:id
  • POSTPOST /api/v1/accounts/{id}/block/api/v1/accounts/:id/blockBlock the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline).
  • GETGET /api/v1/accounts/{id}/featured_tags/api/v1/accounts/:id/featured_tagsTags featured by this account.
  • POSTPOST /api/v1/accounts/{id}/follow/api/v1/accounts/:id/followFollow the given account. Can also be used to update whether to show reblogs or enable notifications.
  • GETGET /api/v1/accounts/{id}/followers/api/v1/accounts/:id/followers?max_id=string&since_id=string&limit=40Accounts which follow the given account, if network is not hidden by the account owner.
  • GETGET /api/v1/accounts/{id}/following/api/v1/accounts/:id/following?max_id=string&since_id=string&limit=40Accounts which the given account is following, if network is not hidden by the account owner.
  • GETGET /api/v1/accounts/{id}/identity_proofs/api/v1/accounts/:id/identity_proofsArray of IdentityProof
  • GETGET /api/v1/accounts/{id}/lists/api/v1/accounts/:id/listsUser lists that you have added this account to.
  • POSTPOST /api/v1/accounts/{id}/mute/api/v1/accounts/:id/muteMute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).
  • POSTPOST /api/v1/accounts/{id}/note/api/v1/accounts/:id/noteSets a private note on a user.
  • POSTPOST /api/v1/accounts/{id}/pin/api/v1/accounts/:id/pinAdd the given account to the user's featured profiles. (Featured profiles are currently shown on the user's own public profile.)
  • GETGET /api/v1/accounts/{id}/statuses/api/v1/accounts/:id/statusesStatuses posted to the given account.
  • POSTPOST /api/v1/accounts/{id}/unblock/api/v1/accounts/:id/unblockBlock the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline).
  • POSTPOST /api/v1/accounts/{id}/unfollow/api/v1/accounts/:id/unfollowUnfollow the given account.
  • POSTPOST /api/v1/accounts/{id}/unmute/api/v1/accounts/:id/unmuteUnmute the given account.
  • POSTPOST /api/v1/accounts/{id}/unpin/api/v1/accounts/:id/unpinRemove the given account from the user's featured profiles.

apps

  • POSTPOST /api/v1/apps/api/v1/appsCreate a new application to obtain OAuth2 credentials.
  • GETGET /api/v1/apps/verify_credentials/api/v1/apps/verify_credentialsConfirm that the app's OAuth2 credentials work.

oauth

  • GETGET /oauth/authorize/oauth/authorize?response_type=string&client_id=string&redirect_uri=string&scope=string&force_login=trueDisplays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired redirect_uri, or show…
  • POSTPOST /oauth/revoke/oauth/revokeRevoke an access token to make it no longer valid for use.
  • POSTPOST /oauth/token/oauth/tokenReturns an access token, to be used during API calls that are not public.
  • GETGET /api/oembed/api/oembed?url=string&maxwidth=400&maxheight=0OEmbed as JSON
  • GETGET /api/proofs/api/proofs?provider=string&username=stringView identity proof
  • GETGET /api/v1/admin/accounts/api/v1/admin/accounts?local=true&remote=true&by_domain=string&active=true&pending=true&disabled=true&silenced=true&suspended=true&staff=true&username=string&display_name=string&email=string&ip=stringView accounts matching certain criteria for filtering, up to 100 at a time. Pagination may be done with the HTTP Link header in the response.
  • GETGET /api/v1/admin/accounts/{id}/api/v1/admin/accounts/:idView admin-level information about the given account.
  • POSTPOST /api/v1/admin/accounts/{id}/action/api/v1/admin/accounts/:id/actionPerform an action against an account and log this action in the moderation history.
  • POSTPOST /api/v1/admin/accounts/{id}/approve/api/v1/admin/accounts/:id/approveApprove the given local account if it is currently pending approval.
  • POSTPOST /api/v1/admin/accounts/{id}/enable/api/v1/admin/accounts/:id/enableRe-enable a local account whose login is currently disabled.
  • POSTPOST /api/v1/admin/accounts/{id}/reject/api/v1/admin/accounts/:id/rejectReject the given local account if it is currently pending approval.
  • POSTPOST /api/v1/admin/accounts/{id}/unsilence/api/v1/admin/accounts/:id/unsilenceUnsilence a currently silenced account.
  • POSTPOST /api/v1/admin/accounts/{id}/unsuspend/api/v1/admin/accounts/:id/unsuspendUnsuspend a currently suspended account.
  • GETGET /api/v1/admin/reports/api/v1/admin/reports?resolved=true&account_id=string&target_account_id=stringView all reports. Pagination may be done with HTTP Link header in the response.
  • GETGET /api/v1/admin/reports/{id}/api/v1/admin/reports/:idView information about the report with the given ID.
  • POSTPOST /api/v1/admin/reports/{id}/assign_to_self/api/v1/admin/reports/:id/assign_to_selfClaim the handling of this report to yourself.
  • POSTPOST /api/v1/admin/reports/{id}/reopen/api/v1/admin/reports/:id/reopenMark a report as resolved with no further action taken.
  • POSTPOST /api/v1/admin/reports/{id}/resolve/api/v1/admin/reports/:id/resolveMark a report as resolved with no further action taken.
  • POSTPOST /api/v1/admin/reports/{id}/unassign/api/v1/admin/reports/:id/unassignUnassign a report so that someone else can claim it.
  • GETGET /api/v1/announcements/api/v1/announcements?with_dismissed=trueSee all currently active announcements set by admins.
  • POSTPOST /api/v1/announcements/{id}/dismiss/api/v1/announcements/:id/dismissAllows a user to mark the announcement as read.
  • PUTPUT /api/v1/announcements/{id}/reactions/{name}/api/v1/announcements/:id/reactions/:nameAllows a user to mark the announcement as read.
  • DELETEDELETE /api/v1/announcements/{id}/reactions/{name}/api/v1/announcements/:id/reactions/:nameUndo a react emoji to an announcement.
  • GETGET /api/v1/blocks/api/v1/blocks?limit=0&max_id=string&since_id=stringGet blocked users.
  • GETGET /api/v1/bookmarks/api/v1/bookmarks?limit=0&max_id=string&since_id=string&min_id=stringStatuses the user has bookmarked.
  • GETGET /api/v1/conversations/api/v1/conversations?limit=20&max_id=string&since_id=string&min_id=stringShow conversation.
  • DELETEDELETE /api/v1/conversations/{id}/api/v1/conversations/:idRemove converstation
  • POSTPOST /api/v1/conversations/{id}/read/api/v1/conversations/:id/readRemove converstation
  • GETGET /api/v1/custom_emojis/api/v1/custom_emojisReturns custom emojis that are available on the server.
  • GETGET /api/v1/directory/api/v1/directory?limit=40&offset=0&order=active&local=trueList accounts visible in the directory.
  • GETGET /api/v1/domain_blocks/api/v1/domain_blocks?limit=0&max_id=string&since_id=stringView domains the user has blocked.
  • POSTPOST /api/v1/domain_blocks/api/v1/domain_blocks"Block a domain to: hide all public posts from it hide all notifications from it remove all followers from it prevent following new users from it (but does…
  • DELETEDELETE /api/v1/domain_blocks/api/v1/domain_blocks?domain=stringRemove a domain block, if it exists in the user's array of blocked domains.
  • GETGET /api/v1/endorsements/api/v1/endorsements?limit=40&max_id=string&since_id=stringAccounts that the user is currently featuring on their profile.
  • GETGET /api/v1/favourites/api/v1/favourites?limit=string&max_id=string&min_id=stringStatuses the user has favourited.
  • GETGET /api/v1/featured_tags/api/v1/featured_tagsView your featured tags.
  • POSTPOST /api/v1/featured_tags/api/v1/featured_tagsCreate a feature a tag.
  • GETGET /api/v1/featured_tags/suggestions/api/v1/featured_tags/suggestionsShows your 10 most-used tags, with usage history for the past week.
  • DELETEDELETE /api/v1/featured_tags/{id}/api/v1/featured_tags/:idUnfeature a tag
  • GETGET /api/v1/filters/api/v1/filters
  • POSTPOST /api/v1/filters/api/v1/filters
  • GETGET /api/v1/filters/{id}/api/v1/filters/:idGet one filter.
  • PUTPUT /api/v1/filters/{id}/api/v1/filters/:idUpdate a filter.
  • DELETEDELETE /api/v1/filters/{id}/api/v1/filters/:idDelete a filter.
  • GETGET /api/v1/follow_requests/api/v1/follow_requests?limit=40Pending Follows
  • POSTPOST /api/v1/follow_requests/{id}/authorize/api/v1/follow_requests/:id/authorizeAccept Follow
  • POSTPOST /api/v1/follow_requests/{id}/reject/api/v1/follow_requests/:id/rejectAccept Follow
  • GETGET /api/v1/instance/api/v1/instanceInformation about the server.
  • GETGET /api/v1/instance/activity/api/v1/instance/activityInstance activity over the last 3 months, binned weekly.
  • GETGET /api/v1/instance/peers/api/v1/instance/peersInformation about the server.
  • GETGET /api/v1/lists/api/v1/listsFetch all lists that the user owns.
  • PUTPUT /api/v1/lists/api/v1/listsChange the title of a list, or which replies to show.
  • POSTPOST /api/v1/lists/api/v1/listsCreate a new list.
  • DELETEDELETE /api/v1/lists/api/v1/listsDelete a list
  • GETGET /api/v1/lists/{id}/api/v1/lists/:idRemove converstation
  • GETGET /api/v1/lists/{id}/accounts/api/v1/lists/:id/accounts?limit=40&max_id=string&since_id=stringView accounts in List
  • POSTPOST /api/v1/lists/{id}/accounts/api/v1/lists/:id/accountsAdd accounts to the given list. Note that the user must be following these accounts.
  • DELETEDELETE /api/v1/lists/{id}/accounts/api/v1/lists/:id/accounts?account_ids=stringRemove accounts from the given list.
  • GETGET /api/v1/markers/api/v1/markers?timeline={}Get saved timeline position
  • POSTPOST /api/v1/markers/api/v1/markersGet saved timeline position
  • POSTPOST /api/v1/media/api/v1/mediaCreates an attachment to be used with a new status.
  • GETGET /api/v1/media/{id}/api/v1/media/:idGet an attachement.
  • POSTPOST /api/v1/media/{id}/api/v1/media/:idUpdate an Attachment, before it is attached to a status and posted.
  • GETGET /api/v1/mutes/api/v1/mutes?limit=string&max_id=string&since_id=stringAccounts the user has muted.
  • GETGET /api/v1/notifications/api/v1/notifications?limit=20&max_id=string&since_id=string&min_id=string&exclude_types=string&account_id=stringNotifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed…
  • POSTPOST /api/v1/notifications/clear/api/v1/notifications/clearClear all notifications from the server.
  • GETGET /api/v1/notifications/{id}/api/v1/notifications/:idView information about a notification with a given ID.
  • POSTPOST /api/v1/notifications/{id}/dismiss/api/v1/notifications/:id/dismissClear a single notification from the server.
  • GETGET /api/v1/polls/{id}/api/v1/polls/:idView a poll.
  • POSTPOST /api/v1/polls/{id}/api/v1/polls/:idVote on a poll.
  • GETGET /api/v1/preferences/api/v1/preferencesShows your 10 most-used tags, with usage history for the past week.
  • GETGET /api/v1/push/subscription/api/v1/push/subscriptionView the PushSubscription currently associated with this access token.
  • PUTPUT /api/v1/push/subscription/api/v1/push/subscriptionUpdates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
  • POSTPOST /api/v1/push/subscription/api/v1/push/subscriptionAdd a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old…
  • DELETEDELETE /api/v1/push/subscription/api/v1/push/subscriptionUpdates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
  • POSTPOST /api/v1/reports/api/v1/reportsFile a report.
  • GETGET /api/v1/scheduled_statuses/api/v1/scheduled_statuses?limit=20&max_id=string&since_id=string&min_id=stringView scheduled statuses
  • GETGET /api/v1/scheduled_statuses/{id}/api/v1/scheduled_statuses/:idView a single scheduled status
  • PUTPUT /api/v1/scheduled_statuses/{id}/api/v1/scheduled_statuses/:idView a single scheduled status
  • DELETEDELETE /api/v1/scheduled_statuses/{id}/api/v1/scheduled_statuses/:idCancel a scheduled status
  • POSTPOST /api/v1/statuses/api/v1/statuses
  • GETGET /api/v1/statuses/{id}/api/v1/statuses/:id
  • DELETEDELETE /api/v1/statuses/{id}/api/v1/statuses/:id
  • POSTPOST /api/v1/statuses/{id}/bookmark/api/v1/statuses/:id/bookmarkPrivately bookmark a status.
  • GETGET /api/v1/statuses/{id}/context/api/v1/statuses/:id/context
  • POSTPOST /api/v1/statuses/{id}/favourite/api/v1/statuses/:id/favouriteAdd a status to your favourites list.
  • GETGET /api/v1/statuses/{id}/favourited_by/api/v1/statuses/:id/favourited_byView who favourited a given status.
  • POSTPOST /api/v1/statuses/{id}/mute/api/v1/statuses/:id/muteDo not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.
  • POSTPOST /api/v1/statuses/{id}/pin/api/v1/statuses/:id/pinFeature one of your own public statuses at the top of your profile.
  • POSTPOST /api/v1/statuses/{id}/reblog/api/v1/statuses/:id/reblogReshare a status.
  • GETGET /api/v1/statuses/{id}/reblogged_by/api/v1/statuses/:id/reblogged_byView who boosted a given status.
  • POSTPOST /api/v1/statuses/{id}/unbookmark/api/v1/statuses/:id/unbookmarkRemove a status from your private bookmarks.
  • POSTPOST /api/v1/statuses/{id}/unfavourite/api/v1/statuses/:id/unfavouriteRemove a status from your favourites list.
  • POSTPOST /api/v1/statuses/{id}/unmute/api/v1/statuses/:id/unmuteStatus's conversation unmuted, or was already unmuted
  • POSTPOST /api/v1/statuses/{id}/unpin/api/v1/statuses/:id/unpinUnfeature a status from the top of your profile.
  • POSTPOST /api/v1/statuses/{id}/unreblog/api/v1/statuses/:id/unreblogUndo a reshare of a status.
  • GETGET /api/v1/suggestions/api/v1/suggestions?limit=40Accounts the user has had past positive interactions with, but is not yet following.
  • DELETEDELETE /api/v1/suggestions/{id}/api/v1/suggestions/:idDelete user suggestion
  • GETGET /api/v1/timelines/home/api/v1/timelines/home?local=false&limit=20&max_id=string&since_id=string&min_id=stringView statuses from followed users.
  • GETGET /api/v1/timelines/list/{list_id}/api/v1/timelines/list/:list_id?limit=20&max_id=string&since_id=string&min_id=stringView statuses in the given list timeline.
  • GETGET /api/v1/timelines/public/api/v1/timelines/public?local=false&remote=false&only_media=false&limit=20&max_id=string&since_id=string&min_id=stringPublic timeline
  • GETGET /api/v1/timelines/tag/{hashtag}/api/v1/timelines/tag/:hashtag?local=false&remote=false&only_media=false&limit=20&max_id=string&since_id=string&min_id=stringView public statuses containing the given hashtag.
  • GETGET /api/v1/trends/api/v1/trends?limit=10Tags that are being used more frequently within the past week.
  • GETGET /api/v2/search/api/v2/search?q=string&limit=20&resolve=string&following=true&account_id=string&max_id=string&min_id=string&type=accounts&exclude_unreviewed=true&offset=0Search results

API details

Base URL
http://mastodon.local
https://mastodon.social
Authentication
A bearer token in the Authorization header
OAuth 2.0 (authorization code flow) with 30 scopes
Operations
127 operations on 106 pathsGET 59POST 51DELETE 11PUT 5PATCH 1
Main resources
accounts 21oauth 3apps 2TODOSecurity 1
Response formats
application/json
Description format
OpenAPI 3.0.3, API version 1.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Mastodon API Specification (https://github.com/mastodon/mastodon) in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Mastodon API Specification (https://github.com/mastodon/mastodon) collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “POST /api/v1/accounts” (POST /api/v1/accounts), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Mastodon API Specification (https://github.com/mastodon/mastodon)?

Mastodon API Specification (https://github.com/mastodon/mastodon) endpoints from Mastodon It is listed under Social and has 127 endpoints.

Who publishes the Mastodon API Specification (https://github.com/mastodon/mastodon)?

It is listed from Mastodon's public API description (an OpenAPI document), not published by Mastodon on Swastik Codes. Anyone who controls joinmastodon.org can claim the profile by adding a DNS TXT record.

What is the base URL of the Mastodon API Specification (https://github.com/mastodon/mastodon)?

Its description lists 2 base URLs: http://mastodon.local, https://mastodon.social. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Mastodon API Specification (https://github.com/mastodon/mastodon)?

It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (authorization code flow) with 30 scopes.

How many endpoints does the Mastodon API Specification (https://github.com/mastodon/mastodon) have?

127 operations on 106 paths (59 GET, 51 POST, 11 DELETE, 5 PUT, 1 PATCH). The largest groups are accounts, oauth, apps, TODOSecurity.

Is forking the Mastodon API Specification (https://github.com/mastodon/mastodon) free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.