This FEP proposes using the TREE Hypermedia Vocabulary for client-initiated filter requests on ActivityPub Collections (especially Inbox). Clients can send a filter as a JSON-LD object via HTTP POST to retrieve a filtered subset of the collection.
This enables use cases such as:
Create, Update, Delete, Announce) from followed actors, visible to public or followersas:to or as:ccas:Public (DMs, followers-only, group messages)The context document for this ActivityPub extension is at https://w3id.org/fep/34c1/context. Its contents are as follows:
{
"@context": {
"fep34c1": "https://w3id.org/fep/34c1#",
"FilterRequest": "fep34c1:FilterRequest",
"pageSize": {
"@id": "fep34c1:pageSize",
"@type": "http://www.w3.org/2001/XMLSchema#nonNegativeInteger"
},
"myFollowees": { "@id": "fep34c1:myFollowees", "@type": "@id" },
"myAudience": { "@id": "fep34c1:myAudience", "@type": "@id" }
}
}
fep34c1:FilterRequest| URI | https://w3id.org/fep/34c1#FilterRequest |
| Notes | A container object for a filter query. It holds one or more tree:relation entries that define the filter criteria, and an optional fep34c1:pageSize to control pagination. |
| Domain | (none) |
| Range | (none) |
fep34c1:pageSize| URI | https://w3id.org/fep/34c1#pageSize |
| Notes | The maximum number of items per page in the filtered response. |
| Domain | fep34c1:FilterRequest |
| Range | xsd:nonNegativeInteger |
| Functional | Yes |
fep34c1:myFollowees| URI | https://w3id.org/fep/34c1#myFollowees |
| Notes | Server-resolved placeholder. When used as tree:value, the server MUST replace it with the set of actor IRIs from the following collection of the authenticated (requesting) actor. |
fep34c1:myAudience| URI | https://w3id.org/fep/34c1#myAudience |
| Notes | Server-resolved placeholder. When used as tree:value, the server MUST resolve it to all collection IRIs in which the authenticated actor is known to be a member. This includes at minimum the followers collections of followed actors, and MAY include group memberships, lists, or other collections as the server discovers them. |
ActivityPub defines Collections (Inbox, Outbox, Followers, etc.) but no mechanism for clients to request filtered views. Clients must:
For a “Home Timeline” (activities from followees), this is particularly inefficient since the inbox also contains follow requests, likes, and other irrelevant activities.
| Approach | Problem |
|---|---|
| FEP-5bf0 | WITHDRAWN (June 2025); focused on server-side views, not client queries |
| Hydra | GET-oriented (URL templates), not for POST queries |
| SPARQL | Too complex for simple filters, security risks |
| Proprietary | Mastodon’s /api/v1/timelines/home is not standardized |
The TREE Hypermedia Vocabulary offers:
tree:path, tree:value, tree:Relation)Servers MAY provide a filter endpoint for collections:
POST /ap/actors/{username}/inbox/filter
Content-Type: application/ld+json
The endpoint MUST be announced in the Collection object via the tree:search property:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/tree"
],
"type": "OrderedCollection",
"id": "https://example.com/ap/actors/alice/inbox",
"tree:search": {
"@type": "fep34c1:FilterEndpoint",
"tree:template": "https://example.com/ap/actors/alice/inbox/filter"
}
}
A filter request is a JSON-LD object of type fep34c1:FilterRequest:
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "rdf:type" },
"tree:value": [
{ "@id": "as:Create" },
{ "@id": "as:Update" },
{ "@id": "as:Delete" },
{ "@id": "as:Announce" }
]
},
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "as:actor" },
"tree:value": { "@id": "fep34c1:myFollowees" }
},
{
"@type": "tree:EqualToRelation",
"tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
"tree:value": [
{ "@id": "https://www.w3.org/ns/activitystreams#Public" },
{ "@id": "fep34c1:myAudience" }
]
}
],
"fep34c1:pageSize": 20
}
| Relation | Semantics | SPARQL Equivalent |
|---|---|---|
tree:EqualToRelation |
Value is equal to | ?x = ?value |
tree:NotEqualToRelation |
Value is not equal to | ?x != ?value |
tree:GreaterThanRelation |
Value is greater than | ?x > ?value |
tree:LessThanRelation |
Value is less than | ?x < ?value |
tree:GreaterThanOrEqualToRelation |
Value is greater than or equal to | ?x >= ?value |
tree:LessThanOrEqualToRelation |
Value is less than or equal to | ?x <= ?value |
| Relation | Semantics | SPARQL Equivalent |
|---|---|---|
tree:PrefixRelation |
Value starts with | STRSTARTS(?x, ?value) |
tree:SubstringRelation |
Value contains | CONTAINS(?x, ?value) |
tree:SuffixRelation |
Value ends with | STRENDS(?x, ?value) |
fep34c1:myFollowees - Dynamic Followee ListThe value fep34c1:myFollowees is a server-resolved placeholder. When used as tree:value, the server MUST replace it with the set of actor IRIs from the following collection of the authenticated (requesting) actor.
This means a relation like:
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "as:actor" },
"tree:value": { "@id": "fep34c1:myFollowees" }
}
is equivalent to: “Return only activities where the as:actor property matches one of the actor IRIs in the requesting actor’s following collection.” In other words, only activities authored by actors that the requesting user follows will be included in the result.
fep34c1:myAudience - Dynamic Audience CollectionsThe value fep34c1:myAudience is a server-resolved placeholder. When used as tree:value, the server MUST resolve it to all collection IRIs in which the authenticated actor is known to be a member. This includes at minimum the followers collections of followed actors, and MAY include group memberships, lists, or other collections.
This is useful for audience filtering: Fediverse servers typically address followers-only posts with the actor’s followers collection IRI in as:to or as:cc.
Note: These are explicit FEP-34c1 placeholder properties rather than reused ActivityStreams terms. An earlier version of this spec used
as:followingandas:followersas placeholders, but this was semantically incorrect —as:followersdenotes the collection itself, not its items (see discussion). Using dedicated FEP-34c1 properties makes the server-resolved semantics explicit and avoids overloading AS2 vocabulary. An alternative approach using SHACL Property Paths was considered but rejected due to the complexity of expressing pagination traversal in SHACL path expressions.
If tree:value is an array, the values are combined with OR:
{
"tree:value": [
{ "@id": "as:Create" },
{ "@id": "as:Update" },
{ "@id": "as:Delete" },
{ "@id": "as:Announce" }
]
}
Semantics: rdf:type = as:Create OR rdf:type = as:Update OR rdf:type = as:Delete OR rdf:type = as:Announce
If tree:path is an array, the filter matches if any of the specified paths contains a matching value. This is equivalent to a UNION in SPARQL.
{
"@type": "tree:EqualToRelation",
"tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
"tree:value": { "@id": "https://example.com/ap/actors/alice" }
}
Semantics: “Match if the value appears in as:to OR in as:cc.”
This is particularly useful for audience filtering, since ActivityPub activities use both as:to and as:cc for addressing.
Multiple tree:relation entries are combined with AND:
{
"tree:relation": [
{ "@type": "tree:EqualToRelation", "tree:path": {"@id": "rdf:type"}, "tree:value": {"@id": "as:Create"} },
{ "@type": "tree:EqualToRelation", "tree:path": {"@id": "as:actor"}, "tree:value": {"@id": "fep34c1:myFollowees"} },
{ "@type": "tree:EqualToRelation", "tree:path": [{"@id": "as:to"}, {"@id": "as:cc"}], "tree:value": {"@id": "https://www.w3.org/ns/activitystreams#Public"} }
]
}
Semantics: rdf:type = as:Create AND as:actor IN myFollowees AND (as:to = as:Public OR as:cc = as:Public)
The response is an OrderedCollectionPage with the filtered items. Pagination MUST use as:next and as:prev (standard ActivityStreams pagination). Servers MAY additionally include tree:relation entries to provide boundary values for TREE-aware clients.
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://w3id.org/tree",
{ "fep34c1": "https://w3id.org/fep/34c1#" }
],
"@type": "OrderedCollectionPage",
"partOf": "https://example.com/ap/actors/alice/inbox",
"next": "https://example.com/ap/actors/alice/inbox/filter?cursor=abc123",
"prev": "https://example.com/ap/actors/alice/inbox/filter?cursor=def456",
"orderedItems": [
{ /* Activity 1 */ },
{ /* Activity 2 */ }
],
"tree:relation": [
{
"@type": "tree:GreaterThanRelation",
"tree:path": { "@id": "as:published" },
"tree:value": "2026-01-28T10:00:00Z",
"tree:node": "https://example.com/ap/actors/alice/inbox/filter?cursor=abc123"
}
],
"totalItems": 42
}
Servers MUST provide as:next and as:prev links on OrderedCollectionPage responses for standard ActivityStreams pagination. This ensures compatibility with existing ActivityPub clients.
Servers MAY additionally include tree:relation entries to provide boundary values for TREE-aware clients. Each pagination relation uses three properties from the TREE vocabulary:
tree:value — the boundary value (e.g., a timestamp) that delimits the current pagetree:node — the URL to fetch to retrieve the next page of results beyond that boundarytree:path — the property used for ordering (typically as:published)For example, a tree:GreaterThanRelation with tree:value of "2026-01-28T10:00:00Z" and a tree:node URL means: “Fetching tree:node will return items with as:published greater than 2026-01-28T10:00:00Z.”
Pagination directions:
tree:GreaterThanRelation on as:published → next page contains older items (published after the boundary, in reverse chronological order)tree:LessThanRelation on as:published → next page contains newer items (published before the boundary)The filter endpoint MUST require the same authentication as the collection itself:
Servers MUST validate and sanitize filter requests. In particular:
tree:path MUST be restricted to allowed propertiestree:value MUST be restricted to allowed values/typesRecommended allowed tree:path values:
rdf:typeas:actoras:objectas:toas:ccas:publishedas:tagas:inReplyToas:attributedToFilter requests are potentially more expensive than regular GET requests. Servers SHOULD implement rate limiting.
This FEP explicitly defines no SPARQL interface. The supported operations are limited to the defined tree:Relation types.
Shows content lifecycle activities from followed actors, visible to public or followers.
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "rdf:type" },
"tree:value": [
{ "@id": "as:Create" },
{ "@id": "as:Update" },
{ "@id": "as:Delete" },
{ "@id": "as:Announce" }
]
},
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "as:actor" },
"tree:value": { "@id": "fep34c1:myFollowees" }
},
{
"@type": "tree:EqualToRelation",
"tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
"tree:value": [
{ "@id": "https://www.w3.org/ns/activitystreams#Public" },
{ "@id": "fep34c1:myAudience" }
]
}
],
"fep34c1:pageSize": 20
}
Shows activities where the actor is directly addressed via as:to or as:cc (public mentions only, excluding DMs).
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "rdf:type" },
"tree:value": [{ "@id": "as:Create" }]
},
{
"@type": "tree:EqualToRelation",
"tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
"tree:value": { "@id": "https://example.com/ap/actors/alice" }
},
{
"@type": "tree:EqualToRelation",
"tree:path": [{ "@id": "as:to" }, { "@id": "as:cc" }],
"tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
}
]
}
Shows activities not addressed to as:Public (neither in as:to nor as:cc). This includes direct messages, followers-only posts, and group messages.
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:EqualToRelation",
"tree:path": { "@id": "rdf:type" },
"tree:value": [{ "@id": "as:Create" }]
},
{
"@type": "tree:NotEqualToRelation",
"tree:path": { "@id": "as:to" },
"tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
},
{
"@type": "tree:NotEqualToRelation",
"tree:path": { "@id": "as:cc" },
"tree:value": { "@id": "https://www.w3.org/ns/activitystreams#Public" }
}
]
}
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#",
"xsd": "http://www.w3.org/2001/XMLSchema#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:GreaterThanRelation",
"tree:path": { "@id": "as:published" },
"tree:value": {
"@value": "2026-01-27T00:00:00Z",
"@type": "xsd:dateTime"
}
}
]
}
{
"@context": {
"tree": "https://w3id.org/tree#",
"fep34c1": "https://w3id.org/fep/34c1#",
"as": "https://www.w3.org/ns/activitystreams#"
},
"@type": "fep34c1:FilterRequest",
"tree:relation": [
{
"@type": "tree:PrefixRelation",
"tree:path": { "@id": "as:actor" },
"tree:value": "https://mastodon.social/"
}
]
}
Special placeholder values (fep34c1:myFollowees, fep34c1:myAudience) MUST be resolved at query time before evaluating the filter (see Section 4).
Allowed tree:path values SHOULD be restricted to a known set of ActivityStreams properties (see Security Considerations).
For multi-path with EqualToRelation, the semantics are UNION (match if any path matches). For NotEqualToRelation, the semantics are ALL (none of the paths may match).
tree:search is present in the collection405 Method Not Allowed if the server does not support filtersThis FEP is fully backwards compatible:
405 Method Not Allowed on POST requeststree:search property signals filter supportCC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.