Lemmy-compatible forum API

Catodon answers three read-only requests in the shape of Lemmy's API v3 (Lemmy 0.19), so that forum directories and crawlers written for Lemmy can find the public forums of a Catodon server. "Forum" is Catodon's word for what Lemmy calls a community; the paths and field names below keep Lemmy's spelling.

This page is for developers of such tools and for administrators.

It is a small part of Lemmy's API, not the whole of it. There is no sign-in, no posts or comments, nothing to write, no /api/v3/federated_instances and nothing under /api/v4. Catodon keeps saying catodon in NodeInfo and in version, so a tool can tell it from a Lemmy server. Tools that only accept servers whose NodeInfo name is lemmy (Lemmy Explorer, for one) will not index it.

Which forums are listed

A forum appears only if all of these hold:

• it lives on this server (forums followed from other servers are never listed);
• its visibility is public, federated and listed in discovery, the value public. None of the other seven visibility values appears: not unlisted, not private, not private-but-discoverable, and none of the local-only ones;
• it is not suspended and not deleted;
• List in forum directories is on in the forum's settings.

The list, the lookup and the forum count of the site all use this one rule. A forum outside it answers exactly as a name that does not exist.

Settings

• The whole server. On by default. Control Panel > Federation > Policy > Lemmy-compatible forum API (the meta setting enableLemmyCompatForumApi). While off, /api/v3/community/list and /api/v3/community answer 404 as any unknown API path does, and the site reports 0 forums. /api/v3/site itself keeps answering, because PieFed reads custom emojis from it.
• One forum. On by default. List in forum directories in the forum's edit dialog (listedInDirectories in forums/create and forums/update). Turning it off removes the forum from this API only; it changes nothing about who can see or follow the forum.

Counts are kept for five minutes, and answers may be cached for five minutes by whoever asks, so a change can take that long to show.

GET /api/v3/community/list

Every order ends on the forum's id, so two pages never share a forum. The page after the last one answers {"communities":[]}.

Errors are HTTP 400 with Lemmy's body:

curl 'https://example.com/api/v3/community/list?type_=Local&sort=Old&limit=50&page=1&show_nsfw=true'

GET /api/v3/community?name=...

One forum, by its name (name or name@this-server, in any letter case). The answer has Lemmy's four parts: community_view (the same object as a list item), site, moderators and discussion_languages.

A forum that does not exist, one that is not listed, a name on another server, and any request with id all answer HTTP 404 with {"error":"couldnt_find_community"}.

GET /api/v3/site

The server's name, description, icon and banner; whether registration is open (registration_mode), whether federation, captcha and e-mail verification are on; the custom emojis; and counts: local accounts, local posts, forums listed by this API, and accounts active in the last day, week, month and half year. The account and post counts are the ones NodeInfo reports, from the same hourly statistics, so a brand-new server shows 0 for up to twenty minutes.

Headers

The list and the lookup send Cache-Control: public, max-age=300 and Access-Control-Allow-Origin: *, so a page on another site can read them from a browser.

Fields

Posts and replies that are not readable by everybody (to followers only, or to named people) are not counted, nor are their authors.

Approximated, added or left out

Everything that is not what Lemmy would send:

• community.id, counts.community_id. Lemmy's ids are numbers and Catodon's are text. These carry a number made from Catodon's id: always the same for the same forum, positive, within 31 bits. It cannot be used to look a forum up, and two forums could in principle share one. Use actor_id to tell forums apart.
• instance_id, site.id, local_site.id, site_id. Always 1, as on a Lemmy server for itself.
• Active users count people who posted or replied. Lemmy also counts people who only voted.
• community.updated is left out.
• counts.catodon_last_posted_at is added: the time of the forum's most recent top-level post, or null. Lemmy has no such field.
• subscribed is always "NotSubscribed", and blocked and banned_from_community always false: nobody is signed in.
• moderators in the lookup is an empty list.
• discussion_languages in the lookup holds Lemmy's numbers for the languages the forum states, at most three, and is empty when it states none, which Lemmy's own clients read as every language. Lemmy's table has no row for some languages (Cantonese and Asturian among them), which are left out, so a forum that states only those has an empty list too. The numbers are the rows of all_languages in /api/v3/site.
• site in the lookup and in /api/v3/site: public_key is an empty string; sidebar, published, updated and last_refreshed_at are left out.
• /api/v3/site: local_site_rate_limit is left out, and local_site has only id, site_id, name (the server's name; not a Lemmy field, kept from before), site_setup, enable_nsfw, community_creation_admin_only (always true: administrators create forums), require_email_verification, federation_enabled, captcha_enabled and registration_mode. counts.posts is every local post, replies included, and counts.comments is 0. all_languages is Lemmy's table of 184 languages, numbers, codes and names as Lemmy has them (0 is und, English is 37), and discussion_languages lists every number in it: the server takes every language, and a forum's own setting is what narrows it. taglines and blocked_urls are empty lists. version is catodon.