git.squeep.com Git - akkoma/blob - docs/api/pleroma_api.md

   1 # Pleroma API
   2
   3 Requests that require it can be authenticated with [an OAuth token](https://tools.ietf.org/html/rfc6749), the `_pleroma_key` cookie, or [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
   4
   5 Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`.
   6
   7 ## `/api/pleroma/emoji`
   8 ### Lists the custom emoji on that server.
   9 * Method: `GET`
  10 * Authentication: not required
  11 * Params: none
  12 * Response: JSON
  13 * Example response:
  14 ```json
  15 {
  16   "girlpower": {
  17     "tags": [
  18       "Finmoji"
  19     ],
  20     "image_url": "/finmoji/128px/girlpower-128.png"
  21   },
  22   "education": {
  23     "tags": [
  24       "Finmoji"
  25     ],
  26     "image_url": "/finmoji/128px/education-128.png"
  27   },
  28   "finnishlove": {
  29     "tags": [
  30       "Finmoji"
  31     ],
  32     "image_url": "/finmoji/128px/finnishlove-128.png"
  33   }
  34 }
  35 ```
  36 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
  37
  38 ## `/api/pleroma/follow_import`
  39 ### Imports your follows, for example from a Mastodon CSV file.
  40 * Method: `POST`
  41 * Authentication: required
  42 * Params:
  43     * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow
  44 * Response: HTTP 200 on success, 500 on error
  45 * Note: Users that can't be followed are silently skipped.
  46
  47 ## `/api/pleroma/captcha`
  48 ### Get a new captcha
  49 * Method: `GET`
  50 * Authentication: not required
  51 * Params: none
  52 * Response: Provider specific JSON, the only guaranteed parameter is `type`
  53 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`
  54
  55 ## `/api/pleroma/delete_account`
  56 ### Delete an account
  57 * Method `POST`
  58 * Authentication: required
  59 * Params:
  60     * `password`: user's password
  61 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
  62 * Example response: `{"error": "Invalid password."}`
  63
  64 ## `/api/pleroma/disable_account`
  65 ### Disable an account
  66 * Method `POST`
  67 * Authentication: required
  68 * Params:
  69     * `password`: user's password
  70 * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
  71 * Example response: `{"error": "Invalid password."}`
  72
  73 ## `/api/account/register`
  74 ### Register a new user
  75 * Method `POST`
  76 * Authentication: not required
  77 * Params:
  78     * `nickname`
  79     * `fullname`
  80     * `bio`
  81     * `email`
  82     * `password`
  83     * `confirm`
  84     * `captcha_solution`: optional, contains provider-specific captcha solution,
  85     * `captcha_token`: optional, contains provider-specific captcha token
  86     * `token`: invite token required when the registrations aren't public.
  87 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
  88 * Example response:
  89 ```json
  90 {
  91         "background_image": null,
  92         "cover_photo": "https://pleroma.soykaf.com/images/banner.png",
  93         "created_at": "Tue Dec 18 16:55:56 +0000 2018",
  94         "default_scope": "public",
  95         "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.",
  96         "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.",
  97         "favourites_count": 0,
  98         "fields": [],
  99         "followers_count": 0,
 100         "following": false,
 101         "follows_you": false,
 102         "friends_count": 0,
 103         "id": 6,
 104         "is_local": true,
 105         "locked": false,
 106         "name": "lain",
 107         "name_html": "lain",
 108         "no_rich_text": false,
 109         "pleroma": {
 110                 "tags": []
 111         },
 112         "profile_image_url": "https://pleroma.soykaf.com/images/avi.png",
 113         "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png",
 114         "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png",
 115         "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png",
 116         "rights": {
 117                 "delete_others_notice": false
 118         },
 119         "screen_name": "lain",
 120         "statuses_count": 0,
 121         "statusnet_blocking": false,
 122         "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
 123 }
 124 ```
 125
 126 ## `/api/pleroma/admin/`…
 127 See [Admin-API](Admin-API.md)
 128
 129 ## `/api/pleroma/notifications/read`
 130 ### Mark a single notification as read
 131 * Method `POST`
 132 * Authentication: required
 133 * Params:
 134     * `id`: notification's id
 135 * Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
 136
 137 ## `/api/v1/pleroma/accounts/:id/subscribe`
 138 ### Subscribe to receive notifications for all statuses posted by a user
 139 * Method `POST`
 140 * Authentication: required
 141 * Params:
 142     * `id`: account id to subscribe to
 143 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 144 * Example response:
 145 ```json
 146 {
 147   "id": "abcdefg",
 148   "following": true,
 149   "followed_by": false,
 150   "blocking": false,
 151   "muting": false,
 152   "muting_notifications": false,
 153   "subscribing": true,
 154   "requested": false,
 155   "domain_blocking": false,
 156   "showing_reblogs": true,
 157   "endorsed": false
 158 }
 159 ```
 160
 161 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
 162 ### Unsubscribe to stop receiving notifications from user statuses
 163 * Method `POST`
 164 * Authentication: required
 165 * Params:
 166     * `id`: account id to unsubscribe from
 167 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 168 * Example response:
 169 ```json
 170 {
 171   "id": "abcdefg",
 172   "following": true,
 173   "followed_by": false,
 174   "blocking": false,
 175   "muting": false,
 176   "muting_notifications": false,
 177   "subscribing": false,
 178   "requested": false,
 179   "domain_blocking": false,
 180   "showing_reblogs": true,
 181   "endorsed": false
 182 }
 183 ```
 184
 185 ## `/api/v1/pleroma/accounts/:id/favourites`
 186 ### Returns favorites timeline of any user
 187 * Method `GET`
 188 * Authentication: not required
 189 * Params:
 190     * `id`: the id of the account for whom to return results
 191     * `limit`: optional, the number of records to retrieve
 192     * `since_id`: optional, returns results that are more recent than the specified id
 193     * `max_id`: optional, returns results that are older than the specified id
 194 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
 195 * Example response:
 196 ```json
 197 [
 198   {
 199     "account": {
 200       "id": "9hptFmUF3ztxYh3Svg",
 201       "url": "https://pleroma.example.org/users/nick2",
 202       "username": "nick2",
 203       ...
 204     },
 205     "application": {"name": "Web", "website": null},
 206     "bookmarked": false,
 207     "card": null,
 208     "content": "This is :moominmamma: note 0",
 209     "created_at": "2019-04-15T15:42:15.000Z",
 210     "emojis": [],
 211     "favourited": false,
 212     "favourites_count": 1,
 213     "id": "9hptFmVJ02khbzYJaS",
 214     "in_reply_to_account_id": null,
 215     "in_reply_to_id": null,
 216     "language": null,
 217     "media_attachments": [],
 218     "mentions": [],
 219     "muted": false,
 220     "pinned": false,
 221     "pleroma": {
 222       "content": {"text/plain": "This is :moominmamma: note 0"},
 223       "conversation_id": 13679,
 224       "local": true,
 225       "spoiler_text": {"text/plain": "2hu"}
 226     },
 227     "reblog": null,
 228     "reblogged": false,
 229     "reblogs_count": 0,
 230     "replies_count": 0,
 231     "sensitive": false,
 232     "spoiler_text": "2hu",
 233     "tags": [{"name": "2hu", "url": "/tag/2hu"}],
 234     "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
 235     "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
 236     "visibility": "public"
 237   }
 238 ]
 239 ```
 240
 241 ## `/api/v1/pleroma/accounts/update_*`
 242 ### Set and clear account avatar, banner, and background
 243
 244 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
 245 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
 246 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
 247
 248 ## `/api/v1/pleroma/accounts/confirmation_resend`
 249 ### Resend confirmation email
 250 * Method `POST`
 251 * Params:
 252     * `email`: email of that needs to be verified
 253 * Authentication: not required
 254 * Response: 204 No Content
 255
 256 ## `/api/v1/pleroma/mascot`
 257 ### Gets user mascot image
 258 * Method `GET`
 259 * Authentication: required
 260
 261 * Response: JSON. Returns a mastodon media attachment entity.
 262 * Example response:
 263 ```json
 264 {
 265     "id": "abcdefg",
 266     "url": "https://pleroma.example.org/media/abcdefg.png",
 267     "type": "image",
 268     "pleroma": {
 269         "mime_type": "image/png"
 270     }
 271 }
 272 ```
 273
 274 ### Updates user mascot image
 275 * Method `PUT`
 276 * Authentication: required
 277 * Params:
 278     * `image`: Multipart image
 279 * Response: JSON. Returns a mastodon media attachment entity
 280   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
 281 * Example response:
 282 ```json
 283 {
 284     "id": "abcdefg",
 285     "url": "https://pleroma.example.org/media/abcdefg.png",
 286     "type": "image",
 287     "pleroma": {
 288         "mime_type": "image/png"
 289     }
 290 }
 291 ```
 292 * Note: Behaves exactly the same as `POST /api/v1/upload`.
 293   Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
 294
 295 ## `/api/pleroma/notification_settings`
 296 ### Updates user notification settings
 297 * Method `PUT`
 298 * Authentication: required
 299 * Params:
 300     * `followers`: BOOLEAN field, receives notifications from followers
 301     * `follows`: BOOLEAN field, receives notifications from people the user follows
 302     * `remote`: BOOLEAN field, receives notifications from people on remote instances
 303     * `local`: BOOLEAN field, receives notifications from people on the local instance
 304 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
 305
 306 ## `/api/pleroma/healthcheck`
 307 ### Healthcheck endpoint with additional system data.
 308 * Method `GET`
 309 * Authentication: not required
 310 * Params: none
 311 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 312 * Example response:
 313 ```json
 314 {
 315   "pool_size": 0, # database connection pool
 316   "active": 0, # active processes
 317   "idle": 0, # idle processes
 318   "memory_used": 0.00, # Memory used
 319   "healthy": true # Instance state
 320 }
 321 ```
 322
 323 # Pleroma Conversations
 324
 325 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
 326
 327 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
 328 2. Pleroma Conversations statuses can be requested by Conversation id.
 329 3. Pleroma Conversations can be replied to.
 330
 331 Conversations have the additional field "recipients" under the "pleroma" key. This holds a list of all the accounts that will receive a message in this conversation.
 332
 333 The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation.
 334
 335
 336 ## `GET /api/v1/pleroma/conversations/:id/statuses`
 337 ### Timeline for a given conversation
 338 * Method `GET`
 339 * Authentication: required
 340 * Params: Like other timelines
 341 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 342
 343 ## `GET /api/v1/pleroma/conversations/:id`
 344 ### The conversation with the given ID.
 345 * Method `GET`
 346 * Authentication: required
 347 * Params: None
 348 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 349
 350 ## `PATCH /api/v1/pleroma/conversations/:id`
 351 ### Update a conversation. Used to change the set of recipients.
 352 * Method `PATCH`
 353 * Authentication: required
 354 * Params:
 355     * `recipients`: A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though.
 356 * Response: JSON, statuses (200 - healthy, 503 unhealthy)