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/mascot`
 242 ### Gets user mascot image
 243 * Method `GET`
 244 * Authentication: required
 245
 246 * Response: JSON. Returns a mastodon media attachment entity.
 247 * Example response:
 248 ```json
 249 {
 250     "id": "abcdefg",
 251     "url": "https://pleroma.example.org/media/abcdefg.png",
 252     "type": "image",
 253     "pleroma": {
 254         "mime_type": "image/png"
 255     }
 256 }
 257 ```
 258
 259 ### Updates user mascot image
 260 * Method `PUT`
 261 * Authentication: required
 262 * Params:
 263     * `image`: Multipart image
 264 * Response: JSON. Returns a mastodon media attachment entity
 265   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
 266 * Example response:
 267 ```json
 268 {
 269     "id": "abcdefg",
 270     "url": "https://pleroma.example.org/media/abcdefg.png",
 271     "type": "image",
 272     "pleroma": {
 273         "mime_type": "image/png"
 274     }
 275 }
 276 ```
 277 * Note: Behaves exactly the same as `POST /api/v1/upload`.
 278   Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
 279
 280 ## `/api/pleroma/notification_settings`
 281 ### Updates user notification settings
 282 * Method `PUT`
 283 * Authentication: required
 284 * Params:
 285     * `followers`: BOOLEAN field, receives notifications from followers
 286     * `follows`: BOOLEAN field, receives notifications from people the user follows
 287     * `remote`: BOOLEAN field, receives notifications from people on remote instances
 288     * `local`: BOOLEAN field, receives notifications from people on the local instance
 289 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
 290
 291 ## `/api/pleroma/healthcheck`
 292 ### Healthcheck endpoint with additional system data.
 293 * Method `GET`
 294 * Authentication: not required
 295 * Params: none
 296 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 297 * Example response:
 298 ```json
 299 {
 300   "pool_size": 0, # database connection pool
 301   "active": 0, # active processes
 302   "idle": 0, # idle processes
 303   "memory_used": 0.00, # Memory used
 304   "healthy": true # Instance state
 305 }
 306 ```