Skip to main content

​
The item

Lemmy’s Watch emits a LemmyPost, and type says which kind it is: post or comment. Both halves ride one entity, exactly as Hacker News’ items do — listening wants both, they share every field that matters, and the discrimination belongs in a field rather than in the envelope key. title is the post’s own title on a post, and the parent post’s title on a comment. That is what lets a comment row say what it is a comment on without a second request. id is kind-prefixed — post-51094842, comment-25176549 — because a post and a comment on one instance share a numeric id space between them. url is the discussion on the instance being read, not the apId. A mention on Lemmy is the thread you can reply in; apId points at the originating server, which on a federated post is usually one you have no account on. community.qualifiedName is derived from the community’s actor id, so a community that lives on lemmy.ml reads as technology@lemmy.ml even when you read it through lemmy.world.

​
Coverage

A Watch requires query and/or community. A term with no community is the brand search this Source exists for; a community with no term is “everything new in that room”. Neither is “everything on Lemmy”, which is what the rule refuses. types: "all" costs two credits per tick. Lemmy’s search takes one item type per request, so asking for posts and comments is genuinely two calls. posts is the default because it is the cheaper honest one, not because comments matter less.

​
What one instance can see

A Lemmy server shows you its federated view: the communities its own users subscribe to, and the posts that have reached it. A large instance sees a great deal; a small one sees its own corner. A community nobody on that server follows will not appear in its search, however busy it is elsewhere. If a conversation about you lives in one particular community, watch the instance that community lives on. One term only. Lemmy’s search runs through Postgres full-text search, which ANDs its terms and treats a literal OR as another word — the same behaviour Hacker News’ and Bluesky’s searches have. A quoted phrase is honoured, so match: "word" asks for it upstream rather than filtering afterwards. Interval: 120–86400 seconds. Cap: 20 active Watches per Account.

​
What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit lemmy_post.created with the full item. webhook_url is optional — without it the Watch still records every match, readable through GET /v1/lemmy/watches/{id}/events. See Webhooks.
Lemmy’s search offers no incremental window, so each tick reads the newest page and dedupes by id. Removed and deleted rows are dropped: Lemmy keeps them in results with the body blanked, and a webhook whose body is empty and whose subject no longer exists is not news.

​
Errors

An unreachable or misbehaving instance is 503 and is not charged; the Watch reports it in its activity, readable through GET /v1/lemmy/watches/{id}/activity. instance is validated as a hostname when the Watch is created, and the address it resolves to is checked again on every request — a host that resolves to a private or link-local address is refused.