Upload Custom Icon

Uploads a new icon for the currently authenticated user.

Query Parameters

• autoConvert (boolean): Resize and process the image. If omitted, the server will first convert the image to a 16×16 px size.

• filename (string): Overrides the stored base filename (extension is inferred from the uploaded file's MIME type).

Body

The request body should be a binary file:

• file (file): The image to upload. Accepted MIME types include image/png, image/jpeg, image/svg+xml, etc.

Image Restrictions

When autoConvert=true, the server will:

1. Resize (or crop/pad) the image to 16×16 px.

2. Adjust brightness; if it's above ⅔, scale it down.

3. Convert to PNG and return the processed buffer.

When autoConvert=false, the server will validate:

• Dimensions: Must be exactly 16×16 px.

• Formats allowed: Only png or gif are supported.

  • GIFs are accepted as-is.

  • For PNGs:

    • Must be 24-bit RGBA (srgb, four channels, hasAlpha, no indexed palette).

New Icon Upload

When you upload an icon that doesn't yet exist in the system, the response includes a new: true flag:

{
  "displayIcon": {
        "mediaId": "XBkuY6DBFn5iRfFS6nV6CTWaCrEvBOOX8nzV9Y64h8I",
        "userId": "auth0|userHash",
        "displayIconId": "683736c62fd7c5cd177d206f",
        "url": "https://media-secure.aws.com/icons/mlWc6s-JG",
        "new": true
    }
}

The displayIcon object contains the following properties:

• mediaId (string): A unique identifier for the underlying icon file

• userId (string): The ID of the user who uploaded this icon

• displayIconId (string): Unique identifier for the icon

• url (string): A publicly accessible icon URL

• new (boolean): Always true in this case, indicating a fresh upload

Re-upload of an Existing Icon

If you upload an icon that already exists, the response omits new and returns the existing record (note url is an empty object here):

{
    "displayIcon": {
        "_id": "68sdds2fd7c5cd177d206f",
        "mediaId": "XBkuYsdaFn5iRfFS6nV6CTWaCrEv",
        "userId": "auth0|userHash",
        "createdAt": "2025-05-28T16:16:06.451Z",
        "displayIconId": "68sdds2fd7c5cd177d206f",
        "url": {}
    }
}

The displayIcon object contains the following properties:

• _id (string): Unique identifier for the icon

• mediaId (string): A unique identifier for the underlying icon file

• userId (string): The ID of the user who uploaded this icon

• createdAt (string, ISO 8601): UTC timestamp when this icon record was created

• displayIconId (string): The same ID as _id, returned for API consistency

• url (string): An empty object {} indicating that no new URL was generated because the icon already exists.

Required Scope

user:icons:manage