- **Interactivelybrowse the WebSocket API.** Browse the *Channels*, check out the responses and examples (tailor the *PUBLISH* requests to suit with your favorite WebSocket API client). For testing purposes, either [set up your own server](https://lemmy.ml/docs/en/administration/administration.html) or use the Enterprise server (*ws://enterprise.lemmy.ml/api/v2/ws*)
- **[Openand save](asyncapi.yaml) this specification file** and use it with the various [AsyncAPI tools](https://www.asyncapi.com/docs/community/tooling) (perhaps to generate code or documentation).
Lemmy also has an HTTP API. The Websocket and HTTP API are almost identical:
- WebSocket API needs `let send = { op: userOperation[op], data: form}` as shown below
- HTTP API requires the form at the top level and an HTTP operation (GET, PUT or POST) and endpoint. For example:`PUT /comment`. For more information, see [http.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts)
Register a user on the Lemmy server. If Captcha is enabled on the server, obtain those details by using **GetCaptcha** (*before* attempting to register)
name:Request to list all a user's private messages
payload:
type:object
properties:
op:
type:string
pattern:'^GetPrivateMessages$'
default:'GetPrivateMessages'
data:
type:object
properties:
unread_only:
$ref:'#/components/schemas/unread_only'
page:
$ref:'#/components/schemas/page'
limit:
$ref:'#/components/schemas/limit'
auth:
$ref:'#/components/schemas/authStringSchema'
privateMessagesResponse:
name:List of all a user's private messages
payload:
type:object
properties:
data:
type:object
properties:
private_messages:
type:array
uniqueItems:true
items:
$ref:'#/components/schemas/private_message_view'
op:
type:string
pattern:'^GetPrivateMessages$'
default:'GetPrivateMessages'
createPrivateMessageRequest:
name:|-
Request to create a private message
payload:
type:object
properties:
op:
type:string
pattern:'^CreatePrivateMessage$'
default:'CreatePrivateMessage'
data:
type:object
properties:
content:
$ref:'#/components/schemas/content'
recipient_id:
$ref:'#/components/schemas/recipient'
auth:
$ref:'#/components/schemas/authStringSchema'
createPrivateMessageResponse:
name:|-
Confirmation of the sent private message
payload:
type:object
properties:
op:
type:string
pattern:'^CreatePrivateMessage$'
default:'CreatePrivateMessage'
data:
type:object
properties:
private_message_view:
$ref:'#/components/schemas/private_message_view'
editPrivateMessageRequest:
name:Request to edit a private message
payload:
type:object
properties:
op:
type:string
pattern:'^EditPrivateMessage$'
default:'EditPrivateMessage'
data:
type:object
properties:
private_message_id:
$ref:'#/components/schemas/private_message_id'
content:
$ref:'#/components/schemas/content'
auth:
$ref:'#/components/schemas/authStringSchema'
editPrivateMessageResponse:
name:Confirmation of the edited private message
payload:
type:object
properties:
data:
type:object
properties:
private_message_view:
$ref:'#/components/schemas/private_message_view'
op:
type:string
pattern:'^EditPrivateMessage$'
default:'EditPrivateMessage'
deletePrivateMessageRequest:
name:Request to delete a private message
payload:
type:object
properties:
op:
type:string
pattern:'^DeletePrivateMessage$'
default:'DeletePrivateMessage'
data:
type:object
properties:
private_message_id:
$ref:'#/components/schemas/private_message_id'
deleted:
$ref:'#/components/schemas/deleted'
auth:
$ref:'#/components/schemas/authStringSchema'
deletePrivateMessageResponse:
name:Confirmation of the deleted private message
payload:
type:object
properties:
data:
type:object
properties:
private_message_view:
$ref:'#/components/schemas/private_message_view'
op:
type:string
pattern:'^DeletePrivateMessage$'
default:'DeletePrivateMessage'
markPrivateMessageRequest:
name:Request to mark a private message as read
payload:
type:object
properties:
op:
type:string
pattern:'^MarkPrivateMessageAsRead$'
default:'MarkPrivateMessageAsRead'
data:
type:object
properties:
private_message_id:
$ref:'#/components/schemas/private_message_id'
read:
$ref:'#/components/schemas/read'
auth:
$ref:'#/components/schemas/authStringSchema'
markPrivateMessageResponse:
name:'Confirmation that the private message has been marked as *read*'
payload:
type:object
properties:
data:
type:object
properties:
private_message_view:
$ref:'#/components/schemas/private_message_view'
op:
type:string
pattern:'^MarkPrivateMessageAsRead$'
default:'MarkPrivateMessageAsRead'
markAllReadRequest:
name:Request to mark all user replies and mentions as read
payload:
type:object
properties:
op:
type:string
pattern:'^MarkAllAsRead$'
default:'MarkAllAsRead'
data:
type:object
properties:
auth:
$ref:'#/components/schemas/authStringSchema'
markAllReadResponse:
name:'Confirmation that all replies and mentions have been marked as *read*'
payload:
type:object
properties:
data:
type:object
properties:
replies:
$ref:'#/components/schemas/replies'
op:
type:string
pattern:'^MarkAllAsRead$'
default:'MarkAllAsRead'
deleteAccountRequest:
name:Request to delete a user account
payload:
type:object
properties:
op:
type:string
pattern:'^DeleteAccount$'
default:'DeleteAccount'
data:
type:object
properties:
password:
$ref:'#/components/schemas/passwordRequired'
auth:
$ref:'#/components/schemas/authStringSchema'
deleteAccountResponse:
name:Confirmation that the account has been deleted
payload:
type:object
properties:
data:
type:object
properties:
jwt:
$ref:'#/components/schemas/authStringSchema'
op:
type:string
pattern:'^DeleteAccount$'
default:'DeleteAccount'
addAdminRequest:
name:Request to grant admin privileges to a user
payload:
type:object
properties:
op:
type:string
pattern:'^AddAdmin$'
default:'AddAdmin'
data:
type:object
properties:
user_id:
$ref:'#/components/schemas/user_id'
added:
description:Forthcoming...
type:boolean
example:true
auth:
$ref:'#/components/schemas/authStringSchema'
addAdminResponse:
name:Confirmation that the user has been given admin privileges
payload:
type:object
properties:
data:
type:object
properties:
admins:
$ref:'#/components/schemas/user'
op:
type:string
pattern:'^AddAdmin$'
default:'AddAdmin'
banUserRequest:
name:Request to ban a user
payload:
type:object
properties:
op:
type:string
pattern:'^BanUser$'
default:'BanUser'
data:
type:object
properties:
user_id:
$ref:'#/components/schemas/user_id'
ban:
description:|-
- If set to *true*, ban the user
- If set to *false*, do not ban them (use in combination with `remove_data` to restore comments, posts, and communities that were previously removed with `banUser`)
type:boolean
example:true
remove_data:
description:|-
- If set to *true*, also delete their comments, posts, and communities
- If set *false*, *restore* their comments, posts, and communities
type:boolean
example:false
reason:
description:Forthcoming...
type:string
example:'Breach of terms and conditions'
expires:
description:Forthcoming...
type:integer
format:int64
auth:
$ref:'#/components/schemas/authStringSchema'
banUserResponse:
name:Confirmation that the user has been banned
payload:
type:object
properties:
data:
type:object
properties:
user:
$ref:'#/components/schemas/user'
banned:
description:Forthcoming...
type:boolean
example:true
op:
type:string
pattern:'^BanUser$'
default:'BanUser'
userJoinRequest:
name:Request to join (something?)
payload:
type:object
properties:
op:
type:string
pattern:'^UserJoin$'
default:'UserJoin'
data:
type:object
properties:
auth:
$ref:'#/components/schemas/authStringSchema'
userJoinResponse:
name:Forthcoming...
payload:
type:object
properties:
data:
type:object
properties:
joined:
description:Forthcoming...
type:boolean
example:true
op:
type:string
pattern:'^UserJoin$'
default:'UserJoin'
getReportCountRequest:
name:Request to return report count numbers
payload:
type:object
properties:
op:
type:string
pattern:'^GetReportCount$'
default:'GetReportCount'
data:
type:object
properties:
community:
$ref:'#/components/schemas/community_id'
auth:
$ref:'#/components/schemas/authStringSchema'
getReportCountResponse:
name:Report on the number of posts and comments
payload:
type:object
properties:
data:
type:object
properties:
comment_reports:
description:The number of comments in the community/communities
type:integer
format:int64
example:123
community:
$ref:'#/components/schemas/community_id'
post_reports:
description:The number of posts in the community/communities
type:integer
format:int64
example:23
op:
type:string
pattern:'^GetReportCount$'
default:'GetReportCount'
getCategoriesRequest:
name:Request to list categories on the Lemmy server
payload:
type:object
properties:
op:
type:string
pattern:'^ListCategories$'
default:'ListCategories'
data:
type:object
getCategoriesResponse:
name:Returns list of categories on the server
payload:
type:object
properties:
data:
type:object
properties:
categories:
type:array
items:
properties:
id:
$ref:'#/components/schemas/category_id'
name:
description:The category name
type:string
example:'Politics'
op:
type:string
pattern:'^ListCategories$'
default:'ListCategories'
searchRequest:
name:Request to find information on the Lemmy server
payload:
type:object
properties:
op:
type:string
pattern:'^Search$'
default:'Search'
data:
type:object
properties:
q:
description:The text to search for on the Lemmy server
type:string
example:'lemmy'
type_:
$ref:'#/components/schemas/type_'
community_id:
$ref:'#/components/schemas/community_id'
community_name:
$ref:'#/components/schemas/community_name'
sort:
$ref:'#/components/schemas/sort'
page:
$ref:'#/components/schemas/page'
limit:
$ref:'#/components/schemas/limit'
auth:
$ref:'#/components/schemas/authStringSchema'
searchResponse:
name:The search results
payload:
type:object
properties:
data:
type:object
properties:
communities:
type:array
items:
properties:
community:
$ref:'#/components/schemas/community'
posts:
$ref:'#/components/schemas/replies'
type_:
$ref:'#/components/schemas/type_'
users:
type:array
items:
properties:
user:
$ref:'#/components/schemas/user'
comments:
$ref:'#/components/schemas/comments'
op:
type:string
pattern:'^Search$'
default:'Search'
getModLogRequest:
name:Forthcoming...
payload:
type:object
properties:
op:
type:string
pattern:'^GetModLog$'
default:'GetModLog'
data:
type:object
properties:
mod_user_id:
$ref:'#/components/schemas/user_id'
community_id:
$ref:'#/components/schemas/community_id'
page:
$ref:'#/components/schemas/page'
limit:
$ref:'#/components/schemas/limit'
createSiteRequest:
name:Create Lemmy site on a server
payload:
type:object
properties:
op:
type:string
pattern:'^CreateSite$'
default:'CreateSite'
data:
$ref:'#/components/schemas/site_properties'
editSiteRequest:
name:Request to edit Lemmy site details
payload:
type:object
properties:
op:
type:string
pattern:'^EditSite$'
default:'EditSite'
data:
$ref:'#/components/schemas/site_properties'
editSiteResponse:
name:The response after a site edit
payload:
type:object
properties:
op:
type:string
pattern:'^EditSite$'
default:'EditSite'
data:
type:object
properties:
site_view:
$ref:'#/components/schemas/site_view'
getSiteRequest:
name:Request to return Lemmy site details
payload:
type:object
properties:
op:
type:string
pattern:'^GetSite$'
default:'GetSite'
data:
type:object
properties:
auth:
$ref:'#/components/schemas/authStringSchema'
getSiteResponse:
name:Returns Lemmy site details
payload:
type:object
properties:
data:
type:object
properties:
site_view:
counts:
$ref:'#/components/schemas/site_counts'
site:
$ref:'#/components/schemas/site'
creator:
$ref:'#/components/schemas/creator'
federated_instances:
$ref:'#/components/schemas/federated_instances'
my_user:
$ref:'#/components/schemas/my_user'
version:
$ref:'#/components/schemas/version'
banned:
$ref:'#/components/schemas/banned_list'
online:
$ref:'#/components/schemas/online'
admins:
type:array
uniqueItems:true
items:
properties:
counts:
type:object
properties:
comment_score:
description:Forthcoming...
type:number
example:8
user_id:
description:Forthcoming...
type:number
example:2
post_score:
description:Forthcoming...
type:number
example:13
id:
description:Forthcoming...
type:number
example:1
post_count:
description:Forthcoming...
type:number
example:10
comment_count:
description:Forthcoming...
type:number
example:9
user:
$ref:'#/components/schemas/creator'
op:
type:string
pattern:'^GetSite$'
default:'GetSite'
transferSiteRequest:
name:Request to transfer ownership of the site
payload:
type:object
properties:
op:
type:string
pattern:'^TransferSite$'
default:'TransferSite'
data:
type:object
properties:
user_id:
$ref:'#/components/schemas/user_id'
auth:
$ref:'#/components/schemas/authStringSchema'
transferSiteResponse:
name:Request to transfer ownership of the site
payload:
type:object
properties:
op:
type:string
pattern:'^TransferSite$'
default:'TransferSite'
data:
type:object
properties:
site_view:
$ref:'#/components/schemas/site_view'
admins:
description:The list of administrators for this site
type:array
items:
properties:
user:
$ref:'#/components/schemas/user'
counts:
$ref:'#/components/schemas/counts'
banned:
$ref:'#/components/schemas/banned_list'
online:
$ref:'#/components/schemas/online'
version:
$ref:'#/components/schemas/version'
my_user:
$ref:'#/components/schemas/my_user'
federated_instances:
$ref:'#/components/schemas/federated_instances'
getSiteConfigRequest:
name:Request the configuration data for a Lemmy server
payload:
type:object
properties:
op:
type:string
pattern:'^GetSiteConfig$'
default:'^GetSiteConfig$'
data:
type:object
properties:
auth:
$ref:'#/components/schemas/authStringSchema'
getSiteConfigResponse:
name:Returns the configuration data for a Lemmy server
payload:
type:object
properties:
op:
type:string
pattern:'^GetSiteConfig$'
default:'^GetSiteConfig$'
data:
type:object
properties:
config_hjson:
$ref:'#/components/schemas/config_hjson'
saveSiteConfigRequest:
name:Request to send a configuration data file for a Lemmy server
payload:
type:object
properties:
op:
type:string
pattern:'^SaveSiteConfig$'
default:'^SaveSiteConfig$'
data:
type:object
properties:
config_hjson:
$ref:'#/components/schemas/config_hjson'
auth:
$ref:'#/components/schemas/authStringSchema'
saveSiteConfigResponse:
name:Returns the configuration data for a Lemmy server
description:'A self-written description of the user'
example:'I am a watercolour artist. I am happy to share the paintings I am working on, give and receive critiques, and post resources such as tutorials.'
'category_id':
type:number
minimum:1
description:|-
Matches the dropdown list in a community's *Category* setting. 1 = the topmost element, 2 = the second element, and so on.
example:15
'comment':
type:object
properties:
creator_id:
$ref:'#/components/schemas/creator_id'
content:
$ref:'#/components/schemas/content'
id:
description:Forthcoming...
type:number
example:312
read:
description:Is *true* if the author of the original post has read the comment
format:int32# Or int64? It's stated as both in different parts of the API docs
description:The id number for a community
'community_name':
description:The name of a community
type:string
Example:'The Default Community'
'config_hjson':
description:The configuration data for a Lemmy server (in JSON format)
type:string
example:|-
{\n # for more info about the config, check out the documentation\n # https://lemmy.ml/docs/administration_configuration.html\n\n setup:{\n # username for the admin user\n admin_username:\"lemmy\"\n # password for the admin user\n admin_password: \"lemmy\"\n # name of the site (can be changed later)\n site_name: \"lemmy-test\"\n }\n\n # the domain name of your instance (eg \"lemmy.ml\")\n hostname: \"localhost\"\n # address where lemmy should listen for incoming requests\n bind: \"0.0.0.0\"\n # port where lemmy should listen for incoming requests\n port: 8536\n # json web token for authorization between server and client\n jwt_secret: \"changeme\"\n # settings related to the postgresql database\n database: {\n # name of the postgres database for lemmy\n database: \"lemmy\"\n # username to connect to postgres\n user: \"lemmy\"\n # password to connect to postgres\n password: \"password\"\n # host where postgres is running\n host: \"postgres\"\n }\n# # optional: email sending configuration\n# email: {\n# # hostname and port of the smtp server\n# smtp_server: \"aspmx.l.google.com\"\n# # login name for smtp server\n# smtp_login: \"lemmmy@glemmy.com\"\n# # password to login to the smtp server\n# smtp_password: \"lemom\"\n# # address to send emails from, eg \"noreply@your-instance.com\"\n# smtp_from_address: \"noreply@lemmy.com\"\n# # whether or not smtp connections should use tls\n# use_tls: true\n# }\n}\n\n"
description:'Set to *true* if this commmunity, post or comment is deemed [NSFW](https://en.wikipedia.org/wiki/Not_safe_for_work) (hence invisble to users who have the NSFW option selected in their profile'
