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 key the upload API uses, from 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, 2 to 32 characters from letters, digits, `-` and `_`. 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 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.
`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 requests.	30 links per minute. Back off and retry.
`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, where you can rename, disable or delete it.

Open short links