X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;f=docs%2Fapi%2Fpleroma_api.md;h=edc62727a46d0f4bcf7e61f834100a39d26f4506;hb=026b245dbc2900d90a737f024b87453bf552b62b;hp=2e8fb04d217e17060b78f3b0a9e4fbc3456b3150;hpb=9abf832b034bf3867272bd178d168c641129eff0;p=akkoma

diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md
index 2e8fb04d2..edc62727a 100644
--- a/docs/api/pleroma_api.md
+++ b/docs/api/pleroma_api.md
@@ -10,7 +10,29 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
 * Authentication: not required
 * Params: none
 * Response: JSON
-* Example response: `[{"kalsarikannit_f":{"tags":["Finmoji"],"image_url":"/finmoji/128px/kalsarikannit_f-128.png"}},{"perkele":{"tags":["Finmoji"],"image_url":"/finmoji/128px/perkele-128.png"}},{"blobdab":{"tags":["SomeTag"],"image_url":"/emoji/blobdab.png"}},"happiness":{"tags":["Finmoji"],"image_url":"/finmoji/128px/happiness-128.png"}}]`
+* 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"
+  }
+}
+```
 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
 
 ## `/api/pleroma/follow_import`
@@ -39,6 +61,15 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
 * Example response: `{"error": "Invalid password."}`
 
+## `/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."}`
+
 ## `/api/account/register`
 ### Register a new user
 * Method `POST`
@@ -52,10 +83,10 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
     * `confirm`
     * `captcha_solution`: optional, contains provider-specific captcha solution,
     * `captcha_token`: optional, contains provider-specific captcha token
-    * `token`: invite token required when the registerations aren't public.
+    * `token`: invite token required when the registrations aren't public.
 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
 * Example response:
-```
+```json
 {
 	"background_image": null,
 	"cover_photo": "https://pleroma.soykaf.com/images/banner.png",
@@ -95,24 +126,181 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
 ## `/api/pleroma/admin/`…
 See [Admin-API](Admin-API.md)
 
-## `/api/v1/pleroma/flavour/:flavour`
+## `/api/pleroma/notifications/read`
+### Mark a single notification as read
 * Method `POST`
 * Authentication: required
-* Response: JSON string. Returns the user flavour or the default one on success, otherwise returns `{"error": "error_msg"}`
-* Example response: "glitch"
-* Note: This is intended to be used only by mastofe
+* Params:
+    * `id`: notification's id
+* Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
 
-## `/api/v1/pleroma/flavour`
-* Method `GET`
+## `/api/v1/pleroma/accounts/:id/subscribe`
+### Subscribe to receive notifications for all statuses posted by a user
+* Method `POST`
 * Authentication: required
-* Response: JSON string. Returns the user flavour or the default one.
-* Example response: "glitch"
-* Note: This is intended to be used only by mastofe
+* Params:
+    * `id`: account id to subscribe to
+* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
+* Example response:
+```json
+{
+  "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
+}
+```
 
-## `/api/pleroma/notifications/read`
-### Mark a single notification as read
+## `/api/v1/pleroma/accounts/:id/unsubscribe`
+### Unsubscribe to stop receiving notifications from user statuses
 * Method `POST`
 * Authentication: required
 * Params:
-    * `id`: notifications's id
-* Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
+    * `id`: account id to unsubscribe from
+* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
+* Example response:
+```json
+{
+  "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
+}
+```
+
+## `/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"
+  }
+]
+```
+
+## `/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`.
+
+## `/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
+* Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
+
+## `/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
+  "healthy": true # Instance state
+}
+```