Custom uploader
Custom uploader system in ShareX let users to upload image/text/file to hosting services or shorten/share URL. This feature is mainly used by users who host their own hosting services.
You can export your custom uploader with .sxcu extension which allows users to just double click that file to be able to use custom uploader.
If destination type is configured then ShareX can also set this custom uploader as selected custom uploader and change current destination to this custom uploader, so users won't need any additional configuration to use it.
In custom uploaders list this name will be used. Name field is optional. When it is left empty ShareX will use request URL domain as name automatically. It is suggested to leave name field empty unless you have multiple uploaders which using same domain.
For example if request URL is https://example.com/upload.php and name field is empty, then example.com name will be used in custom uploaders list.
Destination type is used when users import custom uploader by double clicking the .sxcu file.
List of HTTP request methods available:
If request don't have body and only parameters gonna be used then GET method is preferred. If body is Form data (multipart/form-data) then POST method is preferred.
Request will be send to this URL.
Example: https://example.com/upload.php
Parameters will be used to create URL query string.
For text uploader or URL shortener {input} syntax can be used as value to supply input text or URL.
You can also use dynamic values like %mo to get current month etc.
For example if you set parameters like this:
| Name | Value |
|---|---|
| api_key | eUM14R4g4pMS |
| private | true |
Then query string will be appended to request URL like this when sending request:
https://example.com/upload.php?api_key=eUM14R4g4pMs&private=true
Headers can be used to pass additional information with request. Most of the time APIs use headers for authorization.
Default request headers can be overridden too like these:
Basic access authentication example:
| Name | Value |
|---|---|
| Authorization | Basic {base64:USERNAME:PASSWORD} |
API key example:
| Name | Value |
|---|---|
| api_key | eUM14R4g4pMS |
Supported request body types:
Most of the time if API request method is GET then No body will be used with parameters. If request method is POST then Form data (multipart/form-data) body. But this is not always the case so you must check API documentation to make sure what request expects.
For text uploader or URL shortener {input} syntax can be used as value to supply input text or URL.
This field can be only used when Body is Form data (multipart/form-data).
For example in this HTML code: <input type="file" name="file_image"> file form name is file_image.
These textboxes can be used to parse response to get URL result. If response only contains URL then no need to write anything to URL textbox.
Make sure to also parse error message so ShareX can show user friendly error message to users.
There is a special syntax you can use to accomplish some tasks, like parsing URL from JSON responses.
This syntax is usable in the following sections, with a few exceptions:
For example syntaxes which involves parsing response only usable in URL sections as expected.
Note: If you would like to use {, }, | or \ characters in any of syntax supported sections then you can escape them with \ character. For example: \{
You can find list of all available syntaxes with example usages at bottom.
If response only contains file name (or id) and if you would like to append it to domain then you can use this syntax.
But if response just contains full URL then you don't have to use this syntax because empty URL textbox will use response automatically.
Syntax:
{response}
Example URL:
https://example.com/{response}
Can be used to get redirection URL. If no redirection happened then it will be just request URL.
Syntax:
{responseurl}
Example URL:
{responseurl}
Can be used to get specific response header value.
Syntax:
{header:name}
Example URL:
{header:location}
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}
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}
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}
If you are using text custom uploader then this syntax will be replaced with text which you gonna upload, if it is URL shortener or URL sharing service then syntax will be replaced with URL. This syntax mainly used as argument value.
Syntax:
{input}
Example argument:
| Name | Value |
|---|---|
| text | {input} |
This syntax will be replaced with file name. Most of the time you don't need to use this syntax because when doing multipart/form-data file upload, file name already included in request.
Syntax:
{filename}
Example argument:
| Name | Value |
|---|---|
| title | {filename} |
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}
This will show window with all values as buttons. So you can select dynamically which text input to use. This syntax can be useful if you have multiple domains and would like to select specific domain each upload.
Syntax:
{select:value1|value2|value3}
Example URL:
https://{select:domain1.com|domain2.com|domain3.com}/{json:files[0].url}
This will show input box for user to input text. This syntax can be used if user prefer to write different value for argument or URL part each upload.
First parameter is window title, second parameter is default text for input box. Both parameter is optional.
Syntax:
{inputbox}
{inputbox:title}
{inputbox:title|default text}
Example URL:
https://{inputbox:Input subdomain|i}.example.com/{json:files[0].url}
Encode text to Base64.
Syntax:
{base64:text}
Example header:
| Name | Value |
|---|---|
| Authorization | Basic {base64:username:password} |
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: