API Documentation: Upload via HTTP

Learn how to upload files to imageserver.pw using simple HTTP requests.

Quick Start

Get Your API Key

Find your key in the Dashboard under "User Key".

Send a POST Request

Upload to POST /api/v1/upload with your file as multipart/form-data.

Get Your Link

Receive a JSON response with your encrypted file URL.

Endpoint

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

Content-Type: multipart/form-data

Auth Header: X-IMAGESERVER-AUTH-KEY

Form Fields

Field	Required	Description
`file`	Yes	The file to upload
`color`	No	Embed color (hex), e.g. `#ef7c3b`
`title`	No	Embed title (default: `imageserver.pw`)
`urlStyle`	No	`embed` or `direct` — controls returned URL type
`domains`	No	JSON array of domains, e.g. `["default"]` or `["own"]`

Code Examples

Linux / macOS

curl -X POST \
  -H "X-IMAGESERVER-AUTH-KEY: YOUR_USER_KEY" \
  -F "file=@/path/to/image.png" \
  -F "urlStyle=embed" \
  -F "color=#ef7c3b" \
  https://imageserver.pw/api/v1/upload

Windows PowerShell

$headers = @{ "X-IMAGESERVER-AUTH-KEY" = "YOUR_USER_KEY" }
$form = @{
    file = Get-Item -Path "C:\path\to\image.png"
    urlStyle = "embed"
    color = "#ef7c3b"
}
Invoke-RestMethod -Uri "https://imageserver.pw/api/v1/upload" `
    -Method Post -Headers $headers -Form $form

Node.js / Browser

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('urlStyle', 'embed');
formData.append('color', '#ef7c3b');

const response = await fetch('https://imageserver.pw/api/v1/upload', {
    method: 'POST',
    headers: { 'X-IMAGESERVER-AUTH-KEY': 'YOUR_USER_KEY' },
    body: formData
});
const data = await response.json();
console.log(data.url);

Python 3 (requests)

import requests

url = "https://imageserver.pw/api/v1/upload"
headers = {"X-IMAGESERVER-AUTH-KEY": "YOUR_USER_KEY"}
files = {"file": open("/path/to/image.png", "rb")}
data = {"urlStyle": "embed", "color": "#ef7c3b"}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json()["url"])

Response

Success

{
  "url": "https://imageserver.pw/abc123.png?key=...",
  "deletionUrl": "https://imageserver.pw/delete/xyz789"
}

Error Codes

Code	Reason
`400`	Missing auth key or file
`401`	Invalid user key
`403`	Account suspended
`400`	Unsupported file type for your plan
`413`	File size exceeds your plan limit
`413`	Storage quota exceeded

ShareX Setup

Open ShareX → Destinations → Custom Uploader Settings
Create a new uploader with:
- URL: https://imageserver.pw/api/v1/upload
- Method: POST
- Body: Form data (multipart)
Add header: X-IMAGESERVER-AUTH-KEY: YOUR_KEY
Set file form name to file
URL field: $json:url$

Postman Setup

Create new request: POST https://imageserver.pw/api/v1/upload
Headers tab: Add X-IMAGESERVER-AUTH-KEY
Body tab → Select form-data
Add key file (type: File)
Add optional keys: urlStyle, color, etc.
Send and check JSON response

Encryption

All uploaded files are automatically encrypted at rest using AES-256. The decryption key is included in your file URL.

Learn more about how encryption works

Skip the API — Use Our Desktop Client

Take screenshots and upload them instantly with a single hotkey. No code required — just capture, upload, and share.

Global hotkey capture
Auto-copy link to clipboard
Region & fullscreen capture
Upload history

Download Client

Windows macOS Linux

Ready to Integrate?

Get your API key from the dashboard and start uploading.

Get Your API Key