mirror of
https://github.com/versia-pub/server.git
synced 2026-03-13 05:49:16 +01:00
feat(api): ✨ Add new admin emoji API
This commit is contained in:
Jesse Wierzbinski
parent
b979daa39a
commit
8fedd1a07d
20 changed files with 954 additions and 167 deletions
94
docs/api/emojis.md
Normal file
94
docs/api/emojis.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# Emoji API
|
||||
|
||||
An Emoji API is made available to administrators to manage custom emoji on the instance. We recommend using Lysand's CLI to manage emoji, but this API is available for those who prefer to use it.
|
||||
|
||||
## Create Emoji
|
||||
|
||||
```http
|
||||
POST /api/v1/emojis
|
||||
```
|
||||
|
||||
Creates a new custom emoji on the instance.
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Content-Type`: `multipart/form-data`, `application/json` or `application/x-www-form-urlencoded`. If uploading a file, use `multipart/form-data`.
|
||||
|
||||
- `shortcode`: string, required. The shortcode for the emoji. Must be 2-64 characters long and contain only alphanumeric characters, dashes, and underscores.
|
||||
- `element`: string or file, required. The image file for the emoji. This can be a URL or a file upload.
|
||||
- `alt`: string, optional. The alt text for the emoji. Defaults to the shortcode.
|
||||
|
||||
### Response
|
||||
|
||||
```ts
|
||||
// 200 OK
|
||||
{
|
||||
id: string,
|
||||
shortcode: string,
|
||||
url: string,
|
||||
static_url: string,
|
||||
visible_in_picker: boolean,
|
||||
// Lysand does not have a category system for emoji yet, so this is always undefined.
|
||||
category: undefined,
|
||||
}
|
||||
```
|
||||
|
||||
## Get Emoji
|
||||
|
||||
```http
|
||||
GET /api/v1/emojis/:id
|
||||
```
|
||||
|
||||
Retrieves information about a custom emoji on the instance.
|
||||
|
||||
### Response
|
||||
|
||||
```ts
|
||||
// 200 OK
|
||||
{
|
||||
id: string,
|
||||
shortcode: string,
|
||||
url: string,
|
||||
static_url: string,
|
||||
visible_in_picker: boolean,
|
||||
category: undefined,
|
||||
}
|
||||
```
|
||||
|
||||
## Edit Emoji
|
||||
|
||||
```http
|
||||
PATCH /api/v1/emojis/:id
|
||||
```
|
||||
|
||||
Edits a custom emoji on the instance.
|
||||
|
||||
### Parameters
|
||||
|
||||
- `Content-Type`: `application/json`, `multipart/form-data` or `application/x-www-form-urlencoded`. If uploading a file, use `multipart/form-data`.
|
||||
|
||||
- `shortcode`: string, optional. The new shortcode for the emoji. Must be 2-64 characters long and contain only alphanumeric characters, dashes, and underscores.
|
||||
- `element`: string or file, optional. The new image file for the emoji. This can be a URL or a file upload.
|
||||
- `alt`: string, optional. The new alt text for the emoji. Defaults to the shortcode.
|
||||
|
||||
### Response
|
||||
|
||||
```ts
|
||||
// 200 OK
|
||||
{
|
||||
id: string,
|
||||
shortcode: string,
|
||||
url: string,
|
||||
static_url: string,
|
||||
visible_in_picker: boolean,
|
||||
category: undefined,
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Emoji
|
||||
|
||||
```http
|
||||
DELETE /api/v1/emojis/:id
|
||||
```
|
||||
|
||||
Deletes a custom emoji on the instance.
|
||||
13
docs/api/index.md
Normal file
13
docs/api/index.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
# Lysand API Documentation
|
||||
|
||||
The Lysand API strictly follows the latest available Mastodon API version (Glitch-Soc version). This means that the Lysand API is a superset of the Mastodon API, with additional endpoints and features.
|
||||
|
||||
Some more information about the Mastodon API can be found in the [Mastodon API documentation](https://docs.joinmastodon.org/api/).
|
||||
|
||||
## Emoji API
|
||||
|
||||
For administrators. Please read [the documentation](./emojis.md).
|
||||
|
||||
## Moderation API
|
||||
|
||||
For administrators. Not implemented. Please read [the documentation](./moderation.md).
|
||||
271
docs/api/moderation.md
Normal file
271
docs/api/moderation.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
# Moderation API
|
||||
|
||||
> [!WARNING]
|
||||
> **NOT IMPLEMENTED**
|
||||
|
||||
The Lysand project uses the Mastodon API to interact with clients. However, the moderation API is custom-made for Lysand Server, as it allows for more fine-grained control over the server's behavior.
|
||||
|
||||
## Flags, ModTags and ModNotes
|
||||
|
||||
Flags are used by Lysand Server to automatically attribute tags to a status or account based on rules. ModTags and ModNotes are used by moderators to manually tag and take notes on statuses and accounts.
|
||||
|
||||
The difference between flags and modtags is that flags are automatically attributed by the server, while modtags are manually attributed by moderators.
|
||||
|
||||
### Flag Types
|
||||
|
||||
- `content_filter`: (Statuses only) The status contains content that was filtered by the server's content filter.
|
||||
- `bio_filter`: (Accounts only) The account's bio contains content that was filtered by the server's content filter.
|
||||
- `emoji_filter`: The status or account contains an emoji that was filtered by the server's content filter.
|
||||
- `reported`: The status or account was previously reported by a user.
|
||||
- `suspended`: The status or account was previously suspended by a moderator.
|
||||
- `silenced`: The status or account was previously silenced by a moderator.
|
||||
|
||||
### ModTag Types
|
||||
|
||||
ModTag do not have set types and can be anything. Lysand Server autosuggest previously used tags when a moderator is adding a new tag to avoid duplicates.
|
||||
|
||||
### Data Format
|
||||
|
||||
```ts
|
||||
type Flag = {
|
||||
id: string,
|
||||
// One of the following two fields will be present
|
||||
flaggedStatus?: Status,
|
||||
flaggedUser?: User,
|
||||
flagType: string,
|
||||
createdAt: string,
|
||||
}
|
||||
|
||||
type ModTag = {
|
||||
id: string,
|
||||
// One of the following two fields will be present
|
||||
taggedStatus?: Status,
|
||||
taggedUser?: User,
|
||||
mod: User,
|
||||
tag: string,
|
||||
createdAt: string,
|
||||
}
|
||||
|
||||
type ModNote = {
|
||||
id: string,
|
||||
// One of the following two fields will be present
|
||||
notedStatus?: Status,
|
||||
notedUser?: User,
|
||||
mod: User,
|
||||
note: string,
|
||||
createdAt: string,
|
||||
}
|
||||
```
|
||||
|
||||
The `User` and `Status` types are the same as the ones in the Mastodon API.
|
||||
|
||||
## Moderation API Routes
|
||||
|
||||
### `GET /api/v1/moderation/accounts/:id`
|
||||
|
||||
Returns full moderation data and flags for the account with the given ID.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
id: string, // Same ID as in account field
|
||||
flags: Flag[],
|
||||
modtags: ModTag[],
|
||||
modnotes: ModNote[],
|
||||
account: User,
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/moderation/statuses/:id`
|
||||
|
||||
Returns full moderation data and flags for the status with the given ID.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
id: string, // Same ID as in status field
|
||||
flags: Flag[],
|
||||
modtags: ModTag[],
|
||||
modnotes: ModNote[],
|
||||
status: Status,
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/moderation/accounts/:id/modtags`
|
||||
|
||||
Params:
|
||||
- `tag`: string
|
||||
|
||||
Adds a modtag to the account with the given ID
|
||||
|
||||
### `POST /api/v1/moderation/statuses/:id/modtags`
|
||||
|
||||
Params:
|
||||
- `tag`: string
|
||||
|
||||
Adds a modtag to the status with the given ID
|
||||
|
||||
### `POST /api/v1/moderation/accounts/:id/modnotes`
|
||||
|
||||
Params:
|
||||
- `note`: string
|
||||
|
||||
Adds a modnote to the account with the given ID
|
||||
|
||||
### `POST /api/v1/moderation/statuses/:id/modnotes`
|
||||
|
||||
Params:
|
||||
- `note`: string
|
||||
|
||||
Adds a modnote to the status with the given ID
|
||||
|
||||
### `DELETE /api/v1/moderation/accounts/:id/modtags/:modtag_id`
|
||||
|
||||
Deletes the modtag with the given ID from the account with the given ID
|
||||
|
||||
### `DELETE /api/v1/moderation/statuses/:id/modtags/:modtag_id`
|
||||
|
||||
Deletes the modtag with the given ID from the status with the given ID
|
||||
|
||||
### `DELETE /api/v1/moderation/accounts/:id/modnotes/:modnote_id`
|
||||
|
||||
Deletes the modnote with the given ID from the account with the given ID
|
||||
|
||||
### `DELETE /api/v1/moderation/statuses/:id/modnotes/:modnote_id`
|
||||
|
||||
Deletes the modnote with the given ID from the status with the given ID
|
||||
|
||||
### `GET /api/v1/moderation/modtags`
|
||||
|
||||
Returns a list of all modtags previously used by moderators
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
tags: string[],
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/moderation/accounts/flags/search`
|
||||
|
||||
Allows moderators to search for accounts based on their flags, this can also include status flags
|
||||
|
||||
Params:
|
||||
- `limit`: Number
|
||||
- `min_id`: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
||||
- `max_id`: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
||||
- `since_id`: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
||||
- `flags`: String (optional). Comma-separated list of flag types to filter by. Can be left out to return accounts with at least one flag
|
||||
- `flag_count`: Number (optional). Minimum number of flags to filter by
|
||||
- `include_statuses`: Boolean (optional). If true, includes status flags in the search results
|
||||
- `account_id`: Array of strings (optional). Filters accounts by account ID
|
||||
|
||||
This method returns a `Link` header the same way Mastodon does, to allow for pagination.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
accounts: {
|
||||
account: User,
|
||||
modnotes: ModNote[],
|
||||
flags: Flag[],
|
||||
statuses?: {
|
||||
status: Status,
|
||||
modnotes: ModNote[],
|
||||
flags: Flag[],
|
||||
}[],
|
||||
}[],
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/moderation/statuses/flags/search`
|
||||
|
||||
Allows moderators to search for statuses based on their flags
|
||||
|
||||
Params:
|
||||
- `limit`: Number
|
||||
- `min_id`: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
||||
- `max_id`: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
||||
- `since_id`: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
||||
- `flags`: String (optional). Comma-separated list of flag types to filter by. Can be left out to return statuses with at least one flag
|
||||
- `flag_count`: Number (optional). Minimum number of flags to filter by
|
||||
- `account_id`: Array of strings (optional). Filters statuses by account ID
|
||||
|
||||
This method returns a `Link` header the same way Mastodon does, to allow for pagination.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
statuses: {
|
||||
status: Status,
|
||||
modnotes: ModNote[],
|
||||
flags: Flag[],
|
||||
}[],
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/moderation/accounts/modtags/search`
|
||||
|
||||
Allows moderators to search for accounts based on their modtags
|
||||
|
||||
Params:
|
||||
- `limit`: Number
|
||||
- `min_id`: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
||||
- `max_id`: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
||||
- `since_id`: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
||||
- `tags`: String (optional). Comma-separated list of tags to filter by. Can be left out to return accounts with at least one tag
|
||||
- `tag_count`: Number (optional). Minimum number of tags to filter by
|
||||
- `include_statuses`: Boolean (optional). If true, includes status tags in the search results
|
||||
- `account_id`: Array of strings (optional). Filters accounts by account ID
|
||||
|
||||
This method returns a `Link` header the same way Mastodon does, to allow for pagination.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
accounts: {
|
||||
account: User,
|
||||
modnotes: ModNote[],
|
||||
modtags: ModTag[],
|
||||
statuses?: {
|
||||
status: Status,
|
||||
modnotes: ModNote[],
|
||||
modtags: ModTag[],
|
||||
}[],
|
||||
}[],
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/v1/moderation/statuses/modtags/search`
|
||||
|
||||
Allows moderators to search for statuses based on their modtags
|
||||
|
||||
Params:
|
||||
- `limit`: Number
|
||||
- `min_id`: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
||||
- `max_id`: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
||||
- `since_id`: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
||||
- `tags`: String (optional). Comma-separated list of tags to filter by. Can be left out to return statuses with at least one tag
|
||||
- `tag_count`: Number (optional). Minimum number of tags to filter by
|
||||
- `account_id`: Array of strings (optional). Filters statuses by account ID
|
||||
- `include_statuses`: Boolean (optional). If true, includes status tags in the search results
|
||||
|
||||
This method returns a `Link` header the same way Mastodon does, to allow for pagination.
|
||||
|
||||
Output format:
|
||||
|
||||
```ts
|
||||
{
|
||||
statuses: {
|
||||
status: Status,
|
||||
modnotes: ModNote[],
|
||||
modtags: ModTag[],
|
||||
}[],
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue