X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;f=docs%2FAPI%2Fpleroma_api.md;h=d8790ca3250f7a0709f26389bd5c9d4bd9483b6c;hb=a010c5b16a395d823a98cd088c83acd098930ade;hp=94b6a4fda5195e7f7b355a489e25136fe33766a6;hpb=8f5589cf667d8dd24da07e58db94225d81a55a7b;p=akkoma diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 94b6a4fda..d8790ca32 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -378,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 @@ -426,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. @@ -483,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 @@ -550,14 +579,14 @@ Emoji reactions work a lot like favourites do. They make it possible to react to ### React to a post with a unicode emoji * Method: `PUT` * Authentication: required -* Params: `emoji`: A single character unicode emoji +* Params: `emoji`: A unicode RGI emoji or a regional indicator * Response: JSON, the status. ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji` ### Remove a reaction to a post with a unicode emoji * Method: `DELETE` * Authentication: required -* Params: `emoji`: A single character unicode emoji +* Params: `emoji`: A unicode RGI emoji or a regional indicator * Response: JSON, the status. ## `GET /api/v1/pleroma/statuses/:id/reactions` @@ -586,3 +615,41 @@ Emoji reactions work a lot like favourites do. They make it possible to react to {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]} ] ``` + +## `POST /api/v1/pleroma/backups` +### Create a user backup archive + +* Method: `POST` +* Authentication: required +* Params: none +* Response: JSON +* Example response: + +```json +[{ + "content_type": "application/zip", + "file_size": 0, + "inserted_at": "2020-09-10T16:18:03.000Z", + "processed": false, + "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip" +}] +``` + +## `GET /api/v1/pleroma/backups` +### Lists user backups + +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: + +```json +[{ + "content_type": "application/zip", + "file_size": 55457, + "inserted_at": "2020-09-10T16:18:03.000Z", + "processed": true, + "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip" +}] +```