summaryrefslogtreecommitdiff
path: root/docs/API
diff options
context:
space:
mode:
Diffstat (limited to 'docs/API')
-rw-r--r--docs/API/admin_api.md169
-rw-r--r--docs/API/pleroma_api.md153
-rw-r--r--docs/API/prometheus.md26
3 files changed, 289 insertions, 59 deletions
diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md
index c0ea074f0..7bf13daef 100644
--- a/docs/API/admin_api.md
+++ b/docs/API/admin_api.md
@@ -349,9 +349,9 @@ Response:
### Unfollow a Relay
-Params:
-
-* `relay_url`
+- Params:
+ - `relay_url`
+ - *optional* `force`: forcefully unfollow a relay even when the relay is not available. (default is `false`)
Response:
@@ -1334,3 +1334,166 @@ Loads json generated from `config/descriptions.exs`.
{ }
```
+
+## GET /api/pleroma/admin/users/:nickname/chats
+
+### List a user's chats
+
+- Params: None
+
+- Response:
+
+```json
+[
+ {
+ "sender": {
+ "id": "someflakeid",
+ "username": "somenick",
+ ...
+ },
+ "receiver": {
+ "id": "someflakeid",
+ "username": "somenick",
+ ...
+ },
+ "id" : "1",
+ "unread" : 2,
+ "last_message" : {...}, // The last message in that chat
+ "updated_at": "2020-04-21T15:11:46.000Z"
+ }
+]
+```
+
+## GET /api/pleroma/admin/chats/:chat_id
+
+### View a single chat
+
+- Params: None
+
+- Response:
+
+```json
+{
+ "sender": {
+ "id": "someflakeid",
+ "username": "somenick",
+ ...
+ },
+ "receiver": {
+ "id": "someflakeid",
+ "username": "somenick",
+ ...
+ },
+ "id" : "1",
+ "unread" : 2,
+ "last_message" : {...}, // The last message in that chat
+ "updated_at": "2020-04-21T15:11:46.000Z"
+}
+```
+
+## GET /api/pleroma/admin/chats/:chat_id/messages
+
+### List the messages in a chat
+
+- Params: `max_id`, `min_id`
+
+- Response:
+
+```json
+[
+ {
+ "account_id": "someflakeid",
+ "chat_id": "1",
+ "content": "Check this out :firefox:",
+ "created_at": "2020-04-21T15:11:46.000Z",
+ "emojis": [
+ {
+ "shortcode": "firefox",
+ "static_url": "https://dontbulling.me/emoji/Firefox.gif",
+ "url": "https://dontbulling.me/emoji/Firefox.gif",
+ "visible_in_picker": false
+ }
+ ],
+ "id": "13",
+ "unread": true
+ },
+ {
+ "account_id": "someflakeid",
+ "chat_id": "1",
+ "content": "Whats' up?",
+ "created_at": "2020-04-21T15:06:45.000Z",
+ "emojis": [],
+ "id": "12",
+ "unread": false
+ }
+]
+```
+
+## DELETE /api/pleroma/admin/chats/:chat_id/messages/:message_id
+
+### Delete a single message
+
+- Params: None
+
+- Response:
+
+```json
+{
+ "account_id": "someflakeid",
+ "chat_id": "1",
+ "content": "Check this out :firefox:",
+ "created_at": "2020-04-21T15:11:46.000Z",
+ "emojis": [
+ {
+ "shortcode": "firefox",
+ "static_url": "https://dontbulling.me/emoji/Firefox.gif",
+ "url": "https://dontbulling.me/emoji/Firefox.gif",
+ "visible_in_picker": false
+ }
+ ],
+ "id": "13",
+ "unread": false
+}
+```
+
+## `GET /api/pleroma/admin/instance_document/:document_name`
+
+### Get an instance document
+
+- Authentication: required
+
+- Response:
+
+Returns the content of the document
+
+```html
+<h1>Instance panel</h1>
+```
+
+## `PATCH /api/pleroma/admin/instance_document/:document_name`
+- Params:
+ - `file` (the file to be uploaded, using multipart form data.)
+
+### Update an instance document
+
+- Authentication: required
+
+- Response:
+
+``` json
+{
+ "url": "https://example.com/instance/panel.html"
+}
+```
+
+## `DELETE /api/pleroma/admin/instance_document/:document_name`
+
+### Delete an instance document
+
+- Response:
+
+``` json
+{
+ "url": "https://example.com/instance/panel.html"
+}
+```
diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md
index 4e97d26c0..3fd141bd2 100644
--- a/docs/API/pleroma_api.md
+++ b/docs/API/pleroma_api.md
@@ -44,6 +44,22 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* Response: HTTP 200 on success, 500 on error
* Note: Users that can't be followed are silently skipped.
+## `/api/pleroma/blocks_import`
+### Imports your blocks.
+* Method: `POST`
+* Authentication: required
+* Params:
+ * `list`: STRING or FILE containing a whitespace-separated list of accounts to block
+* Response: HTTP 200 on success, 500 on error
+
+## `/api/pleroma/mutes_import`
+### Imports your mutes.
+* Method: `POST`
+* Authentication: required
+* Params:
+ * `list`: STRING or FILE containing a whitespace-separated list of accounts to mute
+* Response: HTTP 200 on success, 500 on error
+
## `/api/pleroma/captcha`
### Get a new captcha
* Method: `GET`
@@ -362,44 +378,43 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* Params: None
* Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
-## `GET /api/pleroma/emoji/packs/import`
-### Imports packs from filesystem
-* Method `GET`
-* Authentication: required
-* Params: None
-* Response: JSON, returns a list of imported packs.
+## `GET /api/pleroma/emoji/pack?name=:name`
+
+### Get pack.json for the pack
-## `GET /api/pleroma/emoji/packs/remote`
-### Make request to another instance for packs list
* Method `GET`
-* Authentication: required
+* Authentication: not required
* Params:
- * `url`: url of the instance to get packs from
-* Response: JSON with the pack list, hashmap with pack name and pack contents
+ * `page`: page number for files (default 1)
+ * `page_size`: page size for files (default 30)
+* Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
-## `POST /api/pleroma/emoji/packs/download`
-### Download pack from another instance
-* Method `POST`
-* Authentication: required
-* Params:
- * `url`: url of the instance to download from
- * `name`: pack to download from that instance
- * `as`: (*optional*) name how to save pack
-* Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
- errors downloading the pack
+```json
+{
+ "files": {...},
+ "files_count": 0, // emoji count in pack
+ "pack": {...}
+}
+```
+
+## `POST /api/pleroma/emoji/pack?name=:name`
-## `POST /api/pleroma/emoji/packs/:name`
### Creates an empty pack
+
* Method `POST`
-* Authentication: required
-* Params: None
+* Authentication: required (admin)
+* Params:
+ * `name`: pack name
* Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
-## `PATCH /api/pleroma/emoji/packs/:name`
+## `PATCH /api/pleroma/emoji/pack?name=:name`
+
### Updates (replaces) pack metadata
+
* Method `PATCH`
-* Authentication: required
+* Authentication: required (admin)
* Params:
+ * `name`: pack name
* `metadata`: metadata to replace the old one
* `license`: Pack license
* `homepage`: Pack home page url
@@ -410,39 +425,85 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* 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)
-## `DELETE /api/pleroma/emoji/packs/:name`
+## `DELETE /api/pleroma/emoji/pack?name=:name`
+
### Delete a custom emoji pack
+
* Method `DELETE`
-* Authentication: required
-* Params: None
+* Authentication: required (admin)
+* Params:
+ * `name`: pack name
* Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
-## `POST /api/pleroma/emoji/packs/:name/files`
+## `GET /api/pleroma/emoji/packs/import`
+
+### Imports packs from filesystem
+
+* Method `GET`
+* Authentication: required (admin)
+* Params: None
+* Response: JSON, returns a list of imported packs.
+
+## `GET /api/pleroma/emoji/packs/remote`
+
+### Make request to another instance for packs list
+
+* Method `GET`
+* Authentication: required (admin)
+* Params:
+ * `url`: url of the instance to get packs from
+ * `page`: page number for packs (default 1)
+ * `page_size`: page size for packs (default 50)
+* Response: JSON with the pack list, hashmap with pack name and pack contents
+
+## `POST /api/pleroma/emoji/packs/download`
+
+### Download pack from another instance
+
+* Method `POST`
+* Authentication: required (admin)
+* Params:
+ * `url`: url of the instance to download from
+ * `name`: pack to download from that instance
+ * `as`: (*optional*) name how to save pack
+* Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
+ errors downloading the pack
+
+## `POST /api/pleroma/emoji/packs/files?name=:name`
+
### Add new file to the pack
+
* Method `POST`
-* Authentication: required
+* Authentication: required (admin)
* Params:
+ * `name`: pack name
* `file`: file needs to be uploaded with the multipart request or link to remote file.
* `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
* `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
* Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
-## `PATCH /api/pleroma/emoji/packs/:name/files`
+## `PATCH /api/pleroma/emoji/packs/files?name=:name`
+
### Update emoji file from pack
+
* Method `PATCH`
-* Authentication: required
+* Authentication: required (admin)
* Params:
+ * `name`: pack name
* `shortcode`: emoji file shortcode
* `new_shortcode`: new emoji file shortcode
* `new_filename`: new filename for emoji file
* `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
* Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
-## `DELETE /api/pleroma/emoji/packs/:name/files`
+## `DELETE /api/pleroma/emoji/packs/files?name=:name`
+
### Delete emoji file from pack
+
* Method `DELETE`
-* Authentication: required
+* Authentication: required (admin)
* Params:
+ * `name`: pack name
* `shortcode`: emoji file shortcode
* Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
@@ -467,30 +528,14 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
}
```
-## `GET /api/pleroma/emoji/packs/:name`
+## `GET /api/pleroma/emoji/packs/archive?name=:name`
-### Get pack.json for the pack
+### Requests a local pack archive from the instance
* Method `GET`
* Authentication: not required
* Params:
- * `page`: page number for files (default 1)
- * `page_size`: page size for files (default 30)
-* Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
-
-```json
-{
- "files": {...},
- "files_count": 0, // emoji count in pack
- "pack": {...}
-}
-```
-
-## `GET /api/pleroma/emoji/packs/:name/archive`
-### Requests a local pack archive from the instance
-* Method `GET`
-* Authentication: not required
-* Params: None
+ * `name`: pack name
* 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
diff --git a/docs/API/prometheus.md b/docs/API/prometheus.md
index 19c564e3c..a5158d905 100644
--- a/docs/API/prometheus.md
+++ b/docs/API/prometheus.md
@@ -2,15 +2,37 @@
Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library.
+Config example:
+
+```
+config :prometheus, Pleroma.Web.Endpoint.MetricsExporter,
+ enabled: true,
+ auth: {:basic, "myusername", "mypassword"},
+ ip_whitelist: ["127.0.0.1"],
+ path: "/api/pleroma/app_metrics",
+ format: :text
+```
+
+* `enabled` (Pleroma extension) enables the endpoint
+* `ip_whitelist` (Pleroma extension) could be used to restrict access only to specified IPs
+* `auth` sets the authentication (`false` for no auth; configurable to HTTP Basic Auth, see [prometheus-plugs](https://github.com/deadtrickster/prometheus-plugs#exporting) documentation)
+* `format` sets the output format (`:text` or `:protobuf`)
+* `path` sets the path to app metrics page
+
+
## `/api/pleroma/app_metrics`
+
### Exports Prometheus application metrics
+
* Method: `GET`
-* Authentication: not required
+* Authentication: not required by default (see configuration options above)
* Params: none
-* Response: JSON
+* Response: text
## Grafana
+
### Config example
+
The following is a config example to use with [Grafana](https://grafana.com)
```
generated by cgit v1.2.3 (git 2.44.0) at 2024-05-02 09:37:35 +0000