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/account/register`
  65 ### Register a new user
  66 * Method `POST`
  67 * Authentication: not required
  68 * Params:
  69     * `nickname`
  70     * `fullname`
  71     * `bio`
  72     * `email`
  73     * `password`
  74     * `confirm`
  75     * `captcha_solution`: optional, contains provider-specific captcha solution,
  76     * `captcha_token`: optional, contains provider-specific captcha token
  77     * `token`: invite token required when the registrations aren't public.
  78 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
  79 * Example response:
  80 ```json
  81 {
  82         "background_image": null,
  83         "cover_photo": "https://pleroma.soykaf.com/images/banner.png",
  84         "created_at": "Tue Dec 18 16:55:56 +0000 2018",
  85         "default_scope": "public",
  86         "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.",
  87         "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.",
  88         "favourites_count": 0,
  89         "fields": [],
  90         "followers_count": 0,
  91         "following": false,
  92         "follows_you": false,
  93         "friends_count": 0,
  94         "id": 6,
  95         "is_local": true,
  96         "locked": false,
  97         "name": "lain",
  98         "name_html": "lain",
  99         "no_rich_text": false,
 100         "pleroma": {
 101                 "tags": []
 102         },
 103         "profile_image_url": "https://pleroma.soykaf.com/images/avi.png",
 104         "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png",
 105         "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png",
 106         "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png",
 107         "rights": {
 108                 "delete_others_notice": false
 109         },
 110         "screen_name": "lain",
 111         "statuses_count": 0,
 112         "statusnet_blocking": false,
 113         "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
 114 }
 115 ```
 116
 117 ## `/api/pleroma/admin/`…
 118 See [Admin-API](Admin-API.md)
 119
 120 ## `/api/v1/pleroma/flavour/:flavour`
 121 * Method `POST`
 122 * Authentication: required
 123 * Response: JSON string. Returns the user flavour or the default one on success, otherwise returns `{"error": "error_msg"}`
 124 * Example response: "glitch"
 125 * Note: This is intended to be used only by mastofe
 126
 127 ## `/api/v1/pleroma/flavour`
 128 * Method `GET`
 129 * Authentication: required
 130 * Response: JSON string. Returns the user flavour or the default one.
 131 * Example response: "glitch"
 132 * Note: This is intended to be used only by mastofe
 133
 134 ## `/api/pleroma/notifications/read`
 135 ### Mark a single notification as read
 136 * Method `POST`
 137 * Authentication: required
 138 * Params:
 139     * `id`: notification's id
 140 * Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
 141
 142 ## `/api/v1/pleroma/accounts/:id/subscribe`
 143 ### Subscribe to receive notifications for all statuses posted by a user
 144 * Method `POST`
 145 * Authentication: required
 146 * Params:
 147     * `id`: account id to subscribe to
 148 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 149 * Example response:
 150 ```json
 151 {
 152   "id": "abcdefg",
 153   "following": true,
 154   "followed_by": false,
 155   "blocking": false,
 156   "muting": false,
 157   "muting_notifications": false,
 158   "subscribing": true,
 159   "requested": false,
 160   "domain_blocking": false,
 161   "showing_reblogs": true,
 162   "endorsed": false
 163 }
 164 ```
 165
 166 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
 167 ### Unsubscribe to stop receiving notifications from user statuses
 168 * Method `POST`
 169 * Authentication: required
 170 * Params:
 171     * `id`: account id to unsubscribe from
 172 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 173 * Example response:
 174 ```json
 175 {
 176   "id": "abcdefg",
 177   "following": true,
 178   "followed_by": false,
 179   "blocking": false,
 180   "muting": false,
 181   "muting_notifications": false,
 182   "subscribing": false,
 183   "requested": false,
 184   "domain_blocking": false,
 185   "showing_reblogs": true,
 186   "endorsed": false
 187 }
 188 ```
 189
 190 ## `/api/v1/pleroma/accounts/:id/favourites`
 191 ### Returns favorites timeline of any user
 192 * Method `GET`
 193 * Authentication: not required
 194 * Params:
 195     * `id`: the id of the account for whom to return results
 196     * `limit`: optional, the number of records to retrieve
 197     * `since_id`: optional, returns results that are more recent than the specified id
 198     * `max_id`: optional, returns results that are older than the specified id
 199 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
 200 * Example response:
 201 ```json
 202 [
 203   {
 204     "account": {
 205       "id": "9hptFmUF3ztxYh3Svg",
 206       "url": "https://pleroma.example.org/users/nick2",
 207       "username": "nick2",
 208       ...
 209     },
 210     "application": {"name": "Web", "website": null},
 211     "bookmarked": false,
 212     "card": null,
 213     "content": "This is :moominmamma: note 0",
 214     "created_at": "2019-04-15T15:42:15.000Z",
 215     "emojis": [],
 216     "favourited": false,
 217     "favourites_count": 1,
 218     "id": "9hptFmVJ02khbzYJaS",
 219     "in_reply_to_account_id": null,
 220     "in_reply_to_id": null,
 221     "language": null,
 222     "media_attachments": [],
 223     "mentions": [],
 224     "muted": false,
 225     "pinned": false,
 226     "pleroma": {
 227       "content": {"text/plain": "This is :moominmamma: note 0"},
 228       "conversation_id": 13679,
 229       "local": true,
 230       "spoiler_text": {"text/plain": "2hu"}
 231     },
 232     "reblog": null,
 233     "reblogged": false,
 234     "reblogs_count": 0,
 235     "replies_count": 0,
 236     "sensitive": false,
 237     "spoiler_text": "2hu",
 238     "tags": [{"name": "2hu", "url": "/tag/2hu"}],
 239     "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
 240     "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
 241     "visibility": "public"
 242   }
 243 ]
 244 ```
 245
 246 ## `/api/pleroma/notification_settings`
 247 ### Updates user notification settings
 248 * Method `PUT`
 249 * Authentication: required
 250 * Params:
 251     * `followers`: BOOLEAN field, receives notifications from followers
 252     * `follows`: BOOLEAN field, receives notifications from people the user follows
 253     * `remote`: BOOLEAN field, receives notifications from people on remote instances
 254     * `local`: BOOLEAN field, receives notifications from people on the local instance
 255 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
 256
 257 ## `/api/pleroma/healthcheck`
 258 ### Healthcheck endpoint with additional system data.
 259 * Method `GET`
 260 * Authentication: not required
 261 * Params: none
 262 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 263 * Example response:
 264 ```json
 265 {
 266   "pool_size": 0, # database connection pool
 267   "active": 0, # active processes
 268   "idle": 0, # idle processes
 269   "memory_used": 0.00, # Memory used
 270   "healthy": true # Instance state
 271 }
 272 ```