pleroma_api.md 15.8 KB
Newer Older
1
# Pleroma API
2 3 4 5 6 7 8 9 10 11 12

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).

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`.

## `/api/pleroma/emoji`
### Lists the custom emoji on that server.
* Method: `GET`
* Authentication: not required
* Params: none
* Response: JSON
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
* Example response:
```json
{
  "girlpower": {
    "tags": [
      "Finmoji"
    ],
    "image_url": "/finmoji/128px/girlpower-128.png"
  },
  "education": {
    "tags": [
      "Finmoji"
    ],
    "image_url": "/finmoji/128px/education-128.png"
  },
  "finnishlove": {
    "tags": [
      "Finmoji"
    ],
    "image_url": "/finmoji/128px/finnishlove-128.png"
  }
}
```
36
* Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
37 38 39 40 41 42 43

## `/api/pleroma/follow_import`
### Imports your follows, for example from a Mastodon CSV file.
* Method: `POST`
* Authentication: required
* Params:
    * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow
44 45 46 47 48 49 50 51
* Response: HTTP 200 on success, 500 on error
* Note: Users that can't be followed are silently skipped.

## `/api/pleroma/captcha`
### Get a new captcha
* Method: `GET`
* Authentication: not required
* Params: none
52
* Response: Provider specific JSON, the only guaranteed parameter is `type`
53 54 55 56 57 58
* Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`

## `/api/pleroma/delete_account`
### Delete an account
* Method `POST`
* Authentication: required
59
* Params:
60 61 62 63
    * `password`: user's password
* Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
* Example response: `{"error": "Invalid password."}`

64 65 66 67 68 69 70 71 72
## `/api/pleroma/disable_account`
### Disable an account
* Method `POST`
* Authentication: required
* Params:
    * `password`: user's password
* Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
* Example response: `{"error": "Invalid password."}`

Haelwenn's avatar
Haelwenn committed
73
## `/api/pleroma/admin/`…
rinpatch's avatar
rinpatch committed
74
See [Admin-API](admin_api.md)
75

76
## `/api/v1/pleroma/notifications/read`
77
### Mark notifications as read
78 79
* Method `POST`
* Authentication: required
80 81 82
* Params (mutually exclusive):
    * `id`: a single notification id to read
    * `max_id`: read all notifications up to this id
83
* Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
84 85 86 87 88 89 90 91 92 93 94

## `/api/v1/pleroma/accounts/:id/subscribe`
### Subscribe to receive notifications for all statuses posted by a user
* Method `POST`
* Authentication: required
* Params:
    * `id`: account id to subscribe to
* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
* Example response:
```json
{
Sadposter's avatar
Sadposter committed
95 96 97 98 99 100 101 102 103 104 105
  "id": "abcdefg",
  "following": true,
  "followed_by": false,
  "blocking": false,
  "muting": false,
  "muting_notifications": false,
  "subscribing": true,
  "requested": false,
  "domain_blocking": false,
  "showing_reblogs": true,
  "endorsed": false
106 107 108 109 110 111 112 113 114 115 116 117 118
}
```

## `/api/v1/pleroma/accounts/:id/unsubscribe`
### Unsubscribe to stop receiving notifications from user statuses
* Method `POST`
* Authentication: required
* Params:
    * `id`: account id to unsubscribe from
* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
* Example response:
```json
{
Sadposter's avatar
Sadposter committed
119 120 121 122 123 124 125 126 127 128 129
  "id": "abcdefg",
  "following": true,
  "followed_by": false,
  "blocking": false,
  "muting": false,
  "muting_notifications": false,
  "subscribing": false,
  "requested": false,
  "domain_blocking": false,
  "showing_reblogs": true,
  "endorsed": false
130 131
}
```
132

133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
## `/api/v1/pleroma/accounts/:id/favourites`
### Returns favorites timeline of any user
* Method `GET`
* Authentication: not required
* Params:
    * `id`: the id of the account for whom to return results
    * `limit`: optional, the number of records to retrieve
    * `since_id`: optional, returns results that are more recent than the specified id
    * `max_id`: optional, returns results that are older than the specified id
* Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
* Example response:
```json
[
  {
    "account": {
      "id": "9hptFmUF3ztxYh3Svg",
      "url": "https://pleroma.example.org/users/nick2",
      "username": "nick2",
      ...
    },
    "application": {"name": "Web", "website": null},
    "bookmarked": false,
    "card": null,
    "content": "This is :moominmamma: note 0",
    "created_at": "2019-04-15T15:42:15.000Z",
    "emojis": [],
    "favourited": false,
    "favourites_count": 1,
    "id": "9hptFmVJ02khbzYJaS",
    "in_reply_to_account_id": null,
    "in_reply_to_id": null,
    "language": null,
    "media_attachments": [],
    "mentions": [],
    "muted": false,
    "pinned": false,
    "pleroma": {
      "content": {"text/plain": "This is :moominmamma: note 0"},
      "conversation_id": 13679,
      "local": true,
      "spoiler_text": {"text/plain": "2hu"}
    },
    "reblog": null,
    "reblogged": false,
    "reblogs_count": 0,
    "replies_count": 0,
    "sensitive": false,
    "spoiler_text": "2hu",
    "tags": [{"name": "2hu", "url": "/tag/2hu"}],
    "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
    "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
    "visibility": "public"
  }
]
```

189 190 191 192 193 194 195
## `/api/v1/pleroma/accounts/update_*`
### Set and clear account avatar, banner, and background

- PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
- PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
- PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image

196 197 198 199 200 201
## `/api/v1/pleroma/accounts/confirmation_resend`
### Resend confirmation email
* Method `POST`
* Params:
    * `email`: email of that needs to be verified
* Authentication: not required
minibikini's avatar
minibikini committed
202
* Response: 204 No Content
203

204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
## `/api/v1/pleroma/mascot`
### Gets user mascot image
* Method `GET`
* Authentication: required

* Response: JSON. Returns a mastodon media attachment entity.
* Example response:
```json
{
    "id": "abcdefg",
    "url": "https://pleroma.example.org/media/abcdefg.png",
    "type": "image",
    "pleroma": {
        "mime_type": "image/png"
    }
}
```

### Updates user mascot image
* Method `PUT`
* Authentication: required
* Params:
    * `image`: Multipart image
* Response: JSON. Returns a mastodon media attachment entity
  when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
* Example response:
```json
{
    "id": "abcdefg",
    "url": "https://pleroma.example.org/media/abcdefg.png",
    "type": "image",
    "pleroma": {
        "mime_type": "image/png"
    }
}
```
* Note: Behaves exactly the same as `POST /api/v1/upload`.
  Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.

243 244 245 246 247 248 249 250 251
## `/api/pleroma/notification_settings`
### Updates user notification settings
* Method `PUT`
* Authentication: required
* Params:
    * `followers`: BOOLEAN field, receives notifications from followers
    * `follows`: BOOLEAN field, receives notifications from people the user follows
    * `remote`: BOOLEAN field, receives notifications from people on remote instances
    * `local`: BOOLEAN field, receives notifications from people on the local instance
lain's avatar
lain committed
252
    * `privacy_option`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
253
* Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
254 255 256 257 258 259 260 261 262 263 264 265 266 267

## `/api/pleroma/healthcheck`
### Healthcheck endpoint with additional system data.
* Method `GET`
* Authentication: not required
* Params: none
* Response: JSON, statuses (200 - healthy, 503 unhealthy).
* Example response:
```json
{
  "pool_size": 0, # database connection pool
  "active": 0, # active processes
  "idle": 0, # idle processes
  "memory_used": 0.00, # Memory used
268 269
  "healthy": true, # Instance state
  "job_queue_stats": {} # Job queue stats
270 271
}
```
272

minibikini's avatar
minibikini committed
273 274 275 276 277 278 279 280
## `/api/pleroma/change_email`
### Change account email
* Method `POST`
* Authentication: required
* Params:
    * `password`: user's password
    * `email`: new email
* Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
281
* Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
minibikini's avatar
minibikini committed
282

283 284 285 286
# Pleroma Conversations

Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:

287
1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
2. Pleroma Conversations statuses can be requested by Conversation id.
3. Pleroma Conversations can be replied to.

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.

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.


## `GET /api/v1/pleroma/conversations/:id/statuses`
### Timeline for a given conversation
* Method `GET`
* Authentication: required
* Params: Like other timelines
* Response: JSON, statuses (200 - healthy, 503 unhealthy).

303 304 305 306 307 308
## `GET /api/v1/pleroma/conversations/:id`
### The conversation with the given ID.
* Method `GET`
* Authentication: required
* Params: None
* Response: JSON, statuses (200 - healthy, 503 unhealthy).
309 310 311 312 313 314

## `PATCH /api/v1/pleroma/conversations/:id`
### Update a conversation. Used to change the set of recipients.
* Method `PATCH`
* Authentication: required
* Params:
315
    * `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.
316
* Response: JSON, statuses (200 - healthy, 503 unhealthy)
317

318 319 320 321 322 323 324
## `GET /api/v1/pleroma/conversations/read`
### Marks all user's conversations as read.
* Method `POST`
* Authentication: required
* Params: None
* Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).

325 326 327 328 329 330 331
## `GET /api/pleroma/emoji/packs`
### Lists the custom emoji packs on the server
* Method `GET`
* Authentication: not required
* Params: None
* Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents"

332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
## `PUT /api/pleroma/emoji/packs/:name`
### Creates an empty custom emoji pack
* Method `PUT`
* Authentication: required
* Params: None
* Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists

## `DELETE /api/pleroma/emoji/packs/:name`
### Delete a custom emoji pack
* Method `DELETE`
* Authentication: required
* Params: None
* Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack

## `POST /api/pleroma/emoji/packs/:name/update_file`
### Update a file in a custom emoji pack
* Method `POST`
* Authentication: required
350
* Params:
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
    * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`,
      that means that the emoji file needs to be uploaded with the request
      (thus requiring it to be a multipart request) and be named `file`.
      There can also be an optional `filename` that will be the new emoji file name
      (if it's not there, the name will be taken from the uploaded file).
    * if the `action` is `update`, changes emoji shortcode
      (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`)
    * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file
* Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode
  that is already taken, 400 if there was an error with the shortcode, filename or file (additional info
  in the "error" part of the response JSON)

## `POST /api/pleroma/emoji/packs/:name/update_metadata`
### Updates (replaces) pack metadata
* Method `POST`
* Authentication: required
367
* Params:
368 369 370 371 372 373 374 375
  * `new_data`: new metadata to replace the old one
* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
  problem with the new metadata (the error is specified in the "error" part of the response JSON)

## `POST /api/pleroma/emoji/packs/download_from`
### Requests the instance to download the pack from another instance
* Method `POST`
* Authentication: required
376
* Params:
377 378 379 380 381
  * `instance_address`: the address of the instance to download from
  * `pack_name`: the pack to download from that instance
* Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were
  errors downloading the pack

382 383 384 385 386 387 388 389 390
## `POST /api/pleroma/emoji/packs/list_from`
### Requests the instance to list the packs from another instance
* Method `POST`
* Authentication: required
* Params:
  * `instance_address`: the address of the instance to download from
* Response: JSON with the pack list, same as if the request was made to that instance's
  list endpoint directly + 200 status

391
## `GET /api/pleroma/emoji/packs/:name/download_shared`
392
### Requests a local pack from the instance
393
* Method `GET`
394
* Authentication: not required
395 396 397
* Params: None
* Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
  404 if the pack does not exist
398

399
## `GET /api/v1/pleroma/accounts/:id/scrobbles`
400 401 402 403 404 405 406 407 408
### Requests a list of current and recent Listen activities for an account
* Method `GET`
* Authentication: not required
* Params: None
* Response: An array of media metadata entities.
* Example response:
```json
[
   {
409
       "account": {...},
410 411 412 413
       "id": "1234",
       "title": "Some Title",
       "artist": "Some Artist",
       "album": "Some Album",
414 415
       "length": 180000,
       "created_at": "2019-09-28T12:40:45.000Z"
416 417 418 419
   }
]
```

Ariadne Conill's avatar
Ariadne Conill committed
420
## `POST /api/v1/pleroma/scrobble`
421 422 423 424 425 426 427 428 429
### Creates a new Listen activity for an account
* Method `POST`
* Authentication: required
* Params:
  * `title`: the title of the media playing
  * `album`: the album of the media playing [optional]
  * `artist`: the artist of the media playing [optional]
  * `length`: the length of the media playing [optional]
* Response: the newly created media metadata entity representing the Listen activity
430

431 432 433 434
# Emoji Reactions

Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character.

lain's avatar
lain committed
435
## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
436
### React to a post with a unicode emoji
437
* Method: `PUT`
438 439 440 441
* Authentication: required
* Params: `emoji`: A single character unicode emoji
* Response: JSON, the status.

lain's avatar
lain committed
442
## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
443
### Remove a reaction to a post with a unicode emoji
444
* Method: `DELETE`
445 446 447 448
* Authentication: required
* Params: `emoji`: A single character unicode emoji
* Response: JSON, the status.

lain's avatar
lain committed
449
## `GET /api/v1/pleroma/statuses/:id/reactions`
450 451 452 453
### Get an object of emoji to account mappings with accounts that reacted to the post
* Method: `GET`
* Authentication: optional
* Params: None
lain's avatar
lain committed
454
* Response: JSON, a list of emoji/account list tuples, sorted by emoji insertion date, in ascending order, e.g, the first emoji in the list is the oldest.
455 456
* Example Response:
```json
lain's avatar
lain committed
457
[
lain's avatar
lain committed
458 459
  {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
  {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
lain's avatar
lain committed
460
]
461
```