Available API Methods

Following is a list of all client to server API methods that have been implemented.

class minimal_activitypub.client_2_server.ActivityPub

Simplifies interacting with an ActivityPub server / instance.

This is a minimal implementation only implementing methods needed for the function of MastodonAmnesia

__init__(instance, client, access_token=None)

Initialise ActivityPub instance with reasonable default values.

Parameters:

  • instance (str) – domain name or url to instance to connect to

  • client (AsyncClient) – httpx AsyncClient to use for communicating with instance

  • access_token (str | None) – authentication token

  • self (ActivityPubClass)

Return type:

None

async static create_app(instance_url, client, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0', client_website='https://pypi.org/project/minimal-activitypub/')

Create an app.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • client (AsyncClient) – httpx.AsyncClient

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

  • client_website (str) – Link to site for user_agent. Defaults to link to minimal_activitypub on Pypi.org

Returns:

tuple(client_id, client_secret)

Return type:

Tuple[str, str]

async delete_status(status)

Delete a status.

Parameters:

  • status (str | Dict[Any, Any]) – The ID of the status you want to delete or a dict containing the status details

  • self (ActivityPubClass)

Returns:

Status that has just been deleted

Return type:

Dict[str, Any]

async determine_instance_type()

Check if the instance is a Pleroma instance or not.

Parameters:

self (ActivityPubClass)

Return type:

None

async static generate_authorization_url(instance_url, client_id, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0')

Create URL to get access token interactively from website.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • client_id (str) – Client id of app as generated by create_app method

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

Returns:

String containing URL to visit to get access token interactively from instance.

Return type:

str

async get_account_statuses(account_id, max_id=None, min_id=None)

Get statuses of a given account.

Parameters:

  • account_id (str) – The account ID of the account you want to get the statuses of

  • max_id (str | None) – The ID of the last status you want to get

  • min_id (str | None) – The ID of the oldest status you want to retrieve

  • self (ActivityPubClass)

Returns:

A list of statuses.

Return type:

List[Dict[str, Any]]

async static get_auth_token(instance_url, username, password, client, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0', client_website='https://pypi.org/project/minimal-activitypub/')

Create an app and use it to get an access token.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • username (str) – The username of the account you want to get an auth_token for

  • password (str) – The password of the account you want to get an auth_token for

  • client (AsyncClient) – httpx.AsyncClient

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

  • client_website (str) – Link to site for user_agent. Defaults to link to minimal_activitypub on Pypi.org

Returns:

The access token is being returned.

Return type:

str

async get_hashtag_timeline(hashtag, any_tags=None, all_tags=None, none_tags=None, local=False, remote=False, only_media=False, max_id=None, since_id=None, min_id=None, limit=20)

Get timeline of statuses with hashtags.

Parameters:

  • hashtag (str) – Hashtag excluding “#” to list statuses for

  • any_tags (list[str] | None) – Return statuses that also contain any of these additional tags.

  • all_tags (list[str] | None) – Return statuses that also contain all of these additional tags.

  • none_tags (list[str] | None) – Return statuses that contain none of these additional tags.

  • local (bool) – Return only local statuses? Defaults to False.

  • remote (bool) – Return only remote statuses? Defaults to False.

  • only_media (bool) – Return only statuses with media attachments? Defaults to False.

  • max_id (str | None) – All results returned will be lesser than this ID. In effect, sets an upper bound on results.

  • since_id (str | None) – All results returned will be greater than this ID. In effect, sets a lower bound on results.

  • min_id (str | None) – Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

  • limit (int) – Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category.

  • self (ActivityPubClass)

Return type:

List[Dict[str, Any]]

async get_home_timeline(max_id=None, since_id=None, min_id=None, limit=20)

Get statuses of the home timeline.

Parameters:

  • max_id (str | None) – All results returned will be lesser than this ID. In effect, sets an upper bound on results.

  • since_id (str | None) – All results returned will be greater than this ID. In effect, sets a lower bound on results.

  • min_id (str | None) – Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

  • limit (int) – Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

  • self (ActivityPubClass)

Returns:

A list of statuses.

Return type:

List[Dict[str, Any]]

async get_public_timeline(local=False, remote=False, only_media=False, max_id=None, since_id=None, min_id=None, limit=20)

Get statuses of the public timeline.

Parameters:

  • local (bool) – Show only local statuses? Defaults to False.

  • remote (bool) – Show only remote statuses? Defaults to False.

  • only_media (bool) – Show only statuses with media attached? Defaults to False.

  • max_id (str | None) – All results returned will be lesser than this ID. In effect, sets an upper bound on results.

  • since_id (str | None) – All results returned will be greater than this ID. In effect, sets a lower bound on results.

  • min_id (str | None) – Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

  • limit (int) – Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.

  • self (ActivityPubClass)

Returns:

A list of statuses.

Return type:

List[Dict[str, Any]]

async post_media(file, mime_type, description=None, focus=None)

Post a media file (image or video).

Parameters:

  • file (BinaryIO) – The file to be uploaded

  • mime_type (str) – Mime type

  • description (str | None) – A plain-text description of the media, for accessibility purposes

  • focus (Tuple[float, float] | None) – Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0 (see “Focal points <https://docs.joinmastodon.org/methods/statuses/media/#focal-points>”_)

  • self (ActivityPubClass)

Returns:

Dict containing details for this media on server, such a id, url etc

Return type:

Any

async post_status(status, visibility=Visibility.PUBLIC, media_ids=None, sensitive=False, spoiler_text=None)

Post a status to the fediverse.

Parameters:

  • status (str) – The text to be posted on the timeline.

  • visibility (Visibility) – Visibility of the posted status. Enumerable one of public, unlisted, private, or direct. Defaults to public

  • media_ids (List[str] | None) – List of ids for media (pictures, videos, etc) to be attached to this post. Can be None if no media is to be attached. Defaults to None

  • sensitive (bool) – Set to true the post is of a sensitive nature and should be marked as such. For example overly political or explicit material is often marked as sensitive. Applies particularly to attached media. Defaults to False

  • spoiler_text (str | None) – Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field. Defaults to None

  • self (ActivityPubClass)

Returns:

Dict of the status just posted.

Return type:

Dict[str, Any]

async reblog(status_id)

Reblog a status.

Parameters:

  • status_id (str) – The ID of the status you want to delete or a dict containing the status details

  • self (ActivityPubClass)

Returns:

The response from the server.

Return type:

Dict[str, Any]

async search(query, query_type, resolve=True, following=False, account_id=None, exclude_unreviewed=False, max_id=None, min_id=None, limit=None, offset=None)

Search for accounts, statuses and hashtags.

Parameters:

  • query (str) – The search query.

  • query_type (SearchType) – Specify whether to search for only accounts, hashtags, statuses. Use SearchType enum for this.

  • resolve (bool) – Only relevant if type includes accounts. If true and (a) the search query is for a remote account (e.g., someaccount@someother.server) and (b) the local server does not know about the account, WebFinger is used to try and resolve the account at some other.server. This provides the best recall at higher latency. If false only accounts the server knows about are returned. Defaults to True.

  • following (bool) – Only include accounts that the user is following? Defaults to False.

  • account_id (str | None) – If provided, will only return statuses authored by this account.

  • exclude_unreviewed (bool) – Filter out unreviewed tags? Defaults to False. Use True when trying to find trending tags.

  • max_id (str | None) – All results returned will be lesser than this ID. In effect, sets an upper bound on results.

  • min_id (str | None) – Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates

  • limit (int | None) – Maximum number of results to return, per type. Mastodon servers default this to 20 results per category. Max 40 results per category.

  • offset (int | None) – Skip the first n results.

  • self (ActivityPubClass)

Return type:

Any

async undo_favourite(status)

Remove a favourite.

Parameters:

  • status (str | Dict[Any, Any]) – The ID of the status you want to delete or a dict containing the status details

  • self (ActivityPubClass)

Returns:

The Status that has just been un-favourited.

Return type:

Dict[str, Any]

async undo_reblog(status)

Remove a reblog.

Parameters:

  • status (str | Dict[Any, Any]) – The ID of the status you want to delete or a dict containing the status details

  • self (ActivityPubClass)

Returns:

The response from the server.

Return type:

Dict[str, Any]

async static validate_authorization_code(client, instance_url, authorization_code, client_id, client_secret)

Validate an authorization code and get access token needed for API access.

Parameters:

  • client (AsyncClient) – httpx.AsyncClient

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • authorization_code (str) – authorization code

  • client_id (str) – client id as returned by create_app method

  • client_secret (str) – client secret as returned by create_app method

Returns:

access token

Return type:

str

async verify_credentials()

Verify the credentials of the user.

Returns:

The response is a JSON object containing the account’s information.

Parameters:

self (ActivityPubClass)

Return type:

Any