Skip to content

KeywordFilter

A keyword filter of the user, which only the user sees. The server matches the posts it returns against the filters of their contexts, so every client gets the same result; the user’s own posts and boosts are never matched.

object
id
required

The ID of a resource, a UUIDv7 in its canonical string form.

string format: uuid
title
required

The name of the filter, 1 to 50 characters, which a folded post shows.

string
action
required

What a keyword filter does to a post that matches it: warn returns the post with the filter in its filtered, and clients fold it behind the filter’s title; hide leaves the post out, as if the user could not see it.

string
Allowed values: warn hide
contexts
required

Where the filter applies, at least one.

Array<string>
>= 1 items
Allowed values: home notifications public thread account
keywords
required

The words of the filter, in the order given; a post matches the filter when it matches any of them.

Array<object>
>= 1 items

A word of a keyword filter.

object
keyword
required

The word or phrase, as the user typed it. It matches the text, the content warning, the poll’s choices, and the alt text of a post, each on its own, regardless of case, of half-width and full-width forms, and of katakana and hiragana; runs of white space match one space. Up to 100 characters once normalized.

string
>= 1 characters <= 400 characters
whole_word
required

Whether the word matches only where no letter, digit, or _ touches it. Characters of scripts that do not separate words with spaces (Chinese, Japanese, Thai, and the like) never count as touching, so there the word matches anywhere.

boolean
expires_at

When the filter stops applying; omitted for a filter that never does. An expired filter stays, applying nowhere, and applies again when its expiry moves later.

string format: date-time
expired
required

Whether the filter has expired and applies nowhere.

boolean
created_at
required

When the user created the filter.

string format: date-time

Example generated

{
"id": "01890a5d-ac96-774b-bcce-b302099a8057",
"title": "example",
"action": "warn",
"contexts": [
"home"
],
"keywords": [
{
"keyword": "example",
"whole_word": true
}
],
"expires_at": "2026-04-15T12:00:00Z",
"expired": true,
"created_at": "2026-04-15T12:00:00Z"
}

For LLMs and coding agents:llms.txt,llms-full.txt, llms-small.txt

Analytics on this site