re f83bae7c: remove unnecessary filter
[akkoma] / docs / Pleroma-API.md
1 # Authentication
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
6
7 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`.
8
9 # Endpoints
10
11 ## `/api/pleroma/emoji`
12 ### Lists the custom emoji on that server.
13 * Method: `GET`
14 * Authentication: not required
15 * Params: none
16 * Response: JSON
17 * Example response: `{"kalsarikannit_f":"/finmoji/128px/kalsarikannit_f-128.png","perkele":"/finmoji/128px/perkele-128.png","blobdab":"/emoji/blobdab.png","happiness":"/finmoji/128px/happiness-128.png"}`
18
19 ## `/api/pleroma/follow_import`
20 ### Imports your follows, for example from a Mastodon CSV file.
21 * Method: `POST`
22 * Authentication: required
23 * Params:
24 * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow
25 * Response: HTTP 200 on success, 500 on error
26 * Note: Users that can't be followed are silently skipped.
27
28 ## `/api/pleroma/captcha`
29 ### Get a new captcha
30 * Method: `GET`
31 * Authentication: not required
32 * Params: none
33 * Response: Provider specific JSON, the only guaranteed parameter is `type`
34 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`
35
36 ## `/api/pleroma/delete_account`
37 ### Delete an account
38 * Method `POST`
39 * Authentication: required
40 * Params:
41 * `password`: user's password
42 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
43 * Example response: `{"error": "Invalid password."}`
44
45 ## `/api/account/register`
46 ### Register a new user
47 * Method `POST`
48 * Authentication: not required
49 * Params:
50 * `nickname`
51 * `fullname`
52 * `bio`
53 * `email`
54 * `password`
55 * `confirm`
56 * `captcha_solution`: optional, contains provider-specific captcha solution,
57 * `captcha_token`: optional, contains provider-specific captcha token
58 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
59 * Example response:
60 ```
61 {
62 "background_image": null,
63 "cover_photo": "https://pleroma.soykaf.com/images/banner.png",
64 "created_at": "Tue Dec 18 16:55:56 +0000 2018",
65 "default_scope": "public",
66 "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.",
67 "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.",
68 "favourites_count": 0,
69 "fields": [],
70 "followers_count": 0,
71 "following": false,
72 "follows_you": false,
73 "friends_count": 0,
74 "id": 6,
75 "is_local": true,
76 "locked": false,
77 "name": "lain",
78 "name_html": "lain",
79 "no_rich_text": false,
80 "pleroma": {
81 "tags": []
82 },
83 "profile_image_url": "https://pleroma.soykaf.com/images/avi.png",
84 "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png",
85 "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png",
86 "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png",
87 "rights": {
88 "delete_others_notice": false
89 },
90 "screen_name": "lain",
91 "statuses_count": 0,
92 "statusnet_blocking": false,
93 "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
94 }
95 ```
96
97 ## `/api/pleroma/admin/`…
98 See [Admin-API](Admin-API.md)