mirror of
https://github.com/versia-pub/server.git
synced 2025-12-06 16:38:19 +01:00
204 lines
4.4 KiB
Markdown
204 lines
4.4 KiB
Markdown
# Emoji API
|
|
|
|
This API allows users to create, read, update, and delete instance custom emojis.
|
|
|
|
The **Versia Server CLI** can also be used to manage custom emojis.
|
|
|
|
## Emoji
|
|
|
|
```typescript
|
|
type UUID = string;
|
|
type URL = string;
|
|
|
|
interface Emoji {
|
|
id: UUID;
|
|
shortcode: string;
|
|
url: URL;
|
|
static_url?: URL;
|
|
visible_in_picker: boolean;
|
|
category?: string;
|
|
}
|
|
```
|
|
|
|
## Create Emoji
|
|
|
|
```http
|
|
POST /api/v1/emojis
|
|
```
|
|
|
|
Upload a new custom emoji.
|
|
|
|
- **Returns:** [`Emoji`](#emoji)
|
|
- **Authentication:** Required
|
|
- **Permissions:** `owner:emoji`, or `emoji` if uploading a global emoji.
|
|
- **Version History**:
|
|
- `0.7.0`: Added.
|
|
|
|
### Request
|
|
|
|
- `shortcode` (string, required): The shortcode for the emoji.
|
|
- 1-64 characters long, alphanumeric, and may contain dashes or underscores.
|
|
- `element` (file/string, required): The image file to upload.
|
|
- Can be a URL, or a file upload (`multipart/form-data`).
|
|
- `alt` (string): Emoji alt text.
|
|
- `category` (string): Emoji category. Can be any string up to 64 characters long.
|
|
- `global` (boolean): If set to `true`, the emoji will be visible to all users, not just the uploader.
|
|
- Requires `emoji` permission.
|
|
|
|
#### Example
|
|
|
|
```http
|
|
POST /api/v1/emojis
|
|
Content-Type: application/json
|
|
Authorization: Bearer ...
|
|
|
|
{
|
|
"shortcode": "blobfox-coffee",
|
|
"element": "https://example.com/blobfox-coffee.png",
|
|
"alt": "My emoji",
|
|
"category": "Blobmojis"
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `201 Created`
|
|
|
|
Emoji successfully uploaded.
|
|
|
|
```json
|
|
{
|
|
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
|
|
"shortcode": "blobfox-coffee",
|
|
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"visible_in_picker": true,
|
|
"category": "Blobmojis"
|
|
}
|
|
```
|
|
|
|
## Get Emoji
|
|
|
|
```http
|
|
GET /api/v1/emojis/:id
|
|
```
|
|
|
|
Get a specific custom emoji.
|
|
|
|
- **Returns:** [`Emoji`](#emoji)
|
|
- **Authentication:** Required
|
|
- **Permissions:** `owner:emoji`, or `emoji` if viewing a global emoji.
|
|
- **Version History**:
|
|
- `0.7.0`: Added.
|
|
|
|
### Request
|
|
|
|
#### Example
|
|
|
|
```http
|
|
GET /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b
|
|
Authorization: Bearer ...
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `200 OK`
|
|
|
|
Custom emoji data.
|
|
|
|
```json
|
|
{
|
|
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
|
|
"shortcode": "blobfox-coffee",
|
|
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"visible_in_picker": true,
|
|
"category": "Blobmojis"
|
|
}
|
|
```
|
|
|
|
## Edit Emoji
|
|
|
|
```http
|
|
PATCH /api/v1/emojis/:id
|
|
```
|
|
|
|
Edit an existing custom emoji.
|
|
|
|
- **Returns:** [`Emoji`](#emoji)
|
|
- **Authentication:** Required
|
|
- **Permissions:** `owner:emoji`, or `emoji` if editing a global emoji.
|
|
- **Version History**:
|
|
- `0.7.0`: Added.
|
|
|
|
### Request
|
|
|
|
> [!NOTE]
|
|
> All fields are optional.
|
|
|
|
- `shortcode` (string): The shortcode for the emoji.
|
|
- 1-64 characters long, alphanumeric, and may contain dashes or underscores.
|
|
- `element` (file/string): The image file to upload.
|
|
- Can be a URL, or a file upload (`multipart/form-data`).
|
|
- `alt` (string): Emoji alt text.
|
|
- `category` (string): Emoji category. Can be any string up to 64 characters long.
|
|
- `global` (boolean): If set to `true`, the emoji will be visible to all users, not just the uploader.
|
|
- Requires `emoji` permission.
|
|
|
|
#### Example
|
|
|
|
```http
|
|
PATCH /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b
|
|
Content-Type: application/json
|
|
Authorization: Bearer ...
|
|
|
|
{
|
|
"category": "Blobfoxes"
|
|
}
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `200 OK`
|
|
|
|
Emoji successfully edited.
|
|
|
|
```json
|
|
{
|
|
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
|
|
"shortcode": "blobfox-coffee",
|
|
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
|
|
"visible_in_picker": true,
|
|
"category": "Blobfoxes"
|
|
}
|
|
```
|
|
|
|
## Delete Emoji
|
|
|
|
```http
|
|
DELETE /api/v1/emojis/:id
|
|
```
|
|
|
|
Delete an existing custom emoji.
|
|
|
|
- **Returns:** `204 No Content`
|
|
- **Authentication:** Required
|
|
- **Permissions:** `owner:emoji`, or `emoji` if deleting a global emoji.
|
|
- **Version History**:
|
|
- `0.7.0`: Added.
|
|
|
|
### Request
|
|
|
|
#### Example
|
|
|
|
```http
|
|
DELETE /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1
|
|
Authorization: Bearer ...
|
|
```
|
|
|
|
### Response
|
|
|
|
#### `204 No Content`
|
|
|
|
Emoji successfully deleted. |