mastodon

Platypush documentation

`mastodon`#

Description#

Plugin to interact with Mastodon instances.

It requires an active API token associated to an app registered on the instance. In order to get one:

Open https://<mastodon-base-url>/settings/applications/

Create a new application

Select the scopes relevant for your specific usage.

Take note of the token reported on the Your access token row.

The notifications subscription service requires the ngrok plugin and the http backend to be enabled, since we need to expose an external URL that the Mastodon instance can call when new events occur.

Configuration#

mastodon:
  # [Required]
  # Base URL of the Mastodon web server, in the form of ``https://<domain-name>``.
  base_url:   # type=str

  # [Optional]
  # Access token as reported on ``https://<base_url>/settings/applications/<app_id>``.
  # access_token:   # type=Optional[str]

Actions#

mastodon.add_accounts_to_list

mastodon.add_favourite_status

mastodon.add_featured_tag

mastodon.block_account

mastodon.bookmark_status

mastodon.create_filter

mastodon.create_list

mastodon.delete_list

mastodon.dismiss_notifications

mastodon.follow_account

mastodon.get_account

mastodon.get_blocked_accounts

mastodon.get_bookmarked_statuses

mastodon.get_conversations

mastodon.get_favourited_statuses

mastodon.get_featured_lists

mastodon.get_featured_tags

mastodon.get_filters

mastodon.get_followers

mastodon.get_following

mastodon.get_hashtag_timeline

mastodon.get_home_timeline

mastodon.get_list_accounts

mastodon.get_list_timeline

mastodon.get_lists

mastodon.get_muted_accounts

mastodon.get_notifications

mastodon.get_public_timeline

mastodon.get_status

mastodon.get_statuses

mastodon.mark_conversation_as_read

mastodon.mute_account

mastodon.mute_status

mastodon.pin_account

mastodon.pin_status

mastodon.publish_status

mastodon.reblog_status

mastodon.register_account

mastodon.remove_accounts_from_list

mastodon.remove_conversation

mastodon.remove_favourite_status

mastodon.remove_featured_tag

mastodon.remove_filter

mastodon.remove_status

mastodon.search

mastodon.set_account_note

mastodon.unblock_account

mastodon.undo_bookmark_status

mastodon.undo_reblog_status

mastodon.unfollow_account

mastodon.unmute_account

mastodon.unmute_status

mastodon.unpin_account

mastodon.unpin_status

mastodon.update_account

mastodon.update_filter

mastodon.update_list

mastodon.update_media

mastodon.upload_media

Module reference#

class platypush.plugins.mastodon.MastodonPlugin(base_url: str, access_token: str | None = None, **kwargs)[source]#

Bases: Plugin

Plugin to interact with Mastodon instances.

It requires an active API token associated to an app registered on the instance. In order to get one:

Open https://<mastodon-base-url>/settings/applications/

Create a new application

Select the scopes relevant for your specific usage.

Take note of the token reported on the Your access token row.

__init__(base_url: str, access_token: str | None = None, **kwargs)[source]#

Parameters:

base_url – Base URL of the Mastodon web server, in the form of https://<domain-name>.
access_token – Access token as reported on https://<base_url>/settings/applications/<app_id>.

add_accounts_to_list(list_id: int, account_ids: Sequence[str], **kwargs)[source]#

Add accounts to a list.

It requires the specified API token to have the write:lists permission.

Parameters:

list_id – List ID.
account_ids – Accounts that should be added.
kwargs – base_url/access_token override.

Returns:

{
  "id": 25,
  "replies_policy": "string",
  "title": "strippedstring"
}

add_favourite_status(status_id: str, **kwargs)[source]#

Favourite a status.

It requires the specified API token to have the write:favourites permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

add_featured_tag(name: str, **kwargs) → dict[source]#

Add a featured tag to the current account.

It requires the specified API token to have the write:accounts permission.

Parameters:

name – Hashtag name.
kwargs – base_url/access_token override.

Returns:

{
  "id": 24,
  "last_status": "2020-01-01T00:00:00+00:00",
  "name": "string",
  "statuses_count": 55
}

block_account(account_id: str, **kwargs)[source]#

Block a given account ID.

It requires the specified API token to have the write:blocks permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

bookmark_status(status_id: str, **kwargs)[source]#

Add a status to the bookmarks.

It requires the specified API token to have the write:bookmarks permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

create_filter(phrase: str, context: Iterable[str], irreversible: bool | None = None, whole_word: bool | None = None, expires_in: int | None = None, **kwargs) → dict[source]#

Create a new filter.

It requires the specified API token to have the write:filters permission.

Parameters:

phrase – Text to be filtered.
context – Array of enumerable strings: home, notifications, public, thread. At least one context must be specified.
irreversible – Should the server irreversibly drop matching entities from home and notifications?
whole_word – Consider word boundaries?
expires_in – Expires in the specified number of seconds.
kwargs – base_url/access_token override.

Returns:

{
  "context": "Which context(s) this filter applies to. Possible values: home, notifications, public, thread",
  "expires_at": "2020-01-01T00:00:00+00:00",
  "id": 22,
  "irreversible": false,
  "phrase": "strippedstring",
  "whole_word": false
}

create_list(title: str, replies_policy: str = 'list', **kwargs) → dict[source]#

Create a new list.

It requires the specified API token to have the write:lists permission.

Parameters:

title – List title.
replies_policy – Possible values: none, following or list. Default: list.
kwargs – base_url/access_token override.

Returns:

{
  "id": 60,
  "replies_policy": "string",
  "title": "strippedstring"
}

delete_list(list_id: int, **kwargs)[source]#

Delete a list.

It requires the specified API token to have the write:lists permission.

Parameters:

list_id – List ID.
kwargs – base_url/access_token override.

dismiss_notifications(notification_id: str | None = None, **kwargs)[source]#

Dismiss notifications.

It requires the specified API token to have the write:notifications permission.

Parameters:

notification_id – Dismiss only this notification.
kwargs – base_url/access_token override.

follow_account(account_id: str, notify: bool = False, reblogs: bool = True, **kwargs)[source]#

Follow a given account ID.

It requires the specified API token to have the write:follows permission.

Parameters:

account_id – Account ID.
notify – Receive notifications when this account posts a new status (default: False).
reblogs – Receive this account’s reblogs on your timeline (default: True).
kwargs – base_url/access_token override.

get_account(account_id: str, **kwargs) → dict[source]#

Retrieve an account by ID.

It requires the specified API token to have read:accounts permissions.

Parameters:

account_id – Account ID to retrieve.
kwargs – base_url/access_token override.

Returns:

{
  "avatar": "https://example.org",
  "bot": true,
  "created_at": "2020-01-01T00:00:00+00:00",
  "discoverable": false,
  "display_name": "Name Surname",
  "followers_count": 94,
  "following_count": 86,
  "group": false,
  "header": "https://example.org",
  "id": "812419715237446415",
  "last_status_at": "2020-01-01T00:00:00+00:00",
  "locked": true,
  "note": "string",
  "url": "https://example.org",
  "username": "admin"
}

get_blocked_accounts(max_id: str | None = None, since_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Retrieve the list of blocked accounts.

It requires the specified API token to have the read:blocks permission.

Parameters:

max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "avatar": "https://example.org",
    "bot": true,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": true,
    "display_name": "Name Surname",
    "followers_count": 13,
    "following_count": 39,
    "group": true,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": false,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  }
]

get_bookmarked_statuses(min_id: str | None = None, max_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Retrieve the list of statuses bookmarked by the user.

It requires the specified API token to have the read:bookmarks permission.

Parameters:

min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": true,
      "display_name": "Name Surname",
      "followers_count": 22,
      "following_count": 15,
      "group": false,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": false,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": true,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": false,
    "favourites_count": 21,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 49,
            "day": "2020-01-01",
            "uses": 21
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": false,
    "pinned": true,
    "reblogged": false,
    "reblogs_count": 76,
    "replies_count": 47,
    "sensitive": false,
    "url": "https://example.org"
  }
]

get_conversations(min_id: str | None = None, max_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Get a list of user conversations.

It requires the specified API token to have the read:statuses permission.

Parameters:

min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "accounts": [
      {
        "avatar": "https://example.org",
        "bot": true,
        "created_at": "2020-01-01T00:00:00+00:00",
        "discoverable": true,
        "display_name": "Name Surname",
        "followers_count": 59,
        "following_count": 77,
        "group": false,
        "header": "https://example.org",
        "id": "812419715237446415",
        "last_status_at": "2020-01-01T00:00:00+00:00",
        "locked": false,
        "note": "string",
        "url": "https://example.org",
        "username": "admin"
      }
    ],
    "id": 84,
    "last_status": {
      "account": {
        "avatar": "https://example.org",
        "bot": true,
        "created_at": "2020-01-01T00:00:00+00:00",
        "discoverable": true,
        "display_name": "Name Surname",
        "followers_count": 7,
        "following_count": 66,
        "group": false,
        "header": "https://example.org",
        "id": "812419715237446415",
        "last_status_at": "2020-01-01T00:00:00+00:00",
        "locked": false,
        "note": "string",
        "url": "https://example.org",
        "username": "admin"
      },
      "attachments": [
        {
          "description": "strippedstring",
          "id": "string",
          "meta": {
            "key": "value"
          },
          "preview_remote_url": "https://example.org",
          "preview_url": "https://example.org",
          "remote_url": "https://example.org",
          "type": "image",
          "url": "https://example.org"
        }
      ],
      "bookmarked": true,
      "content": "string",
      "created_at": "2020-01-01T00:00:00+00:00",
      "favourited": true,
      "favourites_count": 49,
      "hashtags": [
        {
          "history": [
            {
              "accounts": 54,
              "day": "2020-01-01",
              "uses": 34
            }
          ],
          "name": "hashtag",
          "url": "https://example.org"
        }
      ],
      "id": "541635392513179495",
      "in_reply_to_account_id": "837526482893846314",
      "in_reply_to_id": "566427241989829486",
      "muted": true,
      "pinned": true,
      "reblogged": true,
      "reblogs_count": 53,
      "replies_count": 76,
      "sensitive": false,
      "url": "https://example.org"
    },
    "unread": true
  }
]

get_favourited_statuses(min_id: str | None = None, max_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Retrieve the list of statuses favourited by the account.

It requires the specified API token to have the read:favourites permission.

Parameters:

min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": false,
      "display_name": "Name Surname",
      "followers_count": 52,
      "following_count": 5,
      "group": true,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": false,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": false,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": false,
    "favourites_count": 71,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 21,
            "day": "2020-01-01",
            "uses": 82
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": false,
    "pinned": false,
    "reblogged": true,
    "reblogs_count": 96,
    "replies_count": 28,
    "sensitive": true,
    "url": "https://example.org"
  }
]

get_featured_lists(account_id: str, max_id: str | None = None, since_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Retrieve the list that you have added a certain account to.

It requires the specified API token to have the read:lists permission.

Parameters:

account_id – Account ID.
max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "id": 15,
    "title": "strippedstring"
  }
]

get_featured_tags(account_id: str | None = None, max_id: str | None = None, since_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Retrieve the list of featured hashtags of an account.

It requires the specified API token to have the read:accounts permission.

Parameters:

account_id – Account ID (if not specified then retrieve the featured tags of the current account).
max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "id": 29,
    "last_status": "2020-01-01T00:00:00+00:00",
    "name": "string",
    "statuses_count": 90
  }
]

get_filters(**kwargs) → Iterable[dict][source]#

Retrieve the list of filters created by the account.

It requires the specified API token to have the read:filters permission.

Parameters:

kwargs – base_url/access_token override.

Returns:

[
  {
    "context": "Which context(s) this filter applies to. Possible values: home, notifications, public, thread",
    "expires_at": "2020-01-01T00:00:00+00:00",
    "id": 34,
    "irreversible": false,
    "phrase": "strippedstring",
    "whole_word": false
  }
]

get_followers(account_id: str, max_id: str | None = None, since_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Retrieve the list of followers of an account.

It requires the specified API token to have the read:accounts permission.

Parameters:

account_id – Account ID.
max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "avatar": "https://example.org",
    "bot": false,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 34,
    "following_count": 20,
    "group": true,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": false,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  }
]

get_following(account_id: str, max_id: str | None = None, since_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Retrieve the list of accounts followed by a specified account.

It requires the specified API token to have the read:accounts permission.

Parameters:

account_id – Account ID.
max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "avatar": "https://example.org",
    "bot": false,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 55,
    "following_count": 10,
    "group": true,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": true,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  }
]

get_hashtag_timeline(hashtag: str, local: bool = False, only_media: bool = False, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Get a list of statuses associated to a hashtag.

It requires the specified API token to have the read:statuses permission.

Parameters:

hashtag – Hashtag to search.
local – Retrieve only local statuses (default: False).
only_media – Retrieve only statuses with media attached (default: False).
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": true,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": false,
      "display_name": "Name Surname",
      "followers_count": 23,
      "following_count": 21,
      "group": true,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": false,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": true,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": true,
    "favourites_count": 88,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 45,
            "day": "2020-01-01",
            "uses": 53
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": true,
    "pinned": true,
    "reblogged": true,
    "reblogs_count": 16,
    "replies_count": 1,
    "sensitive": true,
    "url": "https://example.org"
  }
]

get_home_timeline(local: bool = False, only_media: bool = False, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Get a list of statuses from the followed users.

It requires the specified API token to have the read:statuses permission.

Parameters:

local – Retrieve only local statuses (default: False).
only_media – Retrieve only statuses with media attached (default: False).
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": true,
      "display_name": "Name Surname",
      "followers_count": 73,
      "following_count": 51,
      "group": true,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": true,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": true,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": true,
    "favourites_count": 1,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 75,
            "day": "2020-01-01",
            "uses": 56
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": false,
    "pinned": true,
    "reblogged": false,
    "reblogs_count": 28,
    "replies_count": 87,
    "sensitive": true,
    "url": "https://example.org"
  }
]

get_list_accounts(list_id: int | None = None, min_id: str | None = None, max_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Get the accounts in a list.

It requires the specified API token to have the read:lists permission.

Parameters:

list_id – List ID.
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "avatar": "https://example.org",
    "bot": true,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 15,
    "following_count": 47,
    "group": false,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": true,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  }
]

get_list_timeline(list_id: str, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Get a list of statuses from a list timeline.

It requires the specified API token to have the read:lists permission.

Parameters:

list_id – List ID.
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": true,
      "display_name": "Name Surname",
      "followers_count": 34,
      "following_count": 41,
      "group": false,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": true,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": true,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": false,
    "favourites_count": 94,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 27,
            "day": "2020-01-01",
            "uses": 75
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": true,
    "pinned": false,
    "reblogged": false,
    "reblogs_count": 65,
    "replies_count": 95,
    "sensitive": true,
    "url": "https://example.org"
  }
]

get_lists(list_id: int | None = None, **kwargs) → dict | Iterable[dict][source]#

Get the lists owned by the logged user.

It requires the specified API token to have the read:lists permission.

Parameters:

list_id – Retrieve a specific list ID (default: retrieve all).
kwargs – base_url/access_token override.

Returns:

[
  {
    "id": 27,
    "replies_policy": "string",
    "title": "strippedstring"
  }
]

get_muted_accounts(max_id: str | None = None, since_id: str | None = None, limit: int = 20, **kwargs) → Iterable[dict][source]#

Retrieve the list of muted accounts.

It requires the specified API token to have the read:mutes permission.

Parameters:

max_id – Return results older than this ID.
since_id – Return results newer than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "avatar": "https://example.org",
    "bot": false,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 49,
    "following_count": 94,
    "group": false,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": false,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  }
]

get_notifications(notification_id: str | None = None, min_id: str | None = None, max_id: str | None = None, limit: int = 20, **kwargs) → dict | Iterable[dict][source]#

Get the list of notifications of the user.

It requires the specified API token to have the read:notifications permission.

Parameters:

notification_id – If specified then retrieve only the notification associated to this ID.
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": false,
      "display_name": "Name Surname",
      "followers_count": 57,
      "following_count": 42,
      "group": true,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": true,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "created_at": "2020-01-01T00:00:00+00:00",
    "id": "string",
    "mention": {
      "id": 1,
      "url": "https://mastodon.social/@user",
      "username": "user"
    },
    "status": {
      "account": {
        "avatar": "https://example.org",
        "bot": true,
        "created_at": "2020-01-01T00:00:00+00:00",
        "discoverable": false,
        "display_name": "Name Surname",
        "followers_count": 18,
        "following_count": 71,
        "group": true,
        "header": "https://example.org",
        "id": "812419715237446415",
        "last_status_at": "2020-01-01T00:00:00+00:00",
        "locked": true,
        "note": "string",
        "url": "https://example.org",
        "username": "admin"
      },
      "attachments": [
        {
          "description": "strippedstring",
          "id": "string",
          "meta": {
            "key": "value"
          },
          "preview_remote_url": "https://example.org",
          "preview_url": "https://example.org",
          "remote_url": "https://example.org",
          "type": "image",
          "url": "https://example.org"
        }
      ],
      "bookmarked": false,
      "content": "string",
      "created_at": "2020-01-01T00:00:00+00:00",
      "favourited": true,
      "favourites_count": 41,
      "hashtags": [
        {
          "history": [
            {
              "accounts": 17,
              "day": "2020-01-01",
              "uses": 94
            }
          ],
          "name": "hashtag",
          "url": "https://example.org"
        }
      ],
      "id": "541635392513179495",
      "in_reply_to_account_id": "837526482893846314",
      "in_reply_to_id": "566427241989829486",
      "muted": false,
      "pinned": true,
      "reblogged": true,
      "reblogs_count": 46,
      "replies_count": 48,
      "sensitive": false,
      "url": "https://example.org"
    },
    "type": "string"
  }
]

get_public_timeline(local: bool = False, remote: bool = False, only_media: bool = False, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Get a list of statuses from the public timeline.

It requires the specified API token to have the read:statuses permission.

Parameters:

local – Retrieve only local statuses (default: False).
remote – Retrieve only remote statuses (default: False).
only_media – Retrieve only statuses with media attached (default: False).
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": true,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": false,
      "display_name": "Name Surname",
      "followers_count": 9,
      "following_count": 80,
      "group": false,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": true,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": false,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": false,
    "favourites_count": 30,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 54,
            "day": "2020-01-01",
            "uses": 15
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": false,
    "pinned": false,
    "reblogged": false,
    "reblogs_count": 42,
    "replies_count": 71,
    "sensitive": false,
    "url": "https://example.org"
  }
]

get_status(status_id: str, **kwargs) → dict[source]#

Get a status by ID.

It requires the specified API token to have the read:statuses permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

Returns:

{
  "account": {
    "avatar": "https://example.org",
    "bot": false,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 99,
    "following_count": 71,
    "group": true,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": false,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  },
  "attachments": [
    {
      "description": "strippedstring",
      "id": "string",
      "meta": {
        "key": "value"
      },
      "preview_remote_url": "https://example.org",
      "preview_url": "https://example.org",
      "remote_url": "https://example.org",
      "type": "image",
      "url": "https://example.org"
    }
  ],
  "bookmarked": true,
  "content": "string",
  "created_at": "2020-01-01T00:00:00+00:00",
  "favourited": true,
  "favourites_count": 45,
  "hashtags": [
    {
      "history": [
        {
          "accounts": 38,
          "day": "2020-01-01",
          "uses": 15
        }
      ],
      "name": "hashtag",
      "url": "https://example.org"
    }
  ],
  "id": "541635392513179495",
  "in_reply_to_account_id": "837526482893846314",
  "in_reply_to_id": "566427241989829486",
  "muted": true,
  "pinned": false,
  "reblogged": false,
  "reblogs_count": 16,
  "replies_count": 90,
  "sensitive": true,
  "url": "https://example.org"
}

get_statuses(account_id: str, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, **kwargs) → Iterable[dict][source]#

Retrieve statuses by account ID.

It requires the specified API token to have the read:statuses permission.

Parameters:

account_id – Account ID.
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
kwargs – base_url/access_token override.

Returns:

[
  {
    "account": {
      "avatar": "https://example.org",
      "bot": true,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": true,
      "display_name": "Name Surname",
      "followers_count": 30,
      "following_count": 12,
      "group": false,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": true,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    },
    "attachments": [
      {
        "description": "strippedstring",
        "id": "string",
        "meta": {
          "key": "value"
        },
        "preview_remote_url": "https://example.org",
        "preview_url": "https://example.org",
        "remote_url": "https://example.org",
        "type": "image",
        "url": "https://example.org"
      }
    ],
    "bookmarked": false,
    "content": "string",
    "created_at": "2020-01-01T00:00:00+00:00",
    "favourited": false,
    "favourites_count": 96,
    "hashtags": [
      {
        "history": [
          {
            "accounts": 90,
            "day": "2020-01-01",
            "uses": 63
          }
        ],
        "name": "hashtag",
        "url": "https://example.org"
      }
    ],
    "id": "541635392513179495",
    "in_reply_to_account_id": "837526482893846314",
    "in_reply_to_id": "566427241989829486",
    "muted": true,
    "pinned": true,
    "reblogged": true,
    "reblogs_count": 15,
    "replies_count": 90,
    "sensitive": false,
    "url": "https://example.org"
  }
]

mark_conversation_as_read(conversation_id: int, **kwargs)[source]#

Mark a conversation as read.

It requires the specified API token to have the write_conversations permission.

Parameters:

conversation_id – Conversation ID.
kwargs – base_url/access_token override.

mute_account(account_id: str, **kwargs)[source]#

Mute a given account ID.

It requires the specified API token to have the write:mutes permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

mute_status(status_id: str, **kwargs)[source]#

Mute updates on a status.

It requires the specified API token to have the write:mutes permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

pin_account(account_id: str, **kwargs)[source]#

Pin a given account ID to your profile.

It requires the specified API token to have the write:accounts permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

pin_status(status_id: str, **kwargs)[source]#

Pin a status to the profile.

It requires the specified API token to have the write:accounts permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

Publish a new status.

It requires the specified API token to have the write:statuses permission.

Parameters:

status – Content of the status to publish.
in_reply_to_id – Post the status in reply to this status ID.
media_ids – Optional list of media IDs to add as attachments.
sensitive – Set to true if sensitive.
spoiler_text – Set for optional spoiler text.
visibility – Supported values: public, unlisted, private and direct.
kwargs – base_url/access_token override.

Returns:

{
  "account": {
    "avatar": "https://example.org",
    "bot": false,
    "created_at": "2020-01-01T00:00:00+00:00",
    "discoverable": false,
    "display_name": "Name Surname",
    "followers_count": 80,
    "following_count": 38,
    "group": true,
    "header": "https://example.org",
    "id": "812419715237446415",
    "last_status_at": "2020-01-01T00:00:00+00:00",
    "locked": true,
    "note": "string",
    "url": "https://example.org",
    "username": "admin"
  },
  "attachments": [
    {
      "description": "strippedstring",
      "id": "string",
      "meta": {
        "key": "value"
      },
      "preview_remote_url": "https://example.org",
      "preview_url": "https://example.org",
      "remote_url": "https://example.org",
      "type": "image",
      "url": "https://example.org"
    }
  ],
  "bookmarked": false,
  "content": "string",
  "created_at": "2020-01-01T00:00:00+00:00",
  "favourited": true,
  "favourites_count": 46,
  "hashtags": [
    {
      "history": [
        {
          "accounts": 5,
          "day": "2020-01-01",
          "uses": 37
        }
      ],
      "name": "hashtag",
      "url": "https://example.org"
    }
  ],
  "id": "541635392513179495",
  "in_reply_to_account_id": "837526482893846314",
  "in_reply_to_id": "566427241989829486",
  "muted": true,
  "pinned": false,
  "reblogged": false,
  "reblogs_count": 91,
  "replies_count": 47,
  "sensitive": true,
  "url": "https://example.org"
}

reblog_status(status_id: str, **kwargs)[source]#

Reblog (a.k.a. reshare/boost) a status.

It requires the specified API token to have the write:statuses permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

register_account(username: str, email: str, password: str, locale: str = 'en', reason: str | None = None, **kwargs) → dict[source]#

It requires the specified API token to have write:accounts permissions.

Parameters:

username – User name.
email – User’s email address (must be a valid address).
password – The password used for the first login.
locale – Language/encoding for the confirmation email.
reason – Text that will be reviewed by moderators if registrations require manual approval.
kwargs – base_url/access_token override.

Returns:

{
  "access_token": "string",
  "created_at": "2020-01-01T00:00:00+00:00",
  "scope": "read write follow push",
  "token_type": "Bearer"
}

remove_accounts_from_list(list_id: int, account_ids: Sequence[str], **kwargs)[source]#

Remove accounts from a list

It requires the specified API token to have the write:lists permission.

Parameters:

list_id – List ID.
account_ids – Accounts that should be removed.
kwargs – base_url/access_token override.

Returns:

{
  "id": 39,
  "replies_policy": "string",
  "title": "strippedstring"
}

remove_conversation(conversation_id: int, **kwargs)[source]#

Remove a conversation by ID.

It requires the specified API token to have the write_conversations permission.

Parameters:

conversation_id – Conversation ID.
kwargs – base_url/access_token override.

remove_favourite_status(status_id: str, **kwargs)[source]#

Undo a status favourite action.

It requires the specified API token to have the write:favourites permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

remove_featured_tag(tag_id: int, **kwargs)[source]#

Remove a featured tag from the current account.

It requires the specified API token to have the write:accounts permission.

Parameters:

tag_id – Hashtag ID.
kwargs – base_url/access_token override.

remove_filter(filter_id: int, **kwargs)[source]#

Remove a filter.

It requires the specified API token to have the write:filters permission.

Parameters:

filter_id – Filter ID.
kwargs – base_url/access_token override.

remove_status(status_id: str, **kwargs)[source]#

Remove a status by ID.

It requires the specified API token to have the read:statuses permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

search(query: str, type: str | None = None, min_id: str | None = None, max_id: str | None = None, limit: int = 20, offset: int = 0, following: bool = False, **kwargs) → Mapping[str, Iterable[dict]][source]#

Perform a search.

Parameters:

query – Search query.
type –
Filter by type. Supported types:
- accounts
- hashtags
- statuses
min_id – Return results newer than this ID.
max_id – Return results older than this ID.
limit – Maximum number of results (default: 20).
offset – Return results from this offset (default: 0).
following – Only return results from accounts followed by the user (default: False).
kwargs – base_url/access_token override.

Returns:

{
  "accounts": [
    {
      "avatar": "https://example.org",
      "bot": false,
      "created_at": "2020-01-01T00:00:00+00:00",
      "discoverable": true,
      "display_name": "Name Surname",
      "followers_count": 52,
      "following_count": 77,
      "group": true,
      "header": "https://example.org",
      "id": "812419715237446415",
      "last_status_at": "2020-01-01T00:00:00+00:00",
      "locked": false,
      "note": "string",
      "url": "https://example.org",
      "username": "admin"
    }
  ],
  "hashtags": [
    {
      "history": [
        {
          "accounts": 57,
          "day": "2020-01-01",
          "uses": 50
        }
      ],
      "name": "hashtag",
      "url": "https://example.org"
    }
  ],
  "statuses": [
    {
      "account": {
        "avatar": "https://example.org",
        "bot": true,
        "created_at": "2020-01-01T00:00:00+00:00",
        "discoverable": true,
        "display_name": "Name Surname",
        "followers_count": 71,
        "following_count": 14,
        "group": true,
        "header": "https://example.org",
        "id": "812419715237446415",
        "last_status_at": "2020-01-01T00:00:00+00:00",
        "locked": false,
        "note": "string",
        "url": "https://example.org",
        "username": "admin"
      },
      "attachments": [
        {
          "description": "strippedstring",
          "id": "string",
          "meta": {
            "key": "value"
          },
          "preview_remote_url": "https://example.org",
          "preview_url": "https://example.org",
          "remote_url": "https://example.org",
          "type": "image",
          "url": "https://example.org"
        }
      ],
      "bookmarked": true,
      "content": "string",
      "created_at": "2020-01-01T00:00:00+00:00",
      "favourited": true,
      "favourites_count": 42,
      "hashtags": [
        {
          "history": [
            {
              "accounts": 91,
              "day": "2020-01-01",
              "uses": 51
            }
          ],
          "name": "hashtag",
          "url": "https://example.org"
        }
      ],
      "id": "541635392513179495",
      "in_reply_to_account_id": "837526482893846314",
      "in_reply_to_id": "566427241989829486",
      "muted": false,
      "pinned": false,
      "reblogged": true,
      "reblogs_count": 76,
      "replies_count": 91,
      "sensitive": false,
      "url": "https://example.org"
    }
  ]
}

set_account_note(account_id: str, note: str, **kwargs)[source]#

Set a private note for an account.

It requires the specified API token to have the write:accounts permission.

Parameters:

account_id – Account ID.
note – Note content (HTML is supported).
kwargs – base_url/access_token override.

unblock_account(account_id: str, **kwargs)[source]#

Unblock a given account ID.

It requires the specified API token to have the write:blocks permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

undo_bookmark_status(status_id: str, **kwargs)[source]#

Remove a status from the bookmarks.

It requires the specified API token to have the write:bookmarks permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

undo_reblog_status(status_id: str, **kwargs)[source]#

Undo a status reblog.

It requires the specified API token to have the write:statuses permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

unfollow_account(account_id: str, **kwargs)[source]#

Unfollow a given account ID.

It requires the specified API token to have the write:follows permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

unmute_account(account_id: str, **kwargs)[source]#

Unmute a given account ID.

It requires the specified API token to have the write:mutes permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

unmute_status(status_id: str, **kwargs)[source]#

Restore updates on a status.

It requires the specified API token to have the write:mutes permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

unpin_account(account_id: str, **kwargs)[source]#

Unpin a given account ID from your profile.

It requires the specified API token to have the write:accounts permission.

Parameters:

account_id – Account ID.
kwargs – base_url/access_token override.

unpin_status(status_id: str, **kwargs)[source]#

Remove a pinned status.

It requires the specified API token to have the write:accounts permission.

Parameters:

status_id – Status ID.
kwargs – base_url/access_token override.

Updates the properties of the account associated to the access token.

It requires the specified API token to have write:accounts permissions.

Parameters:

discoverable – Whether the account should be shown in the profile directory.
bot – Whether the account is a bot.
display_name – The display name to use for the profile.
note – The account bio (HTML is supported).
avatar – Path to an avatar image.
header – Path to a header image.
locked – Whether manual approval of follow requests is required.
privacy – Default post privacy for authored statuses.
sensitive – Whether to mark authored statuses as sensitive by default.
language – Default language to use for authored statuses (ISO 6391 code).
metadata – Profile metadata items with name and value.
kwargs – base_url/access_token override.

Returns:

{
  "avatar": "https://example.org",
  "bot": false,
  "created_at": "2020-01-01T00:00:00+00:00",
  "discoverable": false,
  "display_name": "Name Surname",
  "followers_count": 42,
  "following_count": 67,
  "group": true,
  "header": "https://example.org",
  "id": "812419715237446415",
  "last_status_at": "2020-01-01T00:00:00+00:00",
  "locked": true,
  "note": "string",
  "url": "https://example.org",
  "username": "admin"
}

Update a filter.

It requires the specified API token to have the write:filters permission.

Parameters:

filter_id – Filter ID.
phrase – Text to be filtered.
context – Array of enumerable strings: home, notifications, public, thread. At least one context must be specified.
irreversible – Should the server irreversibly drop matching entities from home and notifications?
whole_word – Consider word boundaries?
expires_in – Expires in the specified number of seconds.
kwargs – base_url/access_token override.

Returns:

{
  "context": "Which context(s) this filter applies to. Possible values: home, notifications, public, thread",
  "expires_at": "2020-01-01T00:00:00+00:00",
  "id": 50,
  "irreversible": true,
  "phrase": "strippedstring",
  "whole_word": false
}

update_list(list_id: int, title: str | None, replies_policy: str | None = None, **kwargs) → dict[source]#

Update a list.

It requires the specified API token to have the write:lists permission.

Parameters:

list_id – List ID.
title – New list title.
replies_policy – New replies policy. Possible values: none, following or list. Default: list.
kwargs – base_url/access_token override.

Returns:

{
  "id": 54,
  "replies_policy": "string",
  "title": "strippedstring"
}

update_media(media_id: str, file: str | None = None, description: str | None = None, thumbnail: str | None = None, **kwargs) → dict[source]#

Update a media attachment.

It requires the specified API token to have the write:media permission.

Parameters:

media_id – Media ID to update.
file – Path to the new file.
description – New description.
thumbnail – Path to the new thumbnail.
kwargs – base_url/access_token override.

Returns:

{
  "description": "strippedstring",
  "id": "string",
  "meta": {
    "key": "value"
  },
  "preview_remote_url": "https://example.org",
  "preview_url": "https://example.org",
  "remote_url": "https://example.org",
  "type": "image",
  "url": "https://example.org"
}

upload_media(file: str, description: str | None = None, thumbnail: str | None = None, **kwargs) → dict[source]#

Upload media that can be used as attachments.

It requires the specified API token to have the write:media permission.

Parameters:

file – Path to the file to upload.
thumbnail – Path to the file thumbnail.
description – Optional attachment description.
kwargs – base_url/access_token override.

Returns:

{
  "description": "strippedstring",
  "id": "string",
  "meta": {
    "key": "value"
  },
  "preview_remote_url": "https://example.org",
  "preview_url": "https://example.org",
  "remote_url": "https://example.org",
  "type": "image",
  "url": "https://example.org"
}

mastodon

Platypush documentation

mastodon#

Description#

Configuration#

Actions#

Module reference#

`mastodon`#