- API Documentation: https://docs.joinmastodon.org/api/ (scroll down, the different API endpoints are listed in the TOC under API Methods)
Code Samples
Using Mastodon.py, and see https://git.jon-e.net/jonny/masto-gitsocial-bridge for more examples from a sort of infrastructural shitpost
- Interacting with masto: https://git.jon-e.net/jonny/masto-gitsocial-bridge/src/branch/main/masto_git_bridge/bot.py
- Post model: https://git.jon-e.net/jonny/masto-gitsocial-bridge/src/branch/main/masto_git_bridge/post.py
Make Masto Token
Most of the interesting parts of the API need you to log in underneath an account, and so for that you need to make an auth token:
From your masto instance's homepage...
- Preferences (in hamburger menu top right if page is narrow)
- Development tab
- New Application
The bot needs permissions (I'm honestly not sure you need to give all of read, but
Mastodon.py's me() method seems to need a lot of them. idk.)
- read
- write:lists - the bot only streams your posts by making a list with just you on it
- write:statuses - to xpost, dummy!
Then copy the resulting access token for use in configuration...
from mastodon import Mastodon
client = Mastodon(
access_token=MASTO_TOKEN,
api_base_url=MASTO_URL
)
hacker voice: I'm in
Post!
Posting v easy.
post = client.status_post("my post")
And then to thread:
second_post = client.status_post(
"second post",
in_reply_to_id=post
)
Listen to a list of users
You can also listen to all the accounts that your profile follows, but usually on public instances you want to be respectful and have some sort of opt-in mechanism, and usually that means making a list of accounts that follow you.
Assuming you've already made a list named "my_list"... (see https://git.jon-e.net/jonny/masto-gitsocial-bridge/src/commit/6c65eaa30180dfa1a5995cead10d8ce3f9b2af49/masto_git_bridge/bot.py#L91-L95 for an example of making a list, in this case just with the ID of the bot on it, but you can also list accounts following the bot using account_followers())
Subclass the StreamListener and override its on_update method to handle new statuses. Then initialize it using the client we logged in with above
from mastodon import StreamListener
class Listener(StreamListener):
def on_update(self, status:dict):
# do something....
pass
# get our list
my_list = [l for l in client.lists() if l.get('title', '') == 'my_list'][0]
# start streaming our list, responding using on_update when there's a post
listener = Listener()
client.stream_list(
my_list['id'],
listener = listener
)
Discord
Excuse me let me be a good role model on continuous archiving. One of the reasons I am excited about academics adopting Mastodon is because ActivityPub is built on Linked Data, which i think inspires the possibility for fundamentally new modes of scholarly communication. I have written about this in the past (10.48550/arXiv.2209.07493, but will do my best to decenter my own ideas except for when I am using them as a demonstration for others as part of a demonstration of using the technology developed for the workshop