ShareX

Custom uploader

What is custom uploader?

The custom uploader system in ShareX enables users to upload images, text, or files to hosting services, or to shorten and share URLs. This functionality is particularly valuable for users who manage their own hosting services.

Export / Import

Users can export their custom uploader configurations with the .sxcu extension. This allows for convenient usage by simply double-clicking the file. Additionally, if a destination type is specified, ShareX can automatically select the custom uploader and update the current destination accordingly. This streamlined process eliminates the need for users to perform additional configurations to utilize the custom uploader.

Name

The name specified in the custom uploader list will be utilized for identification. While this field is optional, leaving it empty prompts ShareX to automatically assign the request URL domain as the name. It’s recommended to omit the name unless multiple uploaders share the same domain.

For instance, if the request URL is https://example.com/upload.php and the name field is empty, ShareX will display “example.com” in the custom uploaders list.

Destination type

The destination type serves a crucial

Method

List of HTTP request methods available:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

When a request doesn’t include a body and only parameters are utilized, the GET method is preferable. Conversely, if the request body consists of Form data (multipart/form-data), then the POST method is preferred.

URL parameters

arameters are employed to construct the URL query string.

For text uploader or URL shortener, the {input} syntax can be utilized as the value to provide input text or URL. Additionally, dynamic values such as %mo can be used to obtain the current month, and so forth.

For instance, if parameters are configured like this:

Name                 Value
api_key              eUM14R4g4pMS
private true

When sending the request, the query string will be appended to the request URL as follows:

Headers

Headers serve to transmit supplementary information along with the request, commonly employed for authorization within APIs.

Default request headers can also be overwritten, such as these:

  • Accept
  • Content-Length
  • Content-Type
  • Cookie
  • Referer
  • User-Agent

example:

Name                                 Value
Authorization                    Basic {base64:USERNAME:PASSWORD}

Name                                Value
api_key                             eUM14R4g4pMS

Body

Supported request body types:

  • No body
  • Form data (multipart/form-data)
  • Form URL encoded (application/x-www-form-urlencoded)
  • JSON (application/json)
  • XML (application/xml)
  • Binary

In most cases, if the API request method is GET, parameters will be appended to the URL query string and no body will be used. Conversely, if the request method is POST, a Form data (multipart/form-data) body is typically employed. However, it’s essential to consult the API documentation to confirm the specific requirements of the request.

Body arguments

To provide input text or a URL for a text uploader or URL shortener, you can utilize the {input} syntax as the value.

File form name

This field can only be utilized when the Body is Form data (multipart/form-data).

For instance, in this HTML code snippet: <input type=”file” name=”file_image”>, the form field name is “file_image”.

URL

  • URL
  • Deletion URL
  • Thumbnail URL
  • Error message

The textboxes provided can be used to parse the response and retrieve the URL result. If the response solely contains a URL, there’s no need to enter anything into the URL textbox.

Additionally, ensure that error messages are parsed as well, enabling ShareX to display user-friendly error messages to users.

Custom uploader syntax

There exists a special syntax that facilitates certain tasks, such as extracting URLs from JSON responses. This syntax can be applied in various sections, with a few exceptions:

  • Request URL
  • Parameter value
  • Header value
  • Body argument value
  • URL
  • Thumbnail URL
  • Deletion URL
  • Error
  • message

For instance, syntaxes involving parsing responses are only functional in URL sections, as anticipated.

Note: To use special characters like {, }, |, or \ in any supported syntax section, you can escape them with the \ character. For example: {

A comprehensive list of all available syntaxes, along with example usages, can be found at the bottom.

response

If the response solely contains a file name (or ID) and you wish to append it to the domain, you can employ this syntax. However, if the response already includes the full URL, utilizing this syntax is unnecessary since the response will automatically populate the URL textbox when left empty.

Syntax:

{response}

Example URL:

https://example.com/{response}

responseurl

Can be used to get redirection URL. If no redirection happened then it will be just request URL.

Syntax:

{responseurl}
Example URL:

{responseurl}

header

Can be used to get specific response header value.

Syntax:

{header:name}
Example URL:

{header:location}

json

You can use JsonPath to parse URL from JSON response.

Syntax:

{json:jsonPath}
{json:input|jsonPath}
Example:

{
“status”: 200,
“data”: {
“link”: “https:\/\/example.com\/image.png”
}
}
{json:data.link}
Example 2:

{
“success”: true,
“files”: [
{
“name”: “image.png”,
“url”: “https://example.com/image.png”
}
]
}
{json:files[0].url}

xml

You can use XPath to parse URL from XML response.

Syntax:

{xml:xpath}
{xml:input|xpath}
Example:

<?xml version=”1.0″ encoding=”UTF-8″?>
<files>
<file>
       <name>image.png</name>
<url>https://example.com/image.png</url>
</file>
</files>
{xml:/files/file[1]/url}

regex

If response is not JSON or XML then you can use Regular expression (Regex) to parse response text.

While writing regex pattern don’t forget to escape {, }, |, \ characters with \.

Syntax:

{regex:regexPattern}
{regex:regexPattern|groupIndex}
{regex:regexPattern|groupName}
{regex:input|regexPattern|groupIndex}
{regex:input|regexPattern|groupName}
Example:

{regex:(?<=href=”).+(?=”)}
Example with group index:

{regex:href=”(.+)”|1}
Example with group name:

{regex:href=”(?<url>.+)”|url}
input

If you’re utilizing a text custom uploader, this syntax will be substituted with the text you intend to upload. Alternatively, if it’s a URL shortener or URL sharing service, the syntax will be replaced with the URL. This syntax is primarily employed as an argument value.

Syntax:

{input}
Example argument:

Name     Value
text        {input}

filename

This syntax will be substituted with the file name. In most cases, using this syntax is unnecessary because when performing a multipart/form-data file upload, the file name is already included in the request.

Syntax:

{filename}
Example argument:

Name       Value
title          {filename}

random

If you would like to use random domain each upload you can use this syntax.

Syntax:

{random:value1|value2|value3}
Example URL:

https://{random:subdomain1|subdomain2}.{random:domain1|domain2|domain3}.com/{json:files[0].url}

select

This syntax will display a window with all values as buttons, enabling dynamic selection of the text input to use. It can be particularly useful when dealing with multiple domains and you need to select a specific domain for each upload.

Syntax:

{select:value1|value2|value3}
Example URL:

https://{select:domain1.com|domain2.com|domain3.com}/{json:files[0].url}

inputbox

This syntax will present an input box for the user to input text. It’s handy if the user prefers to specify a different value for the argument or URL part with each upload.

The first parameter represents the window title, while the second parameter denotes the default text for the input box. Both parameters are optional.

Syntax:

{inputbox}
{inputbox:title}
{inputbox:title|default text}
Example URL:

https://{inputbox:Input subdomain|i}.example.com/{json:files[0].url}

base64

Encode text to Base64.

Syntax:

{base64:text}
Example header:

Name Value
Authorization Basic {base64:username:password}

SXCU file

ShareX custom uploader (SXCU) files are JSON files at their core.

Example JSON schema looks like this:

{
“Version”: “14.0.0”,
“Name”: “Example”,
“DestinationType”: “ImageUploader, TextUploader, FileUploader”,
“RequestMethod”: “POST”,
“RequestURL”: “https://example.com/upload.php”,
“Parameters”: {
“Parameter1”: “Value1”,
“Parameter2”: “Value2”,
“Parameter3”: “Value3”
},
“Headers”: {
“Header1”: “Value1”,
“Header2”: “Value2”,
“Header3”: “Value3”
},
“Body”: “MultipartFormData”,
“Arguments”: {
“Argument1”: “Value1”,
“Argument2”: “Value2”,
“Argument3”: “Value3”
},
“FileFormName”: “file”,
“URL”: “{json:url}”,
“ThumbnailURL”: “{json:thumbnail_url}”,
“DeletionURL”: “{json:deletion_url}”,
“ErrorMessage”: “{json:error}”
}
Enums:

  • DestinationType
  • None
  • ImageUploader
  • TextUploader
  • FileUploader
  • URLShortener
  • URLSharingService
  • RequestMethod
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • Body
  • None
  • MultipartFormData
  • FormURLEncoded
  • JSON
  • XML