Shortener API

Turn a long URL into a short one, with a random code or a vanity code you pick, served from our domains or from one of yours.

Quick start

Grab your key

The same AUTH-Key the upload API uses, under Settings › Security in your dashboard.

POST the target

Send url to /api/v1/shorten.

Share the link

Clicks are counted and shown in the dashboard.

Endpoint

POST https://imageserver.pw/api/v1/shorten

Body as multipart/form-data, x-www-form-urlencoded or application/json

Auth header X-IMAGESERVER-AUTH-KEY

Rate limit 30 links per minute

Click counts live in the dashboard

Request fields

Field	Required	Description
`url`	yes	The destination. Must start with `http://` or `https://`. `input` is accepted as an alias, which is what ShareX sends.
`code`	no	Your own code, 5 to 32 characters from letters, digits, `-` and `_`. Codes shorter than 5 characters are part of a paid plan, down to a minimum of 2. Codes are stored and matched in lower case, so `MyLink` and `mylink` are the same code. Other characters are dropped rather than refused: `my link!` becomes `mylink`, so read the code back from the response. Omit it and you get a random 6 character code.
`domains`	no	Set to `own` to serve the link from one of your verified domains. Anything else falls back to a public one. Unlike the upload API this is a plain string, not a JSON array.
`userKey`	no	Your key as a body field, for clients that cannot set headers. The header takes precedence.

Reserved codes

Codes that collide with a real path on this site, such as admin, api, docs or dashboard, are rejected with a 409. Pick a different one, there is no way to claim them.

Examples

Linux, macOS, WSL

curl -X POST https://imageserver.pw/api/v1/shorten \
  -H "X-IMAGESERVER-AUTH-KEY: your-user-key" \
  -F "url=https://example.com/a/very/long/path" \
  -F "code=my-link"

Windows PowerShell

$headers = @{ "X-IMAGESERVER-AUTH-KEY" = "your-user-key" }
$body = @{
    url  = "https://example.com/a/very/long/path"
    code = "my-link"
}

$result = Invoke-RestMethod -Uri "https://imageserver.pw/api/v1/shorten" `
    -Method Post -Headers $headers -Body $body

$result.url

Node.js 18+ and browsers

const res = await fetch('https://imageserver.pw/api/v1/shorten', {
  method: 'POST',
  headers: {
    'X-IMAGESERVER-AUTH-KEY': 'your-user-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/a/very/long/path',
    code: 'my-link'
  })
});

const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.url, data.deletionUrl);

Python 3 with requests

import requests

response = requests.post(
    "https://imageserver.pw/api/v1/shorten",
    headers={"X-IMAGESERVER-AUTH-KEY": "your-user-key"},
    json={"url": "https://example.com/a/very/long/path", "code": "my-link"},
    timeout=30,
)

response.raise_for_status()
print(response.json()["url"])

Response

200 OK

{
  "url": "https://imageserver.pw/s/my-link",
  "deletionUrl": "https://imageserver.pw/s/delete/my-link?key=9f4…"
}

Short links live under /s/<code> and answer with a redirect to the target.
Opening the deletion URL asks you to confirm, then removes the link for good. It needs no auth key, so keep it to yourself.
The host depends on the domain that was picked. Use the returned URL rather than assembling your own.

Use it from ShareX

Import this under Destinations › Custom Uploader Settings, then select it in Destinations › URL shortener › Custom URL shortener. The Config Creator can fill your key in for you.

{
  "Version": "15.0.0",
  "Name": "imageserver.pw (shortener)",
  "DestinationType": "URLShortener",
  "RequestMethod": "POST",
  "RequestURL": "https://imageserver.pw/api/v1/shorten",
  "Body": "MultipartFormData",
  "Headers": {
    "X-IMAGESERVER-AUTH-KEY": "your-user-key"
  },
  "Arguments": {
    "url": "{input}"
  },
  "URL": "{json:url}",
  "ErrorMessage": "{json:error}"
}

Errors

Status	Message	What to do
`400`	Missing auth key or url.	Check the header name and that the field is called `url` or `input`.
`400`	Please provide a valid http:// or https:// URL.	Other schemes are refused. Include the protocol.
`400`	That link already points at this shortener.	Shortening one of our own links would build a loop, so point at the real target.
`400`	Custom codes are 2-32 characters.	Letters, digits, `-` and `_` only.
`402`	Codes shorter than 5 characters are part of a paid plan.	Use a code of 5 characters or more, or upgrade your plan. The response also carries `capability` and `upgradeUrl`, so your client can link straight there.
`401`	Invalid user key.	Copy the key again from the dashboard.
`403`	Your account is suspended.	Link creation stays disabled until that is lifted.
`409`	That code is taken or reserved.	Pick another one, or omit `code` for a random one.
`429`	Too many links created. Please wait a moment before trying again.	30 links per minute. Back off and retry.
`500`	Could not allocate a short code. Please try again.	Ten random codes in a row were taken. Rare; retry once.
`503`	No upload domain is available right now.	Temporary. If it persists, tell us on Discord.

All of these are JSON in the shape { "error": "..." }.

Your links, with click counts

Everything you create through the API shows up in the dashboard with its click count, where you can copy or delete it.

Open short links