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.

Responses

200

Content-Type: application/json

SchemaJSON

No schema available for this response.

No example response provided in the API specification.

Parameters

Query Parameters

autoConvert

Type

string

filename

Type

string

POST

/media/displayIcons/user/me/upload

Server URL:https://api.yotoplay.com

Authorization

bearerAuth

Token

Query Parameters

KEY	VALUE
autoConvert
filename

Request Body

Try it out

Samples

cURLJavaScriptPHPPython

Copy

curl "https://api.yotoplay.com/media/displayIcons/user/me/upload"
--header "Authorization: Bearer [YOUR_TOKEN]"

Copy

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer [YOUR_TOKEN]'
  }
};

fetch('https://api.yotoplay.com/media/displayIcons/user/me/upload', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.yotoplay.com/media/displayIcons/user/me/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer [YOUR_TOKEN]"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Copy

import requests

url = "https://api.yotoplay.com/media/displayIcons/user/me/upload"

headers = {
    'Authorization: Bearer [YOUR_TOKEN]'
}

response = requests.request("POST", url, headers=headers)

print(response.text)