> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Lemmy

> What a Nephia Watch on Lemmy captures, and what arrives in each event.

## 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.

| Criterion   | Values                                            | Default       |
| ----------- | ------------------------------------------------- | ------------- |
| `instance`  | a hostname                                        | `lemmy.world` |
| `query`     | search text                                       | —             |
| `community` | `name@host`, or a bare `name` local to `instance` | —             |
| `types`     | `posts`, `comments`, `all`                        | `posts`       |

**`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](/webhooks).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/lemmy/watches \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "instance": "programming.dev",
    "query": "duckdb",
    "types": "all",
    "refresh_interval_seconds": 300,
    "webhook_url": "https://example.com/hooks/nephia"
  }'
```

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.