Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

API v4 Upgrade Guide

This document outlines the main changes between API v3 (Lemmy 0.19) and API v4 (Lemmy 1.0). You can use the following resources to adapt the new API:

Note that this document only covers changes to existing features, not new features. If any breaking changes are missing, please make a pull request to this file. If you have any questions, use the development chat on matrix or /c/lemmy-support.

Rename account endpoints

Various endpoints have been renamed, especially those under /api/v3/user have been moved to /api/v4/account/auth.

  • /api/v3/user/register to /api/v4/account/auth/register
  • /api/v3/user/login to /api/v4/account/auth/login
  • /api/v3/user/logout to /api/v4/account/auth/logout
  • …
  • /api/v4/site doesn’t have my_user anymore, this is now available at GET /api/v4/account

https://github.com/LemmyNet/lemmy/pull/5216

Combined endpoints

There are various places in the UI where different types of data are shown together, for example posts and comments in the user profile. Until 0.19 these were queried separately, to display the (last 20 posts) and (last 20 comments). For 1.0 Dessalines implemented combined queries, so that the new endpoint /api/v4/person/content returns the last 20 (posts and comments). See the issue and linked pull requests for more details.

The combined endpoints are:

Image endpoints

Uploading or deleting avatars, icons and banners is done through separate endpoints now. With this change it is possible to disable image uploads, while still allowing changes to avatars etc.

The endpoints for image upload and proxying have been moved to GET /api/v4/image/{filename} and GET /api/v4/image/proxy respectively.

https://github.com/LemmyNet/lemmy/pull/5260

Cursor Pagination

Instead of a page parameter, API v4 uses cursors for pagination. To make it simple, a cursor is a string which encodes the id of the last item on the current page. When going to the next page, the client sends the next_page cursor as page_cursor, and the API sends back items which come after this one. This way users don’t lose their place in the feed, but continue exactly where they left off.

Notifications Rewrite

With API v3 notification functionality was spread across various different endpoints. Now all is available under a single endpoint /api/v4/account/notification/list. Notifications also include modlog entries affecting the current user.

Post Time Range Filter

The previous sorts TopHour, TopDay etc are gone and replaced Top sort. Instead there is now a separate parameter time_range_seconds which accepts arbitrary time values and works with all sort types.

Other Breaking Changes