# Emoji

Custom emoji management system for the platform. Supports creating, uploading, importing/exporting, searching, and deleting custom emojis. Emojis are automatically resized and optimized. Admin-only operations require Emojis.Manage permission.

## Get emojis by shortcodes or categories

 - [GET /api/v1/custom_emojis](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis/get.md): Retrieves emojis by exact shortcodes and/or by exact categories from cache. Multiple values can be requested in a single call using comma separation. If both parameters are provided, the union of results is returned. Returns paginated response with items (current page results), total (count matching filter), and totalItems (total emojis in system).

## Delete emojis

 - [DELETE /api/v1/custom_emojis](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis/delete.md): Deletes custom emojis by shortcode or category. Can delete multiple emojis at once using comma-separated values. Either shortcode or category must be provided. Returns the count of deleted emojis. Requires Emojis.Manage permission (admin only).

RBAC: requires Emojis.Manage

## Create emoji from URL

 - [POST /api/v1/custom_emojis](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis/post.md): Creates a custom emoji by downloading from provided URLs. The emoji file is downloaded, processed, and stored locally. Supports overwriting existing emojis with the same shortcode. Can specify category, visibility, and domain for federated emojis. Requires Emojis.Manage permission (admin only).

RBAC: requires Emojis.Manage

## List custom emoji categories

 - [GET /api/v1/custom_emojis/categories](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1categories/get.md): Returns distinct non-empty categories. Supports optional query and pagination.

RBAC: requires Emojis.Manage

## Export emojis to ZIP

 - [GET /api/v1/custom_emojis/export](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1export/get.md): Exports emojis from a specific category as a ZIP archive. The ZIP contains all emoji files from the specified category. Useful for backup or migration purposes. Returns 404 if no emojis found in the category. Requires Emojis.Manage permission (admin only).

RBAC: requires Emojis.Manage

## Bulk import emojis from ZIP

 - [POST /api/v1/custom_emojis/import](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1import/post.md): Imports multiple emojis from a ZIP archive. Filenames (without extension) become emoji shortcodes. All imported emojis share the same category and visibility settings. Images are automatically resized to 128x128 if larger. Animated GIFs are preserved with static versions generated. Supports batch overwriting of existing emojis. Requires Emojis.Manage permission (admin only).

RBAC: requires Emojis.Manage

## Bulk import emojis from ZIP upload

 - [POST /api/v1/custom_emojis/import/upload](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1import~1upload/post.md): Imports multiple emojis from a ZIP archive that was previously uploaded via /uploads. Filenames (without extension) become emoji shortcodes. All imported emojis share the same category and visibility settings. Images are automatically resized to 128x128 if larger. Animated GIFs are preserved with static versions generated. Supports batch overwriting of existing emojis.

RBAC: requires Emojis.Manage

## Search emojis by partial shortcode or category

 - [GET /api/v1/custom_emojis/search](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1search/get.md): Searches for emojis whose shortcodes or categories contain provided substrings. Useful for autocomplete functionality. Multiple searches can be performed in one request by passing comma-separated values. If no parameters provided, returns all emojis from cache. Returns paginated response with items (current page results), total (count matching filter), and totalItems (total emojis in system).

## Upload emoji from existing upload

 - [POST /api/v1/custom_emojis/upload](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1upload/post.md): Processes an existing upload (created via /uploads) as a custom emoji. Clients must first create an upload and PUT the file to the returned URL, then call this endpoint with the uploadId.

RBAC: requires Emojis.Manage

## Partially update emoji metadata

 - [PATCH /api/v1/custom_emojis/{shortcode}](https://docs.wellesley.social/openapi/emoji/paths/~1api~1v1~1custom_emojis~1%7Bshortcode%7D/patch.md): Updates emoji metadata fields without requiring file upload. Supports updating category, visibility and domain. Requires Emojis.Manage permission.

RBAC: requires Emojis.Manage