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