ShareX

Custom Uploader

If you are new to automated screenshot sharing,how to upload screenshots automatically with ShareXwe recommend reviewing our guide on uploading screenshots automatically with ShareX before developing a custom uploader.

What Is a Custom Uploader?

ShareX includes a custom uploader system that enables users to send images, text, and files to various hosting services, or to shorten and share URLs. This functionality is primarily used by individuals who manage their own hosting solutions.

Exporting and Importing

You can export your custom uploader using the.sxcuextension. Other users can then import it by simply double-clicking the exported file.

If a destination type has been configured, ShareX can automatically select the imported custom uploader and update the current destination accordingly, removing the need for further user configuration.

Name

The NameThe field controls the name displayed in the custom uploaders list. This field is optional; if left blank, ShareX will automatically use the request URL's domain as the name. We suggest leaving this field empty unless you have multiple uploaders sharing the same domain.

For instance, if the request URL ishttps://example.com/upload.phpand the name field remains empty, thenexample.comwill appear in the list of custom uploaders.

Destination Type

The destination type takes effect when users import a custom uploader by double-clicking the file..sxcu file.

Method

The following HTTP request methods are available for use:

If the request has no body and relies solely on parameters, theGETmethod is the preferred choice. If the body containsForm data (multipart/form-data), then the POSTmethod should be used.

Request URL

This is the URL where the request will be sent.

Example: https://example.com/upload.php

URL Parameters

Parameters serve to construct a URL'squery string.

For text uploaders or URL shorteners, the {input}syntax can be used to provide the input text or URL as a value.

Dynamic values, such as%mofor retrieving the current month, are also supported.

For instance, if parameters are configured as follows:

Name Value
api_key eUM14R4g4pMS
private true

The query string will then be appended to the request URL when it is sent:

https://example.com/upload.php?api_key=eUM14R4g4pMS&private=true

Headers

Headers allow for transmitting additional information with the request. APIs frequently utilize headers for authorization purposes.

You can also override default request headers, for example:

Basic access authentication example:

Name Value
Authorization Basic {base64:USERNAME:PASSWORD}

Here's an API key example:

Name Value
api_key eUM14R4g4pMS

Body

The request body supports these types:

In most cases,No bodyis utilized alongside parameters whenever the API request method isGET. When the request method is POST, Form data (multipart/form-data)is frequently employed. This isn't always true, so consult the API documentation to confirm the request's specific expectations.

Body Parameters

For uploaders designed for text or URL shorteners, the{input}syntax can serve as a value for providing input text or a URL.

File Form Name

This particular field is only applicable whenBody is Form data (multipart/form-data).

For instance, consider the HTML excerpt<input type="file" name="file_image">, the file form name would befile_image.

URL

These text fields allow parsing URLs directly from the response. If the response contains only a URL, the URL text box can be left blank.

Be sure to also parse the error message, enabling ShareX to display an easy-to-understand error to the user.

Custom Uploader Syntax Rules

A specialized syntax is available to help achieve certain goals, such as extracting a URL from JSON responses.

This syntax is applicable in the following areas, with only a few exceptions:

For example, syntax designed to parse the response can only be used within URL sections.

Important: To use{, }, |, or \special characters within any syntax-enabled section, you must escape them using the\backslash. For instance:\{

A complete list of available syntax expressions, along with usage examples, is provided below.

response

Should the response contain only a file name or ID, this syntax allows you to prepend it with the domain.

If the response already includes a full URL, you won't need to use this syntax. An empty URL input box will automatically utilize the provided response.

Syntax:

{response}

Sample URL:

https://example.com/{response}

responseurl

This can retrieve the redirection URL. If no redirection takes place, it returns the original request URL.

Syntax:

{responseurl}

Sample URL:

{responseurl}

Use this to obtain the value of a specific response header.

Syntax:

{header:name}

Sample URL:

{header:location}

json

You can use JsonPathfor extracting a URL from aJSON 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 XPathfor extracting a URL from anXML 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 the response content is notJSON or XML, aregular expression (regex)can be employed to parse the text.

Remember to escape any special{, }, |, and \characters with a backslash when crafting a regex pattern.\.

Syntax:

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

Example:

{regex:(?<=href=").+(?=")}

Example using a group index:

{regex:href="(.+)"|1}

Example using a group name:

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

input

For a text custom uploader, this syntax is replaced by the text being uploaded. For URL shorteners or sharing services, it's replaced by the URL. It primarily serves as an argument value.

Syntax:

{input}

Example argument:

Name Value
text {input}

filename

This syntax will be substituted with the file name. In most multipart/form-data file uploads, this isn't necessary, as the file name is already part of the request.

Syntax:

{filename}

Example argument:

Name Value
title {filename}

random

This syntax allows you to utilize a different, randomly selected domain for each individual upload.

Syntax:

{random:value1|value2|value3}

For example, consider this URL:

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

select

A window will appear, presenting all available values as buttons, enabling you to dynamically select the desired text input. This approach is beneficial when managing multiple domains and needing to assign a specific one to each upload.

Syntax:

{select:value1|value2|value3}

For instance, this URL:

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

inputbox

An input box will be shown for the user to type text. This method is useful if the user needs to provide a unique value for an argument or URL segment with each upload.

The first parameter sets the window's title, and the second provides the default text for the input box. Both parameters are optional.

Syntax:

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

Here's an example URL:

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

outputbox

This will display an output box containing the specified text. It's useful for requests not involving an uploader, such as querying AI and viewing its response.

Syntax:

{outputbox:text}
{outputbox:title|text}

For example, this URL:

{outputbox:Result|{json:choices[0].message.content}}

base64

To encode text, use:Base64.

Syntax:

{base64:text}

Here is an example header:

Name Value
Authorization Basic {base64:username:password}

SXCU file

ShareX custom uploader (SXCU) files are fundamentally JSON files.

A typical JSON schema appears as follows:

{
  "Version": "17.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: