Mastodon.py
Usage
Register your app! This only needs to be done once (per server, or when distributing rather than hosting an application, most likely per device and server). Uncomment the code and substitute in your information:
from mastodon import Mastodon
'''
Mastodon.create_app(
'pytooterapp',
api_base_url = 'https://mastodon.social',
to_file = 'pytooter_clientcred.secret'
)
'''
Then, log in. This can be done every time your application starts, or you can use the persisted information:
from mastodon import Mastodon
mastodon = Mastodon(client_id = 'pytooter_clientcred.secret',)
print(mastodon.auth_request_url())
# open the URL in the browser and paste the code you get
mastodon.log_in(
code=input("Enter the OAuth authorization code: "),
to_file="pytooter_usercred.secret"
)
Note that previous versions of Mastodon allowed logging in with username and password - unfortunately, due to security concerns, Mastodon has started requiring OAuth starting with version 4.4.0. If you’re building a bot, you may with to instead just generate a token in the UI (On Mastodon: your-server.com/settings/applications) and use it directly
To post, create an actual API instance:
from mastodon import Mastodon
mastodon = Mastodon(access_token = 'pytooter_usercred.secret')
mastodon.toot('Tooting from Python using #mastodonpy !')
Introduction
Mastodon is an ActivityPub-based Twitter-like federated social network node. It has an API that allows you to interact with its every aspect. This is a simple Python wrapper for that API, provided as a single Python module.
Mastodon.py aims to implement the complete public Mastodon API. As of this time, it is feature complete for Mastodon version 4.3.0. The Mastodon compatible API layers of various other pieces of software as well as forks, while not an official target, should also be basically compatible, and Mastodon.py does make some allowances for behaviour that isn’t strictly like that of Mastodon, and attempts to support extensions to the API.
Some usage examples (not neccesarily following app development best practices, but enough to get you started if you learn best by example) can be found at https://github.com/halcy/MastodonpyExamples
Acknowledgements
Mastodon.py contains work by a large number of contributors, many of which have put significant work into making it a better library. You can find some information about who helped with which particular feature or fix in the changelog.
Research use and citing
If you use Mastodon.py in your research, please cite it according to the latest CITATION.cff from the repository:
https://github.com/halcy/Mastodon.py/blob/master/CITATION.cff
As a personal request, It is important to me to ask you to make sure that the subjects of your research - fediverse users - are alright with the research you are doing on them and/or that you have secured the approval of your institutions ethics board.
Introduction
- Mastodon.py
- General information
- Return values
- Base types
- Return types
Account
Account.id
Account.username
Account.acct
Account.display_name
Account.discoverable
Account.group
Account.locked
Account.created_at
Account.following_count
Account.followers_count
Account.statuses_count
Account.note
Account.url
Account.uri
Account.avatar
Account.header
Account.avatar_static
Account.header_static
Account.moved_to_account
Account.suspended
Account.limited
Account.bot
Account.fields
Account.emojis
Account.last_status_at
Account.noindex
Account.roles
Account.role
Account.source
Account.mute_expires_at
Account.indexable
Account.hide_collections
Account.memorial
AccountField
Role
CredentialAccountSource
CredentialAccountSource.privacy
CredentialAccountSource.sensitive
CredentialAccountSource.note
CredentialAccountSource.language
CredentialAccountSource.fields
CredentialAccountSource.follow_requests_count
CredentialAccountSource.indexable
CredentialAccountSource.hide_collections
CredentialAccountSource.discoverable
Status
Status.id
Status.uri
Status.url
Status.account
Status.in_reply_to_id
Status.in_reply_to_account_id
Status.reblog
Status.content
Status.created_at
Status.reblogs_count
Status.favourites_count
Status.reblogged
Status.favourited
Status.sensitive
Status.spoiler_text
Status.visibility
Status.mentions
Status.media_attachments
Status.emojis
Status.tags
Status.bookmarked
Status.application
Status.language
Status.muted
Status.pinned
Status.replies_count
Status.card
Status.poll
Status.edited_at
Status.filtered
StatusEdit
FilterResult
StatusMention
ScheduledStatus
ScheduledStatusParams
ScheduledStatusParams.text
ScheduledStatusParams.in_reply_to_id
ScheduledStatusParams.media_ids
ScheduledStatusParams.sensitive
ScheduledStatusParams.visibility
ScheduledStatusParams.idempotency
ScheduledStatusParams.scheduled_at
ScheduledStatusParams.spoiler_text
ScheduledStatusParams.application_id
ScheduledStatusParams.poll
ScheduledStatusParams.language
ScheduledStatusParams.allowed_mentions
ScheduledStatusParams.with_rate_limit
Poll
PollOption
Conversation
Tag
TagHistory
CustomEmoji
Application
Relationship
Relationship.id
Relationship.following
Relationship.followed_by
Relationship.blocking
Relationship.blocked_by
Relationship.muting
Relationship.muting_notifications
Relationship.requested
Relationship.domain_blocking
Relationship.showing_reblogs
Relationship.endorsed
Relationship.note
Relationship.notifying
Relationship.languages
Relationship.requested_by
FilterV2
Notification
Context
UserList
MediaAttachment
MediaAttachmentMetadataContainer
MediaAttachmentImageMetadata
MediaAttachmentVideoMetadata
MediaAttachmentAudioMetadata
MediaAttachmentFocusPoint
MediaAttachmentColors
PreviewCard
PreviewCard.url
PreviewCard.title
PreviewCard.description
PreviewCard.type
PreviewCard.image
PreviewCard.author_name
PreviewCard.author_url
PreviewCard.width
PreviewCard.height
PreviewCard.html
PreviewCard.provider_name
PreviewCard.provider_url
PreviewCard.blurhash
PreviewCard.language
PreviewCard.embed_url
PreviewCard.authors
PreviewCard.image_description
PreviewCard.published_at
PreviewCard.history
TrendingLinkHistory
PreviewCardAuthor
SearchV2
Instance
Instance.uri
Instance.title
Instance.short_description
Instance.description
Instance.email
Instance.version
Instance.urls
Instance.stats
Instance.thumbnail
Instance.languages
Instance.registrations
Instance.approval_required
Instance.invites_enabled
Instance.configuration
Instance.contact_account
Instance.rules
InstanceConfiguration
InstanceURLs
InstanceV2
InstanceIcon
InstanceConfigurationV2
InstanceVapidKey
InstanceURLsV2
InstanceThumbnail
InstanceThumbnailVersions
InstanceStatistics
InstanceUsage
InstanceUsageUsers
Rule
InstanceRegistrations
InstanceContact
InstanceAccountConfiguration
InstanceStatusConfiguration
InstanceTranslationConfiguration
InstanceMediaConfiguration
InstancePollConfiguration
Nodeinfo
NodeinfoSoftware
NodeinfoServices
NodeinfoUsage
NodeinfoUsageUsers
NodeinfoMetadata
Activity
Report
AdminReport
AdminReport.id
AdminReport.action_taken
AdminReport.comment
AdminReport.created_at
AdminReport.updated_at
AdminReport.account
AdminReport.target_account
AdminReport.assigned_account
AdminReport.action_taken_by_account
AdminReport.statuses
AdminReport.action_taken_at
AdminReport.category
AdminReport.forwarded
AdminReport.rules
WebPushSubscription
WebPushSubscriptionAlerts
WebPushSubscriptionAlerts.follow
WebPushSubscriptionAlerts.favourite
WebPushSubscriptionAlerts.reblog
WebPushSubscriptionAlerts.mention
WebPushSubscriptionAlerts.poll
WebPushSubscriptionAlerts.follow_request
WebPushSubscriptionAlerts.status
WebPushSubscriptionAlerts.admin_sign_up
WebPushSubscriptionAlerts.admin_report
PushNotification
Preferences
FeaturedTag
Marker
Announcement
Reaction
StreamReaction
FamiliarFollowers
AdminAccount
AdminAccount.id
AdminAccount.username
AdminAccount.domain
AdminAccount.created_at
AdminAccount.email
AdminAccount.ip
AdminAccount.role
AdminAccount.confirmed
AdminAccount.suspended
AdminAccount.silenced
AdminAccount.disabled
AdminAccount.approved
AdminAccount.locale
AdminAccount.invite_request
AdminAccount.account
AdminAccount.sensitized
AdminAccount.ips
AdminAccount.created_by_application_id
AdminAccount.invited_by_account_id
AdminIp
AdminMeasure
AdminMeasureData
AdminDimension
AdminDimensionData
AdminRetention
AdminCohort
AdminDomainBlock
AdminCanonicalEmailBlock
AdminDomainAllow
AdminEmailDomainBlock
AdminEmailDomainBlockHistory
AdminIpBlock
DomainBlock
ExtendedDescription
FilterKeyword
FilterStatus
StatusSource
Suggestion
Translation
AccountCreationError
AccountCreationErrorDetails
AccountCreationErrorDetailsField
NotificationPolicy
NotificationPolicySummary
RelationshipSeveranceEvent
GroupedNotificationsResults
PartialAccountWithAvatar
NotificationGroup
NotificationGroup.group_key
NotificationGroup.notifications_count
NotificationGroup.type
NotificationGroup.most_recent_notification_id
NotificationGroup.page_min_id
NotificationGroup.page_max_id
NotificationGroup.latest_page_notification_at
NotificationGroup.sample_account_ids
NotificationGroup.status_id
NotificationGroup.report
NotificationGroup.event
NotificationGroup.moderation_warning
AccountWarning
UnreadNotificationsCount
Appeal
NotificationRequest
SupportedLocale
- Deprecated types
- Error handling
API methods
- App registration, authentication and preferences
- Statuses, media and polls
- Statuses
- Reading
- Writing
Mastodon.status_post()
Mastodon.status_reply()
Mastodon.toot()
Mastodon.make_poll()
Mastodon.status_reblog()
Mastodon.status_unreblog()
Mastodon.status_favourite()
Mastodon.status_unfavourite()
Mastodon.status_mute()
Mastodon.status_unmute()
Mastodon.status_bookmark()
Mastodon.status_unbookmark()
Mastodon.status_delete()
Mastodon.status_update()
Mastodon.generate_media_edit_attributes()
- Scheduled statuses
- Media
- Polls
- Translation
- Statuses
- Accounts, relationships and lists
- Accounts
- Reading
Mastodon.account_verify_credentials()
Mastodon.me()
Mastodon.account()
Mastodon.account_search()
Mastodon.account_lookup()
Mastodon.accounts()
Mastodon.featured_tags()
Mastodon.featured_tag_suggestions()
Mastodon.account_featured_tags()
Mastodon.endorsements()
Mastodon.account_statuses()
Mastodon.account_familiar_followers()
Mastodon.account_lists()
- Writing
- Reading
- Following and followers
- Mutes and blocks
- Lists
- Following tags
- Accounts
- Reading data: Timelines
- Instance-wide data and search
- Instance information
- Announcements
- Trends
- Search
- Domain blocks
- Translation support
- Notifications and filtering
- Notifications
- Grouped notifications
- Source filtering for notifications
Mastodon.notifications_policy()
Mastodon.update_notifications_policy()
Mastodon.notification_requests()
Mastodon.notification_request()
Mastodon.accept_notification_request()
Mastodon.dismiss_notification_request()
Mastodon.accept_multiple_notification_requests()
Mastodon.dismiss_multiple_notification_requests()
Mastodon.notifications_merged()
- Keyword Filters (v2)
Mastodon.filters_v2()
Mastodon.filter_v2()
Mastodon.create_filter_v2()
Mastodon.update_filter_v2()
Mastodon.delete_filter_v2()
Mastodon.filter_keywords_v2()
Mastodon.add_filter_keyword_v2()
Mastodon.delete_filter_keyword_v2()
Mastodon.filter_statuses_v2()
Mastodon.add_filter_status_v2()
Mastodon.filter_status_v2()
Mastodon.delete_filter_status_v2()
- Push notifications
- Keyword filters (v1, deprecated)
- Streaming
- Stream endpoints
- StreamListener
- Misc: Markers, reports
- Utility: Pagination and Blurhash
- Administration and moderation
- Accounts
Mastodon.admin_accounts_v2()
Mastodon.admin_accounts()
Mastodon.admin_accounts_v1()
Mastodon.admin_account()
Mastodon.admin_account_enable()
Mastodon.admin_account_approve()
Mastodon.admin_account_reject()
Mastodon.admin_account_unsilence()
Mastodon.admin_account_unsuspend()
Mastodon.admin_account_moderate()
- Reports
- Federation
- Moderation actions
- Canonical email blocks
- Email domain blocks
- IP blocks
- Trend management
Mastodon.admin_trending_tags()
Mastodon.admin_trending_statuses()
Mastodon.admin_trending_links()
Mastodon.admin_approve_trending_link()
Mastodon.admin_reject_trending_link()
Mastodon.admin_approve_trending_status()
Mastodon.admin_reject_trending_status()
Mastodon.admin_approve_trending_tag()
Mastodon.admin_reject_trending_tag()
- Accounts