API Coverage¶

This page tracks which upstream REST API endpoints are implemented in longwei. The library targets compatibility with Mastodon, Pleroma/Akkoma, GotoSocial, and snac.

All targeted Mastodon v1/v2 API endpoints are now implemented (admin, push notification, and proof endpoints are intentionally out of scope).

Implemented¶

Method	HTTP	Endpoint	Mastodon	Pleroma	GotoSocial	snac	Notes
`APClient.create_app()`	POST	`/api/v1/apps`	✅	✅	✅	✅
`APClient.generate_authorization_url()`	—	`/oauth/authorize`	✅	✅	✅	✅	URL construction only; no HTTP call
`APClient.validate_authorization_code()`	POST	`/oauth/token`	✅	✅	✅	✅	`grant_type=authorization_code`
`APClient.get_auth_token()`	POST	`/oauth/token`	⚠️	✅	✅	✅	`grant_type=password`; not supported by most Mastodon instances
`determine_instance_type()`	GET	`/api/v2/instance` (v1 fallback)	✅	✅	✅	✅	Probes v2 first; falls back to v1 on non-success (Pleroma, snac, older Mastodon)
`verify_credentials()`	GET	`/api/v1/accounts/verify_credentials`	✅	✅	✅	✅
`get_public_timeline()`	GET	`/api/v1/timelines/public`	✅	✅	✅	✅
`get_home_timeline()`	GET	`/api/v1/timelines/home`	✅	✅	✅	✅	Requires authentication
`get_hashtag_timeline()`	GET	`/api/v1/timelines/tag/:hashtag`	✅	✅	✅	✅
`get_account_statuses()`	GET	`/api/v1/accounts/:id/statuses`	✅	✅	✅	✅
`post_status()`	POST	`/api/v1/statuses`	✅	✅	✅	✅
`delete_status()`	DELETE	`/api/v1/statuses/:id`	✅	✅	✅	❌	Pleroma: auto-calls `undo_reblog`/`undo_favourite` if needed. snac: raises `ClientError` (no DELETE support).
`reblog()`	POST	`/api/v1/statuses/:id/reblog`	✅	✅	✅	✅
`undo_reblog()`	POST	`/api/v1/statuses/:id/unreblog`	✅	✅	✅	✅
`undo_favourite()`	POST	`/api/v1/statuses/:id/unfavourite`	✅	✅	✅	✅
`post_media()`	POST	`/api/v2/media` (v1 fallback)	✅	✅	✅	✅	Tries v2 first; falls back to v1 on 404. Polls on HTTP 202.
`update_media()`	PUT	`/api/v1/media/:id`	✅	✅	✅	✅	Updates description/focus before posting
`search()`	GET	`/api/v2/search` (v1 fallback)	✅	✅	✅	✅	Tries v2 first; falls back to v1 on 404 (Pleroma). v1 drops advanced params.
`get_trending_statuses()`	GET	`/api/v1/trends/statuses`	✅	❌	❌	❌
`get_trending_accounts()`	GET	`/api/v1/trends/accounts`	✅	❌	❌	❌
`get_trending_links()`	GET	`/api/v1/trends/links`	✅	❌	❌	❌	Returns `Card` objects
`get_directory()`	GET	`/api/v1/directory`	✅	❌	❌	❌
`get_custom_emojis()`	GET	`/api/v1/custom_emojis`	✅	✅	✅	✅	snac returns an empty list
`get_list_timeline()`	GET	`/api/v1/timelines/list/:list_id`	✅	❌	❌	❌	Requires authentication
`get_link_timeline()`	GET	`/api/v1/timelines/link`	✅	❌	❌	❌
`get_conversations()`	GET	`/api/v1/conversations`	✅	❌	❌	❌	Requires authentication
`delete_conversation()`	DELETE	`/api/v1/conversations/:id`	✅	❌	❌	❌	Requires authentication
`read_conversation()`	POST	`/api/v1/conversations/:id/read`	✅	❌	❌	❌	Requires authentication
`get_markers()`	GET	`/api/v1/markers`	✅	❌	❌	❌	Requires authentication
`save_markers()`	POST	`/api/v1/markers`	✅	❌	❌	❌	Requires authentication
`get_account_moved_to()`	GET	`/api/v1/accounts/:id/moved_to`	❌	❌	✅	❌	Returns `None` if no migration
`get_account_aliases()`	GET	`/api/v1/accounts/:id/aliases`	❌	❌	✅	❌	Returns list of URI strings
`block_account()`	POST	`/api/v1/accounts/:id/block`	✅	❌	✅	❌	Returns `Relationship`
`get_profile_avatar()`	GET	`/api/v1/profile/avatar`	❌	❌	✅	❌	Requires authentication
`delete_profile_avatar()`	DELETE	`/api/v1/profile/avatar`	❌	❌	✅	❌	Requires authentication
`get_profile_header()`	GET	`/api/v1/profile/header`	❌	❌	✅	❌	Requires authentication
`delete_profile_header()`	DELETE	`/api/v1/profile/header`	❌	❌	✅	❌	Requires authentication
`get_filters()`	GET	`/api/v1/filters`	❌	❌	✅	❌	GotoSocial v1 filters only
`create_filter()`	POST	`/api/v1/filters`	❌	❌	✅	❌	GotoSocial v1 filters only
`get_filter()`	GET	`/api/v1/filters/:id`	❌	❌	✅	❌	GotoSocial v1 filters only
`update_filter()`	PUT	`/api/v1/filters/:id`	❌	❌	✅	❌	GotoSocial v1 filters only
`delete_filter()`	DELETE	`/api/v1/filters/:id`	❌	❌	✅	❌	GotoSocial v1 filters only
`get_filters_v2()`	GET	`/api/v2/filters`	✅	❌	❌	❌	Returns `list[FilterV2]`
`create_filter_v2()`	POST	`/api/v2/filters`	✅	❌	❌	❌	Returns `FilterV2`
`get_filter_v2()`	GET	`/api/v2/filters/:id`	✅	❌	❌	❌	Returns `FilterV2`
`update_filter_v2()`	PUT	`/api/v2/filters/:id`	✅	❌	❌	❌	Returns `FilterV2`
`delete_filter_v2()`	DELETE	`/api/v2/filters/:id`	✅	❌	❌	❌
`get_filter_keywords()`	GET	`/api/v2/filters/:id/keywords`	✅	❌	❌	❌	Returns `list[FilterKeyword]`
`add_filter_keyword()`	POST	`/api/v2/filters/:id/keywords`	✅	❌	❌	❌	Returns `FilterKeyword`
`get_filter_statuses()`	GET	`/api/v2/filters/:id/statuses`	✅	❌	❌	❌	Returns `list[FilterStatus]`
`add_filter_status()`	POST	`/api/v2/filters/:id/statuses`	✅	❌	❌	❌	Returns `FilterStatus`
`get_reports()`	GET	`/api/v1/reports`	❌	❌	✅	❌	Requester's own filed reports
`create_report()`	POST	`/api/v1/reports`	✅	⚠️	✅	❌	Pleroma: `category` and `rule_ids` ignored
`get_poll()`	GET	`/api/v1/polls/:id`	✅	✅	✅	✅
`vote_poll()`	POST	`/api/v1/polls/:id/votes`	✅	✅	✅	✅	GotoSocial: remote-poll voting returns 422
`get_instance_info()`	GET	`/api/v2/instance`	✅	⚠️	✅	❌	Pleroma: endpoint unavailable; use `determine_instance_type()` instead. snac: v2 endpoint not supported.
`get_status()`	GET	`/api/v1/statuses/:id`	✅	✅	✅	✅
`get_status_context()`	GET	`/api/v1/statuses/:id/context`	✅	✅	✅	✅	Returns `Context`
`get_reblogged_by()`	GET	`/api/v1/statuses/:id/reblogged_by`	✅	✅	✅	✅	Returns `list[Account]`
`get_favourited_by()`	GET	`/api/v1/statuses/:id/favourited_by`	✅	✅	✅	✅	Returns `list[Account]`
`favourite()`	POST	`/api/v1/statuses/:id/favourite`	✅	✅	✅	✅
`bookmark()`	POST	`/api/v1/statuses/:id/bookmark`	✅	❌	✅	❌
`unbookmark()`	POST	`/api/v1/statuses/:id/unbookmark`	✅	❌	✅	❌
`mute_status()`	POST	`/api/v1/statuses/:id/mute`	✅	❌	✅	❌	Requires authentication
`unmute_status()`	POST	`/api/v1/statuses/:id/unmute`	✅	❌	✅	❌	Requires authentication
`pin_status()`	POST	`/api/v1/statuses/:id/pin`	✅	❌	✅	✅	Requires authentication
`unpin_status()`	POST	`/api/v1/statuses/:id/unpin`	✅	❌	✅	✅	Requires authentication
`edit_status()`	PUT	`/api/v1/statuses/:id`	✅	❌	❌	❌	Mastodon 3.5+
`get_status_history()`	GET	`/api/v1/statuses/:id/history`	✅	❌	❌	❌	Mastodon 3.5+; returns `list[StatusEdit]`
`get_status_source()`	GET	`/api/v1/statuses/:id/source`	✅	❌	❌	❌	Mastodon 3.5+; returns `StatusSource`
`translate_status()`	POST	`/api/v1/statuses/:id/translate`	✅	❌	❌	❌	Mastodon 4.0+; returns `Translation`
`get_scheduled_statuses()`	GET	`/api/v1/scheduled_statuses`	✅	❌	❌	❌	Requires authentication; paginated
`get_scheduled_status()`	GET	`/api/v1/scheduled_statuses/:id`	✅	❌	❌	❌
`update_scheduled_status()`	PUT	`/api/v1/scheduled_statuses/:id`	✅	❌	❌	❌	Reschedule only; updates `scheduled_at`
`delete_scheduled_status()`	DELETE	`/api/v1/scheduled_statuses/:id`	✅	❌	❌	❌	Cancels the scheduled status
`get_pleroma_account_favourites()`	GET	`/api/v1/pleroma/accounts/:id/favourites`	❌	✅	❌	❌	Returns `list[Status]`
`update_pleroma_avatar()`	PATCH	`/api/v1/pleroma/accounts/update_avatar`	❌	✅	❌	❌	Multipart file upload; returns `Account`
`update_pleroma_banner()`	PATCH	`/api/v1/pleroma/accounts/update_banner`	❌	✅	❌	❌	Multipart file upload; returns `Account`
`update_pleroma_background()`	PATCH	`/api/v1/pleroma/accounts/update_background`	❌	✅	❌	❌	Multipart file upload; returns `Account`
`get_pleroma_reactions()`	GET	`/api/v1/pleroma/statuses/:id/reactions`	❌	✅	❌	❌	Returns `list[EmojiReaction]`
`add_pleroma_reaction()`	PUT	`/api/v1/pleroma/statuses/:id/reactions/:emoji`	❌	✅	❌	❌	Emoji is URL-encoded; returns `Status`
`remove_pleroma_reaction()`	DELETE	`/api/v1/pleroma/statuses/:id/reactions/:emoji`	❌	✅	❌	❌	Emoji is URL-encoded; returns `Status`
`search()` (Pleroma branch)	GET	`/api/v2/pleroma/search`	—	✅	—	—	Routed automatically when `instance_type == INSTANCE_TYPE_PLEROMA`; all params preserved
`get_pleroma_chats()`	GET	`/api/v1/pleroma/chats`	❌	✅	❌	❌	Returns `list[Chat]`
`open_pleroma_chat()`	POST	`/api/v1/pleroma/chats/by-account-id/:id`	❌	✅	❌	❌	Returns `Chat`
`get_pleroma_chat()`	GET	`/api/v1/pleroma/chats/:id`	❌	✅	❌	❌	Returns `Chat`
`get_pleroma_chat_messages()`	GET	`/api/v1/pleroma/chats/:id/messages`	❌	✅	❌	❌	Returns `list[ChatMessage]`
`post_pleroma_chat_message()`	POST	`/api/v1/pleroma/chats/:id/messages`	❌	✅	❌	❌	Returns `ChatMessage`
`delete_pleroma_chat_message()`	DELETE	`/api/v1/pleroma/chats/:id/messages/:message_id`	❌	✅	❌	❌	Returns `ChatMessage \\| None` (None on 404)
`get_notifications()`	GET	`/api/v1/notifications`	✅	✅	✅	✅	Requires authentication; paginated; filterable by type
`get_notification()`	GET	`/api/v1/notifications/:id`	✅	✅	✅	❌
`clear_notifications()`	POST	`/api/v1/notifications/clear`	✅	✅	✅	✅	Requires authentication
`dismiss_notification()`	POST	`/api/v1/notifications/:id/dismiss`	✅	✅	✅	❌
`get_notifications_v2()`	GET	`/api/v2/notifications`	✅	❌	❌	❌	Mastodon 4.3+ only; returns `GroupedNotificationsResults`
`get_notification_group_accounts()`	GET	`/api/v2/notifications/:group_key/accounts`	✅	❌	❌	❌	Mastodon 4.3+ only; returns `list[Account]`
`get_favourites()`	GET	`/api/v1/favourites`	✅	❌	✅	❌	Requires authentication; paginated. Pleroma: not supported — use `get_pleroma_account_favourites()` instead.
`get_bookmarks()`	GET	`/api/v1/bookmarks`	✅	❌	✅	❌	Requires authentication; paginated. Pleroma: not supported.
`get_lists()`	GET	`/api/v1/lists`	✅	❌	❌	❌	Mastodon only. Requires authentication. Returns `list[UserList]`.
`create_list()`	POST	`/api/v1/lists`	✅	❌	❌	❌	Mastodon only. Returns `UserList`.
`get_list()`	GET	`/api/v1/lists/:id`	✅	❌	❌	❌	Mastodon only. Returns `UserList`.
`update_list()`	PUT	`/api/v1/lists/:id`	✅	❌	❌	❌	Mastodon only. Returns `UserList`.
`delete_list()`	DELETE	`/api/v1/lists/:id`	✅	❌	❌	❌	Mastodon only. Returns `None`.
`get_list_accounts()`	GET	`/api/v1/lists/:id/accounts`	✅	❌	❌	❌	Mastodon only. Returns `list[Account]`; paginated.
`add_list_accounts()`	POST	`/api/v1/lists/:id/accounts`	✅	❌	❌	❌	Mastodon only. Accounts must be followed. Returns `None`.
`delete_list_accounts()`	DELETE	`/api/v1/lists/:id/accounts`	✅	❌	❌	❌	Mastodon only. Returns `None`.
`get_instance_peers()`	GET	`/api/v1/instance/peers`	✅	⚠️	⚠️	❌	Pleroma: returns `[]` by default. GotoSocial: requires `instance-expose-peers: true`; returns 404 otherwise.
`get_instance_activity()`	GET	`/api/v1/instance/activity`	✅	❌	❌	❌	Returns `list[Activity]` (counts as strings). Pleroma/GotoSocial return 404.
`get_instance_rules()`	GET	`/api/v1/instance/rules`	✅	⚠️	✅	❌	Returns `list[Rule]`. Pleroma may return `[]`.
`get_instance_domain_blocks()`	GET	`/api/v1/instance/domain_blocks`	✅	⚠️	⚠️	❌	Unauthenticated view may be obfuscated. GotoSocial: requires `instance-expose-blocklist: true`.
`get_announcements()`	GET	`/api/v1/announcements`	✅	❌	❌	❌	Requires authentication. Returns `list[Announcement]`. Pleroma/GotoSocial return 404.
`dismiss_announcement()`	POST	`/api/v1/announcements/:id/dismiss`	✅	❌	❌	❌	Requires authentication. Pleroma/GotoSocial return 404.
`add_announcement_reaction()`	PUT	`/api/v1/announcements/:id/reactions/:name`	✅	❌	❌	❌	Emoji `name` is URL-encoded. Pleroma/GotoSocial return 404.
`remove_announcement_reaction()`	DELETE	`/api/v1/announcements/:id/reactions/:name`	✅	❌	❌	❌	Emoji `name` is URL-encoded. Pleroma/GotoSocial return 404.
`get_account()`	GET	`/api/v1/accounts/:id`	✅	✅	✅	✅	Returns `Account`.
`get_account_followers()`	GET	`/api/v1/accounts/:id/followers`	✅	✅	✅	✅	Paginated. Returns `list[Account]`.
`get_account_following()`	GET	`/api/v1/accounts/:id/following`	✅	✅	✅	✅	Paginated. Returns `list[Account]`.
`get_account_featured_tags()`	GET	`/api/v1/accounts/:id/featured_tags`	✅	❌	❌	❌	Returns `list[FeaturedTag]`. Pleroma/GotoSocial/snac return 404.
`get_account_lists()`	GET	`/api/v1/accounts/:id/lists`	✅	❌	❌	❌	Mastodon only. Requires authentication. Returns `list[UserList]`.
`follow_account()`	POST	`/api/v1/accounts/:id/follow`	✅	✅	✅	❌	Returns `Relationship`. Optional `reblogs`, `notify`, `languages[]` params. snac: not supported.
`unfollow_account()`	POST	`/api/v1/accounts/:id/unfollow`	✅	✅	✅	❌	Returns `Relationship`. snac: not supported.
`unblock_account()`	POST	`/api/v1/accounts/:id/unblock`	✅	❌	✅	❌	Returns `Relationship`. Pleroma/snac: not supported.
`mute_account()`	POST	`/api/v1/accounts/:id/mute`	✅	❌	✅	❌	Returns `Relationship`. Optional `notifications`, `duration` params. Pleroma/snac: not supported.
`unmute_account()`	POST	`/api/v1/accounts/:id/unmute`	✅	❌	✅	❌	Returns `Relationship`. Pleroma/snac: not supported.
`add_account_note()`	POST	`/api/v1/accounts/:id/note`	✅	❌	❌	❌	Mastodon 4.0+. Returns `Relationship`. Others return 404.
`get_relationships()`	GET	`/api/v1/accounts/relationships`	✅	✅	✅	❌	Requires authentication. Takes `ids: list[str]`. Returns `list[Relationship]`.
`get_familiar_followers()`	GET	`/api/v1/accounts/familiar_followers`	✅	❌	❌	❌	Mastodon 3.5+. Takes `ids: list[str]`. Returns `list[FamiliarFollowers]`.
`search_accounts()`	GET	`/api/v1/accounts/search`	✅	✅	✅	❌	Returns `list[Account]`. Optional `limit`, `resolve`, `following` params.
`lookup_account()`	GET	`/api/v1/accounts/lookup`	✅	❌	✅	❌	Mastodon 3.3+, GotoSocial. Returns `Account`. Pleroma/snac return 404.
`update_credentials()`	PATCH	`/api/v1/accounts/update_credentials`	✅	✅	✅	❌	Returns `Account`. Supports avatar/header file upload. snac: not supported.
`get_mutes()`	GET	`/api/v1/mutes`	✅	❌	✅	❌	Requires authentication. Paginated. Returns `list[Account]`.
`get_blocks()`	GET	`/api/v1/blocks`	✅	❌	✅	❌	Requires authentication. Paginated. Returns `list[Account]`.
`get_follow_requests()`	GET	`/api/v1/follow_requests`	✅	❌	✅	❌	Requires authentication. Paginated. Returns `list[Account]`.
`authorize_follow_request()`	POST	`/api/v1/follow_requests/:id/authorize`	✅	❌	✅	❌	Requires authentication. Returns `Relationship`.
`reject_follow_request()`	POST	`/api/v1/follow_requests/:id/reject`	✅	❌	✅	❌	Requires authentication. Returns `Relationship`.
`get_follow_suggestions()`	GET	`/api/v1/suggestions`	✅	❌	❌	❌	Mastodon only. Requires authentication. Returns `list[Account]`.
`delete_follow_suggestion()`	DELETE	`/api/v1/suggestions/:id`	✅	❌	❌	❌	Mastodon only. Requires authentication.

Pleroma / Akkoma — implementation notes¶

Pleroma and Akkoma expose additional endpoints under /api/v1/pleroma/ and /api/v2/pleroma/ beyond the Mastodon-compatible API. All are now implemented.

Handled quirks¶

delete_status() detects Pleroma instances and calls undo_reblog() or undo_favourite() before deletion when required.
determine_instance_type() reads version from /api/v1/instance to detect Pleroma and adjust max_attachments and other limits.
search() routes to /api/v2/pleroma/search automatically on Pleroma instances, preserving all query parameters (no lossy v1 fallback).
create_report() is accepted by Pleroma/Akkoma but the category and rule_ids fields are silently ignored; only account_id, status_ids[], and comment are meaningful.
vote_poll() works on Pleroma/Akkoma without quirks. GotoSocial returns 422 when attempting to vote on a poll hosted on a remote instance.
follow_account() and unfollow_account() work on Pleroma/Akkoma. unblock_account(), mute_account(), unmute_account(), get_mutes(), get_blocks(), get_follow_requests(), authorize_follow_request(), and reject_follow_request() are not supported on Pleroma/Akkoma; they return 404, which raises NotFoundError.
get_relationships() and search_accounts() work on Pleroma/Akkoma.
get_account(), get_account_followers(), and get_account_following() work on Pleroma/Akkoma.
update_credentials() is accepted by Pleroma/Akkoma; some fields such as discoverable may be silently ignored.
get_notifications() and related v1 endpoints work across all three server types. Pleroma/Akkoma emits additional notification types beyond the Mastodon set: pleroma:emoji_reaction, pleroma:chat_mention, and pleroma:report. The types[] and exclude_types[] filter parameters are honoured on all three servers.
get_favourites() is not supported on Pleroma/Akkoma; callers should use get_pleroma_account_favourites() instead. get_bookmarks() has no Pleroma equivalent. Both work on GotoSocial.
All list management endpoints (get_lists, create_list, etc.) are Mastodon-only. Pleroma/Akkoma and GotoSocial return 404 Not Found, which raises NotFoundError.
get_notifications_v2() and get_notification_group_accounts() are Mastodon 4.3+ only. Pleroma/Akkoma and GotoSocial return 404, which raises NotFoundError. These endpoints return GroupedNotificationsResults — a structurally different shape from the flat list[Notification] returned by get_notifications() — so they are exposed as separate methods rather than a silent v2→v1 fallback.
get_instance_activity(), get_announcements(), dismiss_announcement(), add_announcement_reaction(), and remove_announcement_reaction() are Mastodon-only. Pleroma/Akkoma and GotoSocial return 404, which raises NotFoundError.
get_instance_peers() and get_instance_domain_blocks() are available on GotoSocial only when the server operator enables instance-expose-peers and instance-expose-blocklist respectively; the server returns 404 otherwise, raising NotFoundError.
get_instance_rules() is supported on Mastodon and GotoSocial. Pleroma/Akkoma may return an empty list if no rules are configured.

snac — implementation notes¶

snac (Social Networks Are Crap) is a minimal ActivityPub server written in C. It supports a subset of the Mastodon-compatible API since version 2.27.

Handled quirks¶

delete_status() raises ClientError immediately on snac instances. snac implements no DELETE endpoints via the Mastodon API; attempting deletion would return an error from the server. Callers should check instance_type == INSTANCE_TYPE_SNAC before calling this method.
determine_instance_type() detects snac via the version field in /api/v1/instance, which contains the string "snac" (e.g. "4.0.0 (not true; really snac/2.77)"). snac does not support /api/v2/instance; detection always uses the v1 fallback path.
snac does not return X-RateLimit-* headers. ratelimit_reset is set to a synthetic 5-minute window, the same behaviour as for Pleroma.
snac reports a maximum of 8 media attachments per status. max_attachments is set to MAX_ATTACHMENTS_SNAC (8) on detection.
get_custom_emojis() returns an empty list on snac; this is expected behaviour.
search() uses the standard /api/v2/search endpoint on snac (no special routing, unlike Pleroma).
get_account(), get_account_followers(), and get_account_following() work on snac. All other account-management endpoints (follow_account(), mute_account(), update_credentials(), etc.) are not supported; snac returns an error.