Filters

Filters let you hide or collapse content matching specific keywords or statuses from your timelines.

longwei implements two filter APIs:

• Mastodon v2 filters — the methods documented on this page. Rich filter objects that group multiple keywords and statuses under a named rule with a configurable action.
• GotoSocial v1 filters — simpler single-keyword filters accessed via get_filters(), create_filter(), get_filter(), update_filter(), and delete_filter(). See the API Methods reference for details.

---

Server compatibility

Server	v2 Filter support
Mastodon	✅ Full support
Pleroma / Akkoma	❌ Not supported — returns 404 Not Found → raises NotFoundError
GotoSocial	❌ Not supported (uses v1 filters only) → raises NotFoundError

All v2 filter methods require authentication.

---

Managing v2 filters

Get all filters

from longwei import APClient, FilterV2
import httpx

async with httpx.AsyncClient() as client:
    ap = await APClient.create(
        instance="mastodon.social",
        client=client,
        access_token="your_token",
    )
    filters: list[FilterV2] = await ap.get_filters_v2()
    for f in filters:
        print(f"{f.id}: {f.title} ({f.filter_action})")

Create a filter

f: FilterV2 = await ap.create_filter_v2(
    title="Spam words",
    context=["home", "notifications", "public"],
    filter_action="warn",   # "warn" (default) collapses; "hide" drops entirely
)
print(f"Created filter {f.id}: {f.title}")

With an inline keyword:

f = await ap.create_filter_v2(
    title="Spam words",
    context=["home"],
    keywords_attributes=[
        {"keyword": "badword", "whole_word": True},
        {"keyword": "otherspam", "whole_word": False},
    ],
)

With an expiry:

f = await ap.create_filter_v2(
    title="Temporary filter",
    context=["home"],
    expires_in=86400,   # expires in 24 hours
)

Get a single filter

f: FilterV2 = await ap.get_filter_v2("12345")
print(f.title, f.filter_action)
for kw in f.keywords:
    print(f"  keyword: {kw.keyword} (whole_word={kw.whole_word})")

Update a filter

Only the parameters provided are sent — omit fields you don't want to change.

f = await ap.update_filter_v2(
    "12345",
    title="Updated title",
    filter_action="hide",
)

Delete a filter

await ap.delete_filter_v2("12345")

---

Managing filter keywords

Keywords are the phrases that trigger a filter. A filter can have multiple keywords.

Get keywords for a filter

from longwei import FilterKeyword

keywords: list[FilterKeyword] = await ap.get_filter_keywords("12345")
for kw in keywords:
    print(f"{kw.id}: {kw.keyword} (whole_word={kw.whole_word})")

Add a keyword

kw: FilterKeyword = await ap.add_filter_keyword(
    "12345",
    keyword="badword",
    whole_word=True,   # match whole words only; defaults to False
)
print(f"Added keyword {kw.id}: {kw.keyword}")

---

Managing filter statuses

In addition to keywords, you can add specific statuses directly to a filter so they are always matched regardless of their content.

Get statuses for a filter

from longwei import FilterStatus

filter_statuses: list[FilterStatus] = await ap.get_filter_statuses("12345")
for fs in filter_statuses:
    print(f"{fs.id}: status_id={fs.status_id}")

Add a status

fs: FilterStatus = await ap.add_filter_status(
    "12345",
    status_id="109031952222346765",
)
print(f"Added filter-status entry {fs.id}")

---

filter_action values

Value	Behaviour
"warn"	Matching content is collapsed with a content warning. The user can expand it.
"hide"	Matching content is permanently dropped and never shown.

The server default when filter_action is omitted is "warn".

---

Valid context values

Value	Where the filter applies
"home"	Home timeline
"notifications"	Notifications
"public"	Public timelines (federated and local)
"thread"	Conversation threads
"account"	Account profiles