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/v1/pleroma/flavour/:flavour`
 130 * Method `POST`
 131 * Authentication: required
 132 * Response: JSON string. Returns the user flavour or the default one on success, otherwise returns `{"error": "error_msg"}`
 133 * Example response: "glitch"
 134 * Note: This is intended to be used only by mastofe
 135
 136 ## `/api/v1/pleroma/flavour`
 137 * Method `GET`
 138 * Authentication: required
 139 * Response: JSON string. Returns the user flavour or the default one.
 140 * Example response: "glitch"
 141 * Note: This is intended to be used only by mastofe
 142
 143 ## `/api/pleroma/notifications/read`
 144 ### Mark a single notification as read
 145 * Method `POST`
 146 * Authentication: required
 147 * Params:
 148     * `id`: notification's id
 149 * Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
 150
 151 ## `/api/v1/pleroma/accounts/:id/subscribe`
 152 ### Subscribe to receive notifications for all statuses posted by a user
 153 * Method `POST`
 154 * Authentication: required
 155 * Params:
 156     * `id`: account id to subscribe to
 157 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 158 * Example response:
 159 ```json
 160 {
 161   "id": "abcdefg",
 162   "following": true,
 163   "followed_by": false,
 164   "blocking": false,
 165   "muting": false,
 166   "muting_notifications": false,
 167   "subscribing": true,
 168   "requested": false,
 169   "domain_blocking": false,
 170   "showing_reblogs": true,
 171   "endorsed": false
 172 }
 173 ```
 174
 175 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
 176 ### Unsubscribe to stop receiving notifications from user statuses
 177 * Method `POST`
 178 * Authentication: required
 179 * Params:
 180     * `id`: account id to unsubscribe from
 181 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 182 * Example response:
 183 ```json
 184 {
 185   "id": "abcdefg",
 186   "following": true,
 187   "followed_by": false,
 188   "blocking": false,
 189   "muting": false,
 190   "muting_notifications": false,
 191   "subscribing": false,
 192   "requested": false,
 193   "domain_blocking": false,
 194   "showing_reblogs": true,
 195   "endorsed": false
 196 }
 197 ```
 198
 199 ## `/api/v1/pleroma/accounts/:id/favourites`
 200 ### Returns favorites timeline of any user
 201 * Method `GET`
 202 * Authentication: not required
 203 * Params:
 204     * `id`: the id of the account for whom to return results
 205     * `limit`: optional, the number of records to retrieve
 206     * `since_id`: optional, returns results that are more recent than the specified id
 207     * `max_id`: optional, returns results that are older than the specified id
 208 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
 209 * Example response:
 210 ```json
 211 [
 212   {
 213     "account": {
 214       "id": "9hptFmUF3ztxYh3Svg",
 215       "url": "https://pleroma.example.org/users/nick2",
 216       "username": "nick2",
 217       ...
 218     },
 219     "application": {"name": "Web", "website": null},
 220     "bookmarked": false,
 221     "card": null,
 222     "content": "This is :moominmamma: note 0",
 223     "created_at": "2019-04-15T15:42:15.000Z",
 224     "emojis": [],
 225     "favourited": false,
 226     "favourites_count": 1,
 227     "id": "9hptFmVJ02khbzYJaS",
 228     "in_reply_to_account_id": null,
 229     "in_reply_to_id": null,
 230     "language": null,
 231     "media_attachments": [],
 232     "mentions": [],
 233     "muted": false,
 234     "pinned": false,
 235     "pleroma": {
 236       "content": {"text/plain": "This is :moominmamma: note 0"},
 237       "conversation_id": 13679,
 238       "local": true,
 239       "spoiler_text": {"text/plain": "2hu"}
 240     },
 241     "reblog": null,
 242     "reblogged": false,
 243     "reblogs_count": 0,
 244     "replies_count": 0,
 245     "sensitive": false,
 246     "spoiler_text": "2hu",
 247     "tags": [{"name": "2hu", "url": "/tag/2hu"}],
 248     "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
 249     "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
 250     "visibility": "public"
 251   }
 252 ]
 253 ```
 254
 255 ## `/api/pleroma/notification_settings`
 256 ### Updates user notification settings
 257 * Method `PUT`
 258 * Authentication: required
 259 * Params:
 260     * `followers`: BOOLEAN field, receives notifications from followers
 261     * `follows`: BOOLEAN field, receives notifications from people the user follows
 262     * `remote`: BOOLEAN field, receives notifications from people on remote instances
 263     * `local`: BOOLEAN field, receives notifications from people on the local instance
 264 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
 265
 266 ## `/api/pleroma/healthcheck`
 267 ### Healthcheck endpoint with additional system data.
 268 * Method `GET`
 269 * Authentication: not required
 270 * Params: none
 271 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 272 * Example response:
 273 ```json
 274 {
 275   "pool_size": 0, # database connection pool
 276   "active": 0, # active processes
 277   "idle": 0, # idle processes
 278   "memory_used": 0.00, # Memory used
 279   "healthy": true # Instance state
 280 }
 281 ```