API Methods Reference¶

All methods are async. Import APClient from the top-level package:

from longwei import APClient
import httpx

async with httpx.AsyncClient() as client:
    ap = await APClient.create(
        instance="mastodon.social",
        client=client,
        access_token="your_token",
    )

`APClient` constructor¶

`APClient(instance, client, access_token, timeout)`¶

Direct instantiation. Prefer APClient.create() for most use cases.

ap = APClient(
    instance="mastodon.social",
    client=client,
    access_token="your_token",   # optional
    timeout=120,                 # optional; defaults to 120 seconds
)

Parameter	Type	Description
`instance`	`str`	Domain or URL of the instance; trailing slash is stripped
`client`	`AsyncClient`	`httpx.AsyncClient` to use for requests
`access_token`	`str \\| None`	Bearer token; omit for public-only access
`timeout`	`int \\| None`	Request timeout in seconds; defaults to `120`

`APClient.create()` (async factory)¶

Recommended entry point. Calls determine_instance_type() automatically.

ap = await APClient.create(
    instance="mastodon.social",
    client=client,
    access_token="your_token",
    timeout=30,
)

Returns a fully initialised APClient instance.

Instance attributes¶

After creation the following attributes are available on the instance:

Attribute	Type	Default	Description
`instance`	`str`	—	Normalised instance URL (https:// prefix added if absent)
`instance_type`	`str`	`INSTANCE_TYPE_MASTODON`	Detected server type
`max_status_len`	`int`	`500`	Max characters per status
`max_attachments`	`int`	`4`	Max media attachments per status
`max_att_size`	`int`	`10000000`	Max attachment size in bytes
`supported_mime_types`	`list[str]`	`[]`	MIME types accepted for uploads
`ratelimit_limit`	`int`	`300`	Requests allowed per rate-limit window
`ratelimit_remaining`	`int`	`300`	Requests remaining in current window
`ratelimit_reset`	`datetime`	now	When the rate-limit window resets
`pagination`	`dict`	`{"next": {…}, "prev": {…}}`	Pagination cursors from last response

Credentials¶

`verify_credentials()`¶

Returns the authenticated account's profile.

account: Account = await ap.verify_credentials()
print(account.username)

Returns: Account

`determine_instance_type()`¶

Queries /api/v1/instance and sets instance_type, max_status_len, max_attachments, max_att_size, and supported_mime_types on the instance. Called automatically by APClient.create().

await ap.determine_instance_type()

Returns: None

Accounts¶

`get_account(account_id)`¶

Fetch a single account by ID.

account: Account = await ap.get_account("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID

Returns: Account

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ✅

`get_account_followers(account_id, ...)`¶

Return accounts that follow the given account.

followers: list[Account] = await ap.get_account_followers("12345", limit=40)

Parameter	Type	Description
`account_id`	`str`	The account ID
`max_id`	`str \\| None`	Return results older than this ID
`min_id`	`str \\| None`	Return results immediately newer than this ID
`limit`	`int \\| None`	Maximum number of results (server default: 40)

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ✅

`get_account_following(account_id, ...)`¶

Return accounts that the given account follows.

following: list[Account] = await ap.get_account_following("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID
`max_id`	`str \\| None`	Return results older than this ID
`min_id`	`str \\| None`	Return results immediately newer than this ID
`limit`	`int \\| None`	Maximum number of results

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ✅

`get_account_featured_tags(account_id)`¶

Return featured hashtags for the given account.

tags: list[FeaturedTag] = await ap.get_account_featured_tags("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID

Returns: list[FeaturedTag]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

`get_account_lists(account_id)`¶

Return user-defined lists that contain the given account. Requires authentication.

lists: list[UserList] = await ap.get_account_lists("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID

Returns: list[UserList]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

`follow_account(account_id, ...)`¶

Follow the given account. Requires authentication.

rel: Relationship = await ap.follow_account("12345", reblogs=True, notify=False)

Parameter	Type	Description
`account_id`	`str`	The account ID to follow
`reblogs`	`bool \\| None`	Show reblogs in home timeline (default: `True`)
`notify`	`bool \\| None`	Notify on new posts (default: `False`)
`languages`	`list[str] \\| None`	Filter to specific BCP 47 language codes

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ❌

`unfollow_account(account_id)`¶

Unfollow the given account. Requires authentication.

rel: Relationship = await ap.unfollow_account("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID to unfollow

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ❌

`unblock_account(account_id)`¶

Unblock the given account. Requires authentication.

rel: Relationship = await ap.unblock_account("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID to unblock

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`mute_account(account_id, ...)`¶

Mute the given account. Requires authentication.

rel: Relationship = await ap.mute_account("12345", notifications=True, duration=3600)

Parameter	Type	Description
`account_id`	`str`	The account ID to mute
`notifications`	`bool \\| None`	Also mute notifications (default: `True`)
`duration`	`int \\| None`	Mute duration in seconds; `0` means indefinite

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`unmute_account(account_id)`¶

Unmute the given account. Requires authentication.

rel: Relationship = await ap.unmute_account("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID to unmute

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`add_account_note(account_id, comment)`¶

Add or update a personal note about the given account (Mastodon 4.0+). Requires authentication.

rel: Relationship = await ap.add_account_note("12345", comment="colleague")

Parameter	Type	Description
`account_id`	`str`	The account ID
`comment`	`str`	The note text; pass `""` to clear

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

`get_relationships(ids)`¶

Return relationships between the authenticated user and the given accounts. Requires authentication.

rels: list[Relationship] = await ap.get_relationships(["1", "2", "3"])

Parameter	Type	Description
`ids`	`list[str]`	Account IDs to look up

Returns: list[Relationship]

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ❌

`get_familiar_followers(ids)`¶

Return accounts that follow both the authenticated user and each given account (Mastodon 3.5+). Requires authentication.

ff: list[FamiliarFollowers] = await ap.get_familiar_followers(["1", "2"])

Parameter	Type	Description
`ids`	`list[str]`	Target account IDs

Returns: list[FamiliarFollowers]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

`search_accounts(q, ...)`¶

Search for accounts matching a query string.

accounts: list[Account] = await ap.search_accounts("alice", limit=10, resolve=True)

Parameter	Type	Description
`q`	`str`	Search query (username, display name, or `user@domain`)
`limit`	`int \\| None`	Maximum results (server default: 40; max: 80)
`resolve`	`bool \\| None`	Attempt WebFinger resolution on unknown accounts
`following`	`bool \\| None`	Limit to accounts you already follow

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ❌

`lookup_account(acct)`¶

Look up an account by its user@domain address without a full search (Mastodon 3.3+, GotoSocial).

account: Account = await ap.lookup_account("alice@mastodon.social")

Parameter	Type	Description
`acct`	`str`	Account address, e.g. `"alice@mastodon.social"` or `"alice"` for local

Returns: Account

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`update_credentials(...)`¶

Update the authenticated user's profile. All parameters are optional. Requires authentication.

import io
account: Account = await ap.update_credentials(
    display_name="Alice",
    note="My bio",
    locked=False,
    avatar=open("avatar.jpg", "rb"),
    avatar_mime_type="image/jpeg",
)

Parameter	Type	Description
`display_name`	`str \\| None`	New display name
`note`	`str \\| None`	New bio / profile note
`locked`	`bool \\| None`	Require approval for new followers
`bot`	`bool \\| None`	Flag the account as a bot
`discoverable`	`bool \\| None`	List the account in the instance directory
`source_privacy`	`str \\| None`	Default post visibility (`"public"`, `"unlisted"`, `"private"`, `"direct"`)
`source_sensitive`	`bool \\| None`	Mark new posts sensitive by default
`source_language`	`str \\| None`	Default post language (BCP 47)
`avatar`	`IO[bytes] \\| None`	File-like object for new avatar image
`avatar_mime_type`	`str`	MIME type of avatar (default: `"image/jpeg"`)
`header`	`IO[bytes] \\| None`	File-like object for new header image
`header_mime_type`	`str`	MIME type of header (default: `"image/jpeg"`)

Returns: Account

Compatibility: Mastodon ✅ Pleroma ✅ GotoSocial ✅ snac ❌

Note: On Pleroma, some fields such as discoverable may be silently ignored.

`get_mutes(...)`¶

Return accounts muted by the authenticated user.

muted: list[Account] = await ap.get_mutes(limit=40)

Parameter	Type	Description
`max_id`	`str \\| None`	Return results older than this ID
`min_id`	`str \\| None`	Return results immediately newer than this ID
`limit`	`int \\| None`	Maximum number of results

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`get_blocks(...)`¶

Return accounts blocked by the authenticated user.

blocked: list[Account] = await ap.get_blocks(limit=40)

Parameter	Type	Description
`max_id`	`str \\| None`	Return results older than this ID
`min_id`	`str \\| None`	Return results immediately newer than this ID
`limit`	`int \\| None`	Maximum number of results

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`get_follow_requests(...)`¶

Return accounts with pending follow requests to the authenticated user.

requests: list[Account] = await ap.get_follow_requests()

Parameter	Type	Description
`max_id`	`str \\| None`	Return results older than this ID
`min_id`	`str \\| None`	Return results immediately newer than this ID
`limit`	`int \\| None`	Maximum number of results

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`authorize_follow_request(account_id)`¶

Accept a pending follow request from the given account. Requires authentication.

rel: Relationship = await ap.authorize_follow_request("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID whose follow request to accept

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`reject_follow_request(account_id)`¶

Reject a pending follow request from the given account. Requires authentication.

rel: Relationship = await ap.reject_follow_request("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID whose follow request to reject

Returns: Relationship

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ✅ snac ❌

`get_follow_suggestions(...)`¶

Return suggested accounts for the authenticated user to follow (Mastodon only).

suggestions: list[Account] = await ap.get_follow_suggestions(limit=10)

Parameter	Type	Description
`limit`	`int \\| None`	Maximum number of results

Returns: list[Account]

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

`delete_follow_suggestion(account_id)`¶

Remove an account from follow suggestions (Mastodon only). Requires authentication.

await ap.delete_follow_suggestion("12345")

Parameter	Type	Description
`account_id`	`str`	The account ID to remove from suggestions

Returns: None

Compatibility: Mastodon ✅ Pleroma ❌ GotoSocial ❌ snac ❌

Timelines¶

`get_public_timeline()`¶

statuses: list[Status] = await ap.get_public_timeline(
    local=False,
    remote=False,
    only_media=False,
    max_id=None,
    since_id=None,
    min_id=None,
    limit=20,
)

Parameter	Type	Default	Description
`local`	`bool`	`False`	Show only local statuses
`remote`	`bool`	`False`	Show only remote statuses
`only_media`	`bool`	`False`	Show only statuses with media attached
`max_id`	`str \\| None`	`None`	Return results older than this ID
`since_id`	`str \\| None`	`None`	Return results newer than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int`	`20`	Max results to return (server max: 40)

Returns: list[Status]

`get_home_timeline()`¶

statuses: list[Status] = await ap.get_home_timeline(
    max_id=None,
    since_id=None,
    min_id=None,
    limit=20,
)

Requires authentication. Returns statuses from accounts the authenticated user follows.

Returns: list[Status]

`get_hashtag_timeline()`¶

statuses: list[Status] = await ap.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,
)

Parameter	Type	Default	Description
`hashtag`	`str`	required	Hashtag to query, without the `#` prefix
`any_tags`	`list[str] \\| None`	`None`	Also include statuses with any of these additional tags
`all_tags`	`list[str] \\| None`	`None`	Also include statuses that contain all of these tags
`none_tags`	`list[str] \\| None`	`None`	Exclude statuses with any of these tags
`local`	`bool`	`False`	Only local statuses
`remote`	`bool`	`False`	Only remote statuses
`only_media`	`bool`	`False`	Only statuses with media
`max_id` / `since_id` / `min_id`	`str \\| None`	`None`	Pagination cursors
`limit`	`int`	`20`	Max results (server max: 40)

Returns: list[Status]

`get_account_statuses()`¶

statuses: list[Status] = await ap.get_account_statuses(
    account_id,
    max_id=None,
    min_id=None,
    since_id=None,
    limit=None,
    only_media=None,
    exclude_replies=None,
    exclude_reblogs=None,
    tagged=None,
)

Parameter	Type	Default	Description
`account_id`	`str`	required	ID of the account
`max_id`	`str \\| None`	`None`	Return statuses older than this ID
`min_id`	`str \\| None`	`None`	Return statuses immediately newer than this ID
`since_id`	`str \\| None`	`None`	Return statuses newer than this ID
`limit`	`int \\| None`	`None`	Maximum number of results (server default: 20, max: 40)
`only_media`	`bool \\| None`	`None`	Only return statuses with media attachments
`exclude_replies`	`bool \\| None`	`None`	Skip statuses that are replies
`exclude_reblogs`	`bool \\| None`	`None`	Skip statuses that are reblogs/boosts
`tagged`	`str \\| None`	`None`	Filter by hashtag (without the `#`)

Returns: list[Status]

`get_list_timeline()`¶

statuses: list[Status] = await ap.get_list_timeline(
    list_id,
    max_id=None,
    since_id=None,
    min_id=None,
    limit=20,
)

Requires authentication. Returns statuses from a user-defined list.

Parameter	Type	Default	Description
`list_id`	`str`	required	ID of the list
`max_id`	`str \\| None`	`None`	Return results older than this ID
`since_id`	`str \\| None`	`None`	Return results newer than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int`	`20`	Max results to return (server max: 40)

Returns: list[Status] — Mastodon only.

`get_link_timeline()`¶

statuses: list[Status] = await ap.get_link_timeline(
    url,
    max_id=None,
    since_id=None,
    min_id=None,
    limit=20,
)

Returns statuses that link to a specific URL.

Parameter	Type	Default	Description
`url`	`str`	required	The URL to fetch statuses for
`max_id`	`str \\| None`	`None`	Return results older than this ID
`since_id`	`str \\| None`	`None`	Return results newer than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int`	`20`	Max results to return (server max: 40)

Returns: list[Status] — Mastodon only.

`get_conversations()`¶

conversations: list[Conversation] = await ap.get_conversations(
    max_id=None,
    since_id=None,
    min_id=None,
    limit=20,
)

Requires authentication. Returns direct-message conversation threads.

Returns: list[Conversation] — Mastodon only.

`delete_conversation()`¶

await ap.delete_conversation(conversation_id)

Requires authentication. Deletes a conversation.

Parameter	Type	Description
`conversation_id`	`str`	ID of the conversation to delete

Returns: None — Mastodon only.

`read_conversation()`¶

conversation: Conversation = await ap.read_conversation(conversation_id)

Requires authentication. Marks a conversation as read.

Parameter	Type	Description
`conversation_id`	`str`	ID of the conversation to mark as read

Returns: Conversation — Mastodon only.

`get_markers()`¶

markers: dict[str, Marker] = await ap.get_markers(timelines=["home", "notifications"])

Requires authentication. Fetches saved timeline position markers.

Parameter	Type	Description
`timelines`	`list[str]`	Timeline names to fetch, e.g. `["home", "notifications"]`

Returns: dict[str, Marker] keyed by timeline name — Mastodon only.

`save_markers()`¶

markers: dict[str, Marker] = await ap.save_markers(
    home_last_read_id=None,
    notifications_last_read_id=None,
)

Requires authentication. Saves timeline position markers so you can resume where you left off.

Parameter	Type	Default	Description
`home_last_read_id`	`str \\| None`	`None`	ID of the last read status in the home timeline
`notifications_last_read_id`	`str \\| None`	`None`	ID of the last read notification

Returns: dict[str, Marker] keyed by timeline name — Mastodon only.

Favourites & Bookmarks¶

Requires authentication. Mastodon and GotoSocial only — Pleroma/Akkoma does not support these endpoints (use get_pleroma_account_favourites() for favourites on Pleroma).

`get_favourites()`¶

statuses: list[Status] = await ap.get_favourites(
    max_id=None,    # return results older than this ID
    min_id=None,    # return results immediately newer than this ID
    limit=None,     # max results (server default: 20, max: 40)
)

Parameter	Type	Default	Description
`max_id`	`str \\| None`	`None`	Return results older than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int \\| None`	`None`	Maximum number of results

Returns: list[Status]

`get_bookmarks()`¶

statuses: list[Status] = await ap.get_bookmarks(
    max_id=None,
    min_id=None,
    limit=None,
)

Parameter	Type	Default	Description
`max_id`	`str \\| None`	`None`	Return results older than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int \\| None`	`None`	Maximum number of results

Returns: list[Status]

Statuses¶

`post_status()`¶

status: Status = await ap.post_status(
    status,
    visibility=Visibility.PUBLIC,
    media_ids=None,
    sensitive=False,
    spoiler_text=None,
    scheduled_at=None,
    in_reply_to_id=None,
    language=None,
    poll_options=None,
    poll_expires_in=None,
    poll_multiple=False,
    poll_hide_totals=False,
)

Parameter	Type	Default	Description
`status`	`str`	required	Text content of the status
`visibility`	`Visibility`	`Visibility.PUBLIC`	Who can see the status
`media_ids`	`list[str] \\| None`	`None`	IDs from `post_media()` to attach
`sensitive`	`bool`	`False`	Mark the status as sensitive
`spoiler_text`	`str \\| None`	`None`	Content warning text
`scheduled_at`	`datetime \\| None`	`None`	Schedule for future posting (at least 5 min ahead); timezone defaults to UTC if naive
`in_reply_to_id`	`str \\| None`	`None`	ID of the status being replied to
`language`	`str \\| None`	`None`	ISO 639-1 language code (e.g. `"en"`)
`poll_options`	`list[str] \\| None`	`None`	Answer strings for an attached poll (at least 2); mutually exclusive with `media_ids`
`poll_expires_in`	`int \\| None`	`None`	Seconds until the poll closes; required when `poll_options` is set
`poll_multiple`	`bool`	`False`	Allow voters to select multiple options
`poll_hide_totals`	`bool`	`False`	Hide vote counts until the poll ends

Returns: Status

`delete_status()`¶

status: Status = await ap.delete_status(
    status,
    delete_only_one=False,
)

Parameter	Type	Default	Description
`status`	`str \\| Status`	required	Status ID or `Status` object
`delete_only_one`	`bool`	`False`	Set `True` to skip the random 0–3 s batch delay

When a Status object is passed on a Pleroma instance, undo_reblog() or undo_favourite() is called first if the status is reblogged or favourited.

Returns: Status (the deleted status)

`reblog()`¶

status: Status = await ap.reblog(status_id, visibility=None)

Parameter	Type	Default	Description
`status_id`	`str`	required	ID of the status to reblog
`visibility`	`Visibility \\| None`	`None`	Override reblog visibility: `public`, `unlisted`, or `private`. Omit to use the account default.

Returns: Status

`undo_reblog()`¶

status: Status = await ap.undo_reblog(status)

Parameter	Type	Description
`status`	`str \\| Status`	Status ID or `Status` object

Returns: Status

`undo_favourite()`¶

status: Status = await ap.undo_favourite(status)

Parameter	Type	Description
`status`	`str \\| Status`	Status ID or `Status` object

Returns: Status

`get_status()`¶

status: Status = await ap.get_status(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status to fetch

Returns: Status

`get_status_context()`¶

context: Context = await ap.get_status_context(status_id)

Returns the thread surrounding a status: statuses that appear before it (ancestors) and after it (descendants).

Parameter	Type	Description
`status_id`	`str`	ID of the status

Returns: Context

`get_reblogged_by()`¶

accounts: list[Account] = await ap.get_reblogged_by(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status

Returns: list[Account]

`get_favourited_by()`¶

accounts: list[Account] = await ap.get_favourited_by(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status

Returns: list[Account]

`favourite()`¶

status: Status = await ap.favourite(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status to favourite

Returns: Status

`bookmark()`¶

status: Status = await ap.bookmark(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status to bookmark

Returns: Status

`unbookmark()`¶

status: Status = await ap.unbookmark(status_id)

Parameter	Type	Description
`status_id`	`str`	ID of the status to remove from bookmarks

Returns: Status

`mute_status()`¶

status: Status = await ap.mute_status(status_id)

Mutes the conversation started by a status so you no longer receive notifications for it. Requires authentication.

Parameter	Type	Description
`status_id`	`str`	ID of the status whose conversation to mute

Returns: Status

`unmute_status()`¶

status: Status = await ap.unmute_status(status_id)

Unmutes the conversation started by a status. Requires authentication.

Parameter	Type	Description
`status_id`	`str`	ID of the status whose conversation to unmute

Returns: Status

`pin_status()`¶

status: Status = await ap.pin_status(status_id)

Pins a status to the authenticated account's profile. Requires authentication.

Parameter	Type	Description
`status_id`	`str`	ID of the status to pin

Returns: Status

`unpin_status()`¶

status: Status = await ap.unpin_status(status_id)

Unpins a status from the authenticated account's profile. Requires authentication.

Parameter	Type	Description
`status_id`	`str`	ID of the status to unpin

Returns: Status

`edit_status()`¶

status: Status = await ap.edit_status(
    status_id,
    status,
    *,
    media_ids=None,
    sensitive=None,
    spoiler_text=None,
    language=None,
)

Edits an existing status. Mastodon 3.5+.

Parameter	Type	Default	Description
`status_id`	`str`	required	ID of the status to edit
`status`	`str`	required	Updated text content
`media_ids`	`list[str] \\| None`	`None`	Updated list of attached media IDs
`sensitive`	`bool \\| None`	`None`	Updated sensitive flag
`spoiler_text`	`str \\| None`	`None`	Updated content warning text
`language`	`str \\| None`	`None`	ISO 639-1 language code

Returns: Status

`get_status_history()`¶

history: list[StatusEdit] = await ap.get_status_history(status_id)

Fetches the edit history of a status. Mastodon 3.5+.

Parameter	Type	Description
`status_id`	`str`	ID of the status

Returns: list[StatusEdit] (oldest first)

`get_status_source()`¶

source: StatusSource = await ap.get_status_source(status_id)

Fetches the unrendered plain-text source of a status, suitable for use in an edit form. Mastodon 3.5+.

Parameter	Type	Description
`status_id`	`str`	ID of the status

Returns: StatusSource

`translate_status()`¶

translation: Translation = await ap.translate_status(status_id, lang=None)

Requests a machine translation of a status. Mastodon 4.0+ only.

Parameter	Type	Default	Description
`status_id`	`str`	required	ID of the status to translate
`lang`	`str \\| None`	`None`	BCP 47 target language (e.g. `"fr"`); server chooses if omitted

Returns: Translation

Scheduled Statuses¶

Schedule a status for future posting with scheduled_at in post_status(). These methods manage already-scheduled statuses. Mastodon only — Pleroma/Akkoma and GotoSocial return 404 Not Found (raises NotFoundError) on all scheduled-status endpoints.

`get_scheduled_statuses()`¶

scheduled: list[ScheduledStatus] = await ap.get_scheduled_statuses()

Returns all scheduled statuses for the authenticated account.

Parameter	Type	Default	Description
`max_id`	`str \\| None`	`None`	Return results older than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int \\| None`	`None`	Maximum number of results (server default: 20)

Returns: list[ScheduledStatus]

Note: Implements GET /api/v1/scheduled_statuses (Mastodon). Requires authentication.

`get_scheduled_status()`¶

s: ScheduledStatus = await ap.get_scheduled_status(scheduled_status_id)

Returns a single scheduled status by ID.

Parameter	Type	Description
`scheduled_status_id`	`str`	The scheduled status ID

Returns: ScheduledStatus

Note: Implements GET /api/v1/scheduled_statuses/:id (Mastodon). Requires authentication.

`update_scheduled_status()`¶

s: ScheduledStatus = await ap.update_scheduled_status(
    scheduled_status_id, scheduled_at=datetime(2025, 12, 31, 10, 0, tzinfo=UTC)
)

Reschedules a scheduled status to a new time. The new time must be at least 5 minutes in the future. Naive datetimes are treated as UTC.

Parameter	Type	Description
`scheduled_status_id`	`str`	The scheduled status ID to update
`scheduled_at`	`datetime`	New datetime to post the status

Returns: ScheduledStatus

Note: Implements PUT /api/v1/scheduled_statuses/:id (Mastodon). Requires authentication.

`delete_scheduled_status(scheduled_status_id)`¶

await ap.delete_scheduled_status(scheduled_status_id)

Cancels a scheduled status before it is posted.

Parameter	Type	Description
`scheduled_status_id`	`str`	The scheduled status ID to cancel

Returns: None

Note: Implements DELETE /api/v1/scheduled_statuses/:id (Mastodon). Requires authentication.

Lists¶

User-defined lists for organising followed accounts. Mastodon only — Pleroma/Akkoma and GotoSocial return 404 Not Found (raises NotFoundError) on all list endpoints. See the Lists guide for full examples.

`get_lists()`¶

lists: list[UserList] = await ap.get_lists()

Returns all lists owned by the authenticated account.

Returns: list[UserList]

`create_list()`¶

lst: UserList = await ap.create_list(
    title,              # required: human-readable list title
    replies_policy=None,  # "followed", "list", or "none"
    exclusive=None,     # True: hide members from home timeline (Mastodon 4.2+)
)

Parameter	Type	Default	Description
`title`	`str`	—	Human-readable title for the list
`replies_policy`	`str \\| None`	`None`	Which replies to show: `"followed"`, `"list"`, or `"none"`
`exclusive`	`bool \\| None`	`None`	If `True`, members are excluded from the home timeline (Mastodon 4.2+)

Returns: UserList

`get_list()`¶

lst: UserList = await ap.get_list(list_id)

Parameter	Type	Description
`list_id`	`str`	The list ID

Returns: UserList

`update_list()`¶

lst: UserList = await ap.update_list(
    list_id,
    title,
    replies_policy=None,
    exclusive=None,
)

Same parameters as create_list() plus list_id. Returns: UserList

`delete_list()`¶

await ap.delete_list(list_id)

Parameter	Type	Description
`list_id`	`str`	The list ID to delete

Returns: None

`get_list_accounts()`¶

accounts: list[Account] = await ap.get_list_accounts(
    list_id,
    max_id=None,
    min_id=None,
    since_id=None,
    limit=None,
)

Parameter	Type	Default	Description
`list_id`	`str`	—	The list ID
`max_id`	`str \\| None`	`None`	Return results older than this ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`since_id`	`str \\| None`	`None`	Return results newer than this ID
`limit`	`int \\| None`	`None`	Maximum number of results (server default: 40)

Returns: list[Account]

`add_list_accounts()`¶

await ap.add_list_accounts(list_id, account_ids=["1", "2"])

Adds accounts to the list. The accounts must already be followed by the authenticated user.

Parameter	Type	Description
`list_id`	`str`	The list ID
`account_ids`	`list[str]`	IDs of accounts to add

Returns: None

`delete_list_accounts()`¶

await ap.delete_list_accounts(list_id, account_ids=["1", "2"])

Parameter	Type	Description
`list_id`	`str`	The list ID
`account_ids`	`list[str]`	IDs of accounts to remove

Returns: None

Media¶

`post_media()`¶

Upload a media file. Returns a MediaAttachment (use the id field as an entry in media_ids when calling post_status()).

Attempts POST /api/v2/media first; falls back to POST /api/v1/media on 404. If the server responds with HTTP 202 (still processing), polls until the attachment is ready before returning — the call always resolves with a fully-processed attachment.

result = await ap.post_media(
    file,
    mime_type,
    description=None,
    focus=None,
)
media_id = result.id

Parameter	Type	Default	Description
`file`	`IO[bytes]`	required	File-like object opened in binary mode
`mime_type`	`str`	required	MIME type, e.g. `"image/jpeg"`
`description`	`str \\| None`	`None`	Alt-text for accessibility
`focus`	`tuple[float, float] \\| None`	`None`	Focal point `(x, y)` in range `[-1.0, 1.0]`

Returns: MediaAttachment

Search¶

`search()`¶

results = await ap.search(
    query,
    query_type,
    resolve=True,
    following=False,
    account_id=None,
    exclude_unreviewed=False,
    max_id=None,
    min_id=None,
    limit=None,
    offset=None,
)

Parameter	Type	Default	Description
`query`	`str`	required	Search query string
`query_type`	`SearchType`	required	Constrain results to accounts, hashtags, or statuses
`resolve`	`bool`	`True`	Use WebFinger to resolve unknown remote accounts
`following`	`bool`	`False`	Only include accounts the user follows
`account_id`	`str \\| None`	`None`	Restrict status search to this account
`exclude_unreviewed`	`bool`	`False`	Filter unreviewed tags (useful for trending)
`max_id`	`str \\| None`	`None`	Results older than this ID
`min_id`	`str \\| None`	`None`	Results newer than this ID
`limit`	`int \\| None`	`None`	Max results per category (server default: 20, max: 40)
`offset`	`int \\| None`	`None`	Skip the first N results

Returns: SearchResults with .accounts, .statuses, and .hashtags lists

On Pleroma/Akkoma instances routes directly to GET /api/v2/pleroma/search — all parameters are preserved (no lossy drop). On Mastodon and GotoSocial attempts GET /api/v2/search first; falls back to GET /api/v1/search on 404. On v1 fallback only query, query_type, resolve, and limit are forwarded — the remaining parameters are silently dropped as they are not part of the v1 spec.

Polls¶

`get_poll(poll_id)`¶

poll: Poll = await ap.get_poll("34830")

Parameter	Type	Description
`poll_id`	`str`	The poll ID

Returns the poll with current vote counts and state.

Returns: Poll

Note: Implements GET /api/v1/polls/:id (Mastodon, Pleroma, GotoSocial).

`vote_poll(poll_id, choices)`¶

poll: Poll = await ap.vote_poll("34830", choices=[0])
# multi-choice poll
poll: Poll = await ap.vote_poll("34830", choices=[0, 2])

Parameter	Type	Description
`poll_id`	`str`	The poll ID
`choices`	`list[int]`	0-based indices of the options to vote for

Casts votes on a poll and returns the updated poll. For single-choice polls supply exactly one index; for multi-choice polls supply one or more.

Returns: Poll

Note: Implements POST /api/v1/polls/:id/votes (Mastodon, Pleroma, GotoSocial).

GotoSocial remote polls

GotoSocial does not support voting on polls hosted on remote instances. Attempting to do so will raise an UnprocessedError (HTTP 422).

Discovery¶

`get_trending_statuses()`¶

statuses: list[Status] = await ap.get_trending_statuses(
    limit=None,
    offset=None,
)

Parameter	Type	Default	Description
`limit`	`int \\| None`	`None`	Max results to return (server default: 20, max: 40)
`offset`	`int \\| None`	`None`	Skip the first N results

Returns: list[Status]

Mastodon only.

`get_trending_accounts()`¶

accounts: list[Account] = await ap.get_trending_accounts(
    limit=None,
    offset=None,
)

Parameter	Type	Default	Description
`limit`	`int \\| None`	`None`	Max results to return
`offset`	`int \\| None`	`None`	Skip the first N results

Returns: list[Account]

Mastodon only.

`get_trending_links()`¶

links: list[Card] = await ap.get_trending_links(
    limit=None,
    offset=None,
)

Parameter	Type	Default	Description
`limit`	`int \\| None`	`None`	Max results to return
`offset`	`int \\| None`	`None`	Skip the first N results

Returns: list[Card]

Mastodon only.

`get_directory()`¶

accounts: list[Account] = await ap.get_directory(
    limit=None,
    offset=None,
    order=None,
    local=None,
)

Parameter	Type	Default	Description
`limit`	`int \\| None`	`None`	Max results to return (server default: 40, max: 80)
`offset`	`int \\| None`	`None`	Skip the first N results
`order`	`str \\| None`	`None`	Sort order: `"active"` (recently posted, default) or `"new"` (recently joined)
`local`	`bool \\| None`	`None`	Limit to accounts on this instance only

Returns: list[Account]

Mastodon only.

`get_custom_emojis()`¶

emojis: list[Emoji] = await ap.get_custom_emojis()

Returns the full list of custom emoji available on the instance.

Returns: list[Emoji]

Instance & Announcements¶

`get_instance_peers()`¶

peers: list[str] = await ap.get_instance_peers()

Returns a list of domain names that this instance is aware of (its known peers).

Server support: Mastodon ✅ · Pleroma ⚠️ (returns [] by default) · GotoSocial ⚠️ (requires instance-expose-peers: true in server config; raises NotFoundError if not set)

Returns: list[str]

`get_instance_activity()`¶

activity: list[Activity] = await ap.get_instance_activity()

Returns weekly activity statistics for the instance. Each entry covers one calendar week with counts for new statuses and user logins. Mastodon returns approximately the last 3 months of data. All numeric fields are returned as strings in the JSON response.

Server support: Mastodon ✅ · Pleroma ❌ · GotoSocial ❌ (raises NotFoundError)

Returns: list[Activity]

`get_instance_rules()`¶

rules: list[Rule] = await ap.get_instance_rules()

Returns the list of rules set by the instance administrator.

Server support: Mastodon ✅ · Pleroma ⚠️ (may return [] if no rules configured) · GotoSocial ✅

Returns: list[Rule]

`get_instance_domain_blocks()`¶

blocks: list[DomainBlock] = await ap.get_instance_domain_blocks()

Returns the list of domains blocked by this instance. Unauthenticated requests may receive an obfuscated view where domain names are partially obscured.

Server support: Mastodon ✅ · Pleroma ⚠️ (depends on server config) · GotoSocial ⚠️ (requires instance-expose-blocklist: true; raises NotFoundError if not set)

Returns: list[DomainBlock]

`get_announcements()`¶

announcements: list[Announcement] = await ap.get_announcements()

Returns all active announcements published by the instance admin. Requires authentication. Includes each announcement's read state for the authenticated user and the current emoji reactions.

Server support: Mastodon ✅ · Pleroma ❌ · GotoSocial ❌ (raises NotFoundError)

Returns: list[Announcement]

`dismiss_announcement(announcement_id)`¶

await ap.dismiss_announcement("1")

Marks an announcement as read for the authenticated user. Requires authentication.

Parameter	Type	Description
`announcement_id`	`str`	The ID of the announcement to dismiss

Server support: Mastodon ✅ · Pleroma ❌ · GotoSocial ❌ (raises NotFoundError)

Returns: None

`add_announcement_reaction(announcement_id, name)`¶

await ap.add_announcement_reaction("1", "👍")
await ap.add_announcement_reaction("1", "blobcat")  # custom emoji shortcode

Adds an emoji reaction to an announcement. Requires authentication. The name value is URL-encoded before inclusion in the request path.

Parameter	Type	Description
`announcement_id`	`str`	The ID of the announcement
`name`	`str`	Unicode emoji character or custom emoji shortcode

Server support: Mastodon ✅ · Pleroma ❌ · GotoSocial ❌ (raises NotFoundError)

Returns: None

`remove_announcement_reaction(announcement_id, name)`¶

await ap.remove_announcement_reaction("1", "👍")

Removes an emoji reaction from an announcement. Requires authentication. The name value is URL-encoded before inclusion in the request path.

Parameter	Type	Description
`announcement_id`	`str`	The ID of the announcement
`name`	`str`	Unicode emoji character or custom emoji shortcode

Server support: Mastodon ✅ · Pleroma ❌ · GotoSocial ❌ (raises NotFoundError)

Returns: None

Reports¶

`get_reports()`¶

reports: list[Report] = await ap.get_reports()

Returns reports filed by the authenticated account.

Returns: list[Report]

Note: Implements GET /api/v1/reports (GotoSocial). Requires authentication.

`create_report(account_id, ...)`¶

report: Report = await ap.create_report(
    account_id="12345",
    status_ids=["109876543210"],
    comment="Repeated spam posts",
    forward=True,
    category="spam",
)

Files a report against an account.

Parameter	Type	Default	Description
`account_id`	`str`	required	ID of the account to report
`status_ids`	`list[str] \\| None`	`None`	Status IDs to attach as evidence
`comment`	`str \\| None`	`None`	Reason for the report (≤1000 characters on Mastodon)
`forward`	`bool \\| None`	`None`	Forward the report to the originating instance (remote accounts only)
`category`	`str \\| None`	`None`	`"spam"`, `"violation"`, or `"other"` (Mastodon default when omitted: `"other"`)
`rule_ids`	`list[str] \\| None`	`None`	IDs of rules violated; required by Mastodon when `category="violation"`

Returns: Report

Note: Implements POST /api/v1/reports (Mastodon, GotoSocial). Also accepted by Pleroma/Akkoma, but category and rule_ids are silently ignored there. Requires authentication.

Notifications¶

`get_notifications()`¶

notifications: list[Notification] = await ap.get_notifications(
    max_id=None,
    since_id=None,
    min_id=None,
    limit=None,
    types=None,
    exclude_types=None,
    account_id=None,
)

Returns notifications for the authenticated user. Requires authentication.

Parameter	Type	Default	Description
`max_id`	`str \\| None`	`None`	Return results older than this notification ID
`since_id`	`str \\| None`	`None`	Return results newer than this notification ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int \\| None`	`None`	Maximum results (server default 20, max 30)
`types`	`list[str] \\| None`	`None`	Only return these notification types (e.g. `["mention", "follow"]`)
`exclude_types`	`list[str] \\| None`	`None`	Exclude these notification types
`account_id`	`str \\| None`	`None`	Only return notifications from this account ID

Returns: list[Notification]

Note: Implements GET /api/v1/notifications (Mastodon, Pleroma/Akkoma, GotoSocial). Pleroma/Akkoma also emits pleroma:emoji_reaction, pleroma:chat_mention, and pleroma:report notification types in addition to the standard Mastodon set.

`get_notification(notification_id)`¶

notification: Notification = await ap.get_notification("123")

Returns a single notification by ID.

Parameter	Type	Description
`notification_id`	`str`	The notification ID

Returns: Notification

Note: Implements GET /api/v1/notifications/:id (Mastodon, Pleroma/Akkoma, GotoSocial).

`clear_notifications()`¶

await ap.clear_notifications()

Dismisses all notifications for the authenticated user.

Returns: None

Note: Implements POST /api/v1/notifications/clear (Mastodon, Pleroma/Akkoma, GotoSocial).

`dismiss_notification(notification_id)`¶

await ap.dismiss_notification("123")

Dismisses a single notification by ID.

Parameter	Type	Description
`notification_id`	`str`	The notification ID to dismiss

Returns: None

Note: Implements POST /api/v1/notifications/:id/dismiss (Mastodon, Pleroma/Akkoma, GotoSocial).

`get_notifications_v2()`¶

result: GroupedNotificationsResults = await ap.get_notifications_v2(
    max_id=None,
    since_id=None,
    min_id=None,
    limit=None,
    types=None,
    exclude_types=None,
    account_id=None,
    grouped_types=None,
)

Returns grouped notifications (Mastodon 4.3+ only). Unlike get_notifications(), which returns a flat list[Notification], this endpoint returns a GroupedNotificationsResults envelope containing notification_groups, accounts, and statuses.

Parameter	Type	Default	Description
`max_id`	`str \\| None`	`None`	Return results older than this notification ID
`since_id`	`str \\| None`	`None`	Return results newer than this notification ID
`min_id`	`str \\| None`	`None`	Return results immediately newer than this ID
`limit`	`int \\| None`	`None`	Maximum results
`types`	`list[str] \\| None`	`None`	Only return these notification types
`exclude_types`	`list[str] \\| None`	`None`	Exclude these notification types
`account_id`	`str \\| None`	`None`	Only return notifications from this account ID
`grouped_types`	`list[str] \\| None`	`None`	Which types to group; unlisted types appear ungrouped

Returns: GroupedNotificationsResults

Note: Implements GET /api/v2/notifications (Mastodon 4.3+ only). Pleroma/Akkoma and GotoSocial return 404, raising NotFoundError.

`get_notification_group_accounts(group_key)`¶

accounts: list[Account] = await ap.get_notification_group_accounts("mention.abc123")

Returns the accounts that triggered notifications in a given group (Mastodon 4.3+ only).

Parameter	Type	Description
`group_key`	`str`	The opaque group key from a `NotificationGroup`

Returns: list[Account]

Note: Implements GET /api/v2/notifications/:group_key/accounts (Mastodon 4.3+ only). Pleroma/Akkoma and GotoSocial return 404, raising NotFoundError.

Filters (v2)¶

Mastodon v2 filters group keywords and/or pinned statuses under a named rule with a configurable action (warn or hide). Mastodon only — Pleroma/Akkoma and GotoSocial return 404 Not Found (raises NotFoundError). For GotoSocial use the v1 filter methods instead.

`get_filters_v2()`¶

filters: list[FilterV2] = await ap.get_filters_v2()

Returns all v2 filters for the authenticated account.

Returns: list[FilterV2]

Note: Implements GET /api/v2/filters (Mastodon). Requires authentication.

`create_filter_v2(title, context, ...)`¶

f: FilterV2 = await ap.create_filter_v2(
    title="No spoilers",
    context=["home", "notifications"],
    filter_action="warn",
    expires_in=86400,
)

Creates a new v2 filter.

Parameter	Type	Default	Description
`title`	`str`	required	User-defined name for the filter
`context`	`list[str]`	required	Contexts where the filter applies: `"home"`, `"notifications"`, `"public"`, `"thread"`, `"account"`
`filter_action`	`str`	`"warn"`	`"warn"` (collapse with warning) or `"hide"` (drop matching content)
`expires_in`	`int \\| None`	`None`	Seconds until the filter expires; `None` = no expiry
`keywords_attributes`	`list[dict] \\| None`	`None`	Keyword dicts to add inline; each may contain `"keyword"` (str) and `"whole_word"` (bool)

Returns: FilterV2

Note: Implements POST /api/v2/filters (Mastodon). Requires authentication.

`get_filter_v2(filter_id)`¶

f: FilterV2 = await ap.get_filter_v2("123")

Returns a single v2 filter by ID.

Parameter	Type	Description
`filter_id`	`str`	The filter ID

Returns: FilterV2

Note: Implements GET /api/v2/filters/:id (Mastodon). Requires authentication.

`update_filter_v2(filter_id, ...)`¶

f: FilterV2 = await ap.update_filter_v2("123", title="Updated name", filter_action="hide")

Updates an existing v2 filter. Only parameters provided (not None) are sent.

Parameter	Type	Default	Description
`filter_id`	`str`	required	The filter ID to update
`title`	`str \\| None`	`None`	New user-defined name
`context`	`list[str] \\| None`	`None`	New list of contexts
`filter_action`	`str \\| None`	`None`	New action: `"warn"` or `"hide"`
`expires_in`	`int \\| None`	`None`	New expiry in seconds from now
`keywords_attributes`	`list[dict] \\| None`	`None`	Keyword dicts to update; each may include `"keyword"`, `"whole_word"`, and optionally `"id"`

Returns: FilterV2

Note: Implements PUT /api/v2/filters/:id (Mastodon). Requires authentication.

`delete_filter_v2(filter_id)`¶

await ap.delete_filter_v2("123")

Deletes a v2 filter.

Parameter	Type	Description
`filter_id`	`str`	The filter ID to delete

Returns: None

Note: Implements DELETE /api/v2/filters/:id (Mastodon). Requires authentication.

`get_filter_keywords()`¶

keywords: list[FilterKeyword] = await ap.get_filter_keywords("123")

Returns all keywords attached to a v2 filter.

Parameter	Type	Description
`filter_id`	`str`	The filter ID

Returns: list[FilterKeyword]

Note: Implements GET /api/v2/filters/:id/keywords (Mastodon). Requires authentication.

`add_filter_keyword(filter_id, keyword, ...)`¶

kw: FilterKeyword = await ap.add_filter_keyword("123", keyword="badword", whole_word=True)

Adds a keyword to an existing v2 filter.

Parameter	Type	Default	Description
`filter_id`	`str`	required	The filter ID to add the keyword to
`keyword`	`str`	required	The keyword or phrase to filter
`whole_word`	`bool`	`False`	Match whole words only

Returns: FilterKeyword

Note: Implements POST /api/v2/filters/:id/keywords (Mastodon). Requires authentication.

`get_filter_statuses()`¶

statuses: list[FilterStatus] = await ap.get_filter_statuses("123")

Returns all statuses attached to a v2 filter.

Parameter	Type	Description
`filter_id`	`str`	The filter ID

Returns: list[FilterStatus]

Note: Implements GET /api/v2/filters/:id/statuses (Mastodon). Requires authentication.

`add_filter_status(filter_id, status_id)`¶

fs: FilterStatus = await ap.add_filter_status("123", status_id="456")

Adds a specific status to a v2 filter.

Parameter	Type	Description
`filter_id`	`str`	The filter ID to add the status to
`status_id`	`str`	The ID of the status to filter

Returns: FilterStatus

Note: Implements POST /api/v2/filters/:id/statuses (Mastodon). Requires authentication.

GotoSocial¶

Methods specific to GotoSocial. These endpoints are not available on Mastodon or Pleroma unless noted otherwise.

Accounts¶

`get_account_moved_to(account_id)`¶

target: Account | None = await ap.get_account_moved_to("123456")

Returns the account that account_id has migrated to, or None if no migration exists.

Parameter	Type	Description
`account_id`	`str`	The account ID

Returns: Account | None

Note: Implements GET /api/v1/accounts/:id/moved_to (GotoSocial).

`get_account_aliases(account_id)`¶

aliases: list[str] = await ap.get_account_aliases("123456")

Returns a list of alias URIs configured on the account (used in ActivityPub account migration).

Parameter	Type	Description
`account_id`	`str`	The account ID

Returns: list[str]

Note: Implements GET /api/v1/accounts/:id/aliases (GotoSocial).

`block_account(account_id)`¶

rel: Relationship = await ap.block_account("123456")

Blocks an account. Also supported on Mastodon.

Parameter	Type	Description
`account_id`	`str`	The ID of the account to block

Returns: Relationship

Note: Implements POST /api/v1/accounts/:id/block (Mastodon, GotoSocial).

Profile¶

`get_profile_avatar()`¶

avatar: MediaAttachment = await ap.get_profile_avatar()

Returns the authenticated user's current avatar as a MediaAttachment.

Returns: MediaAttachment

Note: Implements GET /api/v1/profile/avatar (GotoSocial). Requires authentication.

`delete_profile_avatar()`¶

account: Account = await ap.delete_profile_avatar()

Deletes the authenticated user's avatar and returns the updated account.

Returns: Account

Note: Implements DELETE /api/v1/profile/avatar (GotoSocial). Requires authentication.

`get_profile_header()`¶

header: MediaAttachment = await ap.get_profile_header()

Returns the authenticated user's current header image as a MediaAttachment.

Returns: MediaAttachment

Note: Implements GET /api/v1/profile/header (GotoSocial). Requires authentication.

`delete_profile_header()`¶

account: Account = await ap.delete_profile_header()

Deletes the authenticated user's header image and returns the updated account.

Returns: Account

Note: Implements DELETE /api/v1/profile/header (GotoSocial). Requires authentication.

Filters (v1)¶

GotoSocial uses v1 filters only.

`get_filters()`¶

filters: list[Filter] = await ap.get_filters()

Returns all keyword filters for the authenticated account.

Returns: list[Filter]

Note: Implements GET /api/v1/filters (GotoSocial). Requires authentication.

`create_filter(phrase, context, ...)`¶

f: Filter = await ap.create_filter(
    phrase="badword",
    context=["home", "notifications"],
    whole_word=True,
)

Creates a new keyword filter.

Parameter	Type	Default	Description
`phrase`	`str`	required	Keyword or phrase to match
`context`	`list[str]`	required	Where to apply: `"home"`, `"notifications"`, `"public"`, `"thread"`, `"account"`
`irreversible`	`bool`	`False`	Drop matching statuses permanently rather than collapsing with a warning
`whole_word`	`bool`	`False`	Match whole words only
`expires_in`	`int \\| None`	`None`	Seconds until the filter expires; `None` = no expiry

Returns: Filter

Note: Implements POST /api/v1/filters (GotoSocial). Requires authentication.

`get_filter(filter_id)`¶

f: Filter = await ap.get_filter("filter-1")

Returns a single keyword filter by ID.

Parameter	Type	Description
`filter_id`	`str`	The filter ID

Returns: Filter

Note: Implements GET /api/v1/filters/:id (GotoSocial). Requires authentication.

`update_filter(filter_id, ...)`¶

f: Filter = await ap.update_filter("filter-1", phrase="newword")

Updates an existing keyword filter. Only parameters provided (not None) are sent.

Parameter	Type	Default	Description
`filter_id`	`str`	required	The filter ID
`phrase`	`str \\| None`	`None`	New keyword
`context`	`list[str] \\| None`	`None`	New contexts
`irreversible`	`bool \\| None`	`None`	New drop/warn setting
`whole_word`	`bool \\| None`	`None`	New whole-word setting
`expires_in`	`int \\| None`	`None`	New expiry in seconds

Returns: Filter

Note: Implements PUT /api/v1/filters/:id (GotoSocial). Requires authentication.

`delete_filter(filter_id)`¶

await ap.delete_filter("filter-1")

Deletes a keyword filter.

Parameter	Type	Description
`filter_id`	`str`	The filter ID to delete

Returns: None

Note: Implements DELETE /api/v1/filters/:id (GotoSocial). Requires authentication.

Instance¶

`get_instance_info()`¶

info: InstanceInfo = await ap.get_instance_info()
print(info.domain, info.version)

Returns extended information about the instance from /api/v2/instance, including usage statistics, contact details, and rules. Also supported on Mastodon.

Note

This endpoint is not available on Pleroma/Akkoma. Use determine_instance_type() for Pleroma instance detection instead.

Returns: InstanceInfo

Note: Implements GET /api/v2/instance (Mastodon, GotoSocial).

Pleroma¶

Methods specific to Pleroma and Akkoma instances. These endpoints are under the /api/v1/pleroma/ and /api/v2/pleroma/ namespaces and are not available on Mastodon or GotoSocial.

Accounts¶

`get_pleroma_account_favourites()`¶

statuses = await ap.get_pleroma_account_favourites(account_id)

Parameter	Type	Description
`account_id`	`str`	The account ID to look up

Returns: list[Status]

Note: Implements GET /api/v1/pleroma/accounts/:id/favourites (Pleroma, Akkoma).

`update_pleroma_avatar()`¶

account = await ap.update_pleroma_avatar(img, filename, mime_type)

Parameter	Type	Description
`img`	`IO[bytes]`	File-like object opened in binary mode
`filename`	`str`	Filename for the multipart form, e.g. `"avatar.jpg"`
`mime_type`	`str`	MIME type, e.g. `"image/jpeg"`

Returns: Account

Note: Implements PATCH /api/v1/pleroma/accounts/update_avatar (Pleroma, Akkoma).

`update_pleroma_banner()`¶

account = await ap.update_pleroma_banner(img, filename, mime_type)

Parameter	Type	Description
`img`	`IO[bytes]`	File-like object opened in binary mode
`filename`	`str`	Filename for the multipart form, e.g. `"banner.jpg"`
`mime_type`	`str`	MIME type, e.g. `"image/jpeg"`

Returns: Account

Note: Implements PATCH /api/v1/pleroma/accounts/update_banner (Pleroma, Akkoma).

`update_pleroma_background()`¶

account = await ap.update_pleroma_background(img, filename, mime_type)

Parameter	Type	Description
`img`	`IO[bytes]`	File-like object opened in binary mode
`filename`	`str`	Filename for the multipart form, e.g. `"bg.jpg"`
`mime_type`	`str`	MIME type, e.g. `"image/jpeg"`

Returns: Account

Note: Implements PATCH /api/v1/pleroma/accounts/update_background (Pleroma, Akkoma).

Reactions¶

`get_pleroma_reactions()`¶

reactions = await ap.get_pleroma_reactions(status_id)

Parameter	Type	Description
`status_id`	`str`	The status ID

Returns: list[EmojiReaction]

Note: Implements GET /api/v1/pleroma/statuses/:id/reactions (Pleroma, Akkoma).

`add_pleroma_reaction()`¶

status = await ap.add_pleroma_reaction(status_id, emoji)

Parameter	Type	Description
`status_id`	`str`	The status ID
`emoji`	`str`	Unicode character (`"👍"`) or shortcode (`":blobcat:"`)

Returns: Status

The emoji is URL-encoded before path interpolation.

Note: Implements PUT /api/v1/pleroma/statuses/:id/reactions/:emoji (Pleroma, Akkoma).

`remove_pleroma_reaction()`¶

status = await ap.remove_pleroma_reaction(status_id, emoji)

Parameter	Type	Description
`status_id`	`str`	The status ID
`emoji`	`str`	Unicode character (`"👍"`) or shortcode (`":blobcat:"`)

Returns: Status

Note: Implements DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji (Pleroma, Akkoma).

Chats¶

`get_pleroma_chats()`¶

chats = await ap.get_pleroma_chats()

Returns: list[Chat]

Note: Implements GET /api/v1/pleroma/chats (Pleroma, Akkoma).

`open_pleroma_chat()`¶

chat = await ap.open_pleroma_chat(account_id)

Parameter	Type	Description
`account_id`	`str`	The account ID to chat with

Returns: Chat

If a chat with the account already exists, the existing chat is returned.

Note: Implements POST /api/v1/pleroma/chats/by-account-id/:id (Pleroma, Akkoma).

`get_pleroma_chat()`¶

chat = await ap.get_pleroma_chat(chat_id)

Parameter	Type	Description
`chat_id`	`str`	The chat ID

Returns: Chat

Note: Implements GET /api/v1/pleroma/chats/:id (Pleroma, Akkoma).

`get_pleroma_chat_messages()`¶

messages = await ap.get_pleroma_chat_messages(chat_id)

Parameter	Type	Description
`chat_id`	`str`	The chat ID

Returns: list[ChatMessage], newest first.

Note: Implements GET /api/v1/pleroma/chats/:id/messages (Pleroma, Akkoma).

`post_pleroma_chat_message()`¶

message = await ap.post_pleroma_chat_message(chat_id, content)

Parameter	Type	Description
`chat_id`	`str`	The chat ID
`content`	`str`	Text content of the message

Returns: ChatMessage

Note: Implements POST /api/v1/pleroma/chats/:id/messages (Pleroma, Akkoma).

`delete_pleroma_chat_message()`¶

message = await ap.delete_pleroma_chat_message(chat_id, message_id)

Parameter	Type	Description
`chat_id`	`str`	The chat ID
`message_id`	`str`	The message ID to delete

Returns: ChatMessage | None

Returns None if the message does not exist (404).

Note: Implements DELETE /api/v1/pleroma/chats/:id/messages/:message_id (Pleroma, Akkoma).

Authentication (static methods)¶

See the Authentication guide for full details and examples.

Method	Description
`APClient.create_app(instance_url, client, ...)`	Register an OAuth app; returns `(client_id, client_secret)`
`APClient.get_auth_token(instance_url, username, password, client, ...)`	Password grant; returns access token
`APClient.generate_authorization_url(instance_url, client_id, ...)`	Build OAuth redirect URL
`APClient.validate_authorization_code(client, instance_url, code, client_id, client_secret)`	Exchange code for token

Pagination¶

After every timeline call, pagination cursors are stored on the client:

statuses = await ap.get_public_timeline(limit=20)

next_max_id = ap.pagination["next"]["max_id"]
if next_max_id:
    more = await ap.get_public_timeline(limit=20, max_id=next_max_id)

ap.pagination layout:

{
    "next": {"max_id": str | None, "min_id": str | None},
    "prev": {"max_id": str | None, "min_id": str | None},
}

Rate limits¶

Rate limit state is updated after every response:

Attribute	Description
`ap.ratelimit_limit`	Requests allowed per window
`ap.ratelimit_remaining`	Requests left in current window
`ap.ratelimit_reset`	`datetime` when window resets

When ratelimit_remaining reaches 0 and the reset time is still in the future, the next call raises RatelimitError before any HTTP request is made. See Error Handling for handling patterns.

API Methods Reference¶

APClient constructor¶

APClient(instance, client, access_token, timeout)¶

APClient.create() (async factory)¶

Instance attributes¶

Credentials¶

verify_credentials()¶

determine_instance_type()¶

Accounts¶

get_account(account_id)¶

get_account_followers(account_id, ...)¶

get_account_following(account_id, ...)¶

get_account_featured_tags(account_id)¶

get_account_lists(account_id)¶

follow_account(account_id, ...)¶

unfollow_account(account_id)¶

unblock_account(account_id)¶

mute_account(account_id, ...)¶

unmute_account(account_id)¶

add_account_note(account_id, comment)¶

get_relationships(ids)¶

get_familiar_followers(ids)¶

search_accounts(q, ...)¶

lookup_account(acct)¶

update_credentials(...)¶

get_mutes(...)¶

get_blocks(...)¶

get_follow_requests(...)¶

authorize_follow_request(account_id)¶

reject_follow_request(account_id)¶

get_follow_suggestions(...)¶

delete_follow_suggestion(account_id)¶

Timelines¶

get_public_timeline()¶

get_home_timeline()¶

get_hashtag_timeline()¶

get_account_statuses()¶

get_list_timeline()¶

get_link_timeline()¶

get_conversations()¶

delete_conversation()¶

read_conversation()¶

get_markers()¶

save_markers()¶

Favourites & Bookmarks¶

get_favourites()¶

get_bookmarks()¶

Statuses¶

post_status()¶

delete_status()¶

reblog()¶

undo_reblog()¶

undo_favourite()¶

get_status()¶

get_status_context()¶

get_reblogged_by()¶

get_favourited_by()¶

favourite()¶

bookmark()¶

unbookmark()¶

mute_status()¶

unmute_status()¶

pin_status()¶

unpin_status()¶

edit_status()¶

get_status_history()¶

get_status_source()¶

translate_status()¶

Scheduled Statuses¶

get_scheduled_statuses()¶

get_scheduled_status()¶

update_scheduled_status()¶

delete_scheduled_status(scheduled_status_id)¶

Lists¶

get_lists()¶

create_list()¶

get_list()¶

update_list()¶

delete_list()¶

get_list_accounts()¶

`APClient` constructor¶

`APClient(instance, client, access_token, timeout)`¶

`APClient.create()` (async factory)¶

`verify_credentials()`¶

`determine_instance_type()`¶

`get_account(account_id)`¶

`get_account_followers(account_id, ...)`¶

`get_account_following(account_id, ...)`¶

`get_account_featured_tags(account_id)`¶

`get_account_lists(account_id)`¶

`follow_account(account_id, ...)`¶

`unfollow_account(account_id)`¶

`unblock_account(account_id)`¶

`mute_account(account_id, ...)`¶

`unmute_account(account_id)`¶

`add_account_note(account_id, comment)`¶

`get_relationships(ids)`¶

`get_familiar_followers(ids)`¶

`search_accounts(q, ...)`¶

`lookup_account(acct)`¶

`update_credentials(...)`¶

`get_mutes(...)`¶

`get_blocks(...)`¶

`get_follow_requests(...)`¶

`authorize_follow_request(account_id)`¶

`reject_follow_request(account_id)`¶

`get_follow_suggestions(...)`¶

`delete_follow_suggestion(account_id)`¶

`get_public_timeline()`¶

`get_home_timeline()`¶

`get_hashtag_timeline()`¶

`get_account_statuses()`¶

`get_list_timeline()`¶

`get_link_timeline()`¶

`get_conversations()`¶

`delete_conversation()`¶

`read_conversation()`¶

`get_markers()`¶

`save_markers()`¶

`get_favourites()`¶

`get_bookmarks()`¶

`post_status()`¶

`delete_status()`¶

`reblog()`¶

`undo_reblog()`¶

`undo_favourite()`¶

`get_status()`¶

`get_status_context()`¶

`get_reblogged_by()`¶

`get_favourited_by()`¶

`favourite()`¶

`bookmark()`¶

`unbookmark()`¶

`mute_status()`¶

`unmute_status()`¶

`pin_status()`¶

`unpin_status()`¶

`edit_status()`¶

`get_status_history()`¶

`get_status_source()`¶

`translate_status()`¶

`get_scheduled_statuses()`¶

`get_scheduled_status()`¶

`update_scheduled_status()`¶

`delete_scheduled_status(scheduled_status_id)`¶

`get_lists()`¶

`create_list()`¶

`get_list()`¶

`update_list()`¶

`delete_list()`¶

`get_list_accounts()`¶

`add_list_accounts()`¶

`delete_list_accounts()`¶

`post_media()`¶

`search()`¶

`get_poll(poll_id)`¶

`vote_poll(poll_id, choices)`¶

`get_trending_statuses()`¶

`get_trending_accounts()`¶

`get_trending_links()`¶