API documentation

Upload, list and delete files in your Mewshot account from any app or script.

Authentication

Create a key on the API keys page (keys look like mw_…), then send it with every request in one of these ways:

• Header: X-API-Key: mw_YOUR_KEY
• Header: Authorization: Bearer mw_YOUR_KEY
• Form field: api_key=mw_YOUR_KEY

Identify your app (recommended)

Send these optional headers so the key's passport shows which app, system and machine it is used on. Users can then recognise and revoke a key per device.

X-Mewshot-App: windows-app          # or chrome-extension, my-script, …
X-Mewshot-App-Version: 1.4.0
X-Mewshot-OS: Windows 11
X-Mewshot-Device: DESKTOP-K3R9      # hostname or a user-chosen name

Alternatively a User-Agent in the form Mewshot-Windows/1.4.0 (Windows 11; DESKTOP-K3R9) is parsed the same way.

Endpoints

• POST /api/v1/upload.php — upload an image (multipart, field image)
• GET /api/v1/me.php — validate a key; returns the account and its plan (allowed file types, max file size, expiry)
• GET /api/v1/files.php?limit=50&offset=0 — list the account's files with counters
• POST /api/v1/delete.php — delete a file (code=XXXX)
• POST /api/v1/upload_init.php — start a direct multipart upload for audio/video (name, size, mime) → part URLs; PUT each part to its URL and keep the ETag
• POST /api/v1/upload_complete.php — finish (code, parts=[[n, etag]…]) or abort (action=abort&code=…)

Accepted formats: PNG, JPG, GIF, WebP · max 10 MB · 120 requests per key per hour.

Example — cURL

curl -X POST "https://mewshot.com/api/v1/upload.php" \
  -H "X-API-Key: mw_YOUR_KEY" \
  -H "X-Mewshot-App: my-script" \
  -F "image=@screenshot.png"

Example — JavaScript (extension / browser)

const form = new FormData();
form.append("image", blob, "screenshot.png");

const res = await fetch("https://mewshot.com/api/v1/upload.php", {
  method: "POST",
  headers: {
    "X-API-Key": "mw_YOUR_KEY",
    "X-Mewshot-App": "chrome-extension",
    "X-Mewshot-App-Version": chrome.runtime.getManifest().version
  },
  body: form
});
const data = await res.json();
console.log(data.upload.url);

Example — C# (Windows app)

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", "mw_YOUR_KEY");
http.DefaultRequestHeaders.Add("X-Mewshot-App", "windows-app");
http.DefaultRequestHeaders.Add("X-Mewshot-App-Version", "1.4.0");
http.DefaultRequestHeaders.Add("X-Mewshot-OS", Environment.OSVersion.VersionString);
http.DefaultRequestHeaders.Add("X-Mewshot-Device", Environment.MachineName);

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(pngBytes), "image", "screenshot.png");
var res  = await http.PostAsync("https://mewshot.com/api/v1/upload.php", form);
var json = await res.Content.ReadAsStringAsync();

Upload response

{
  "ok": true,
  "upload": {
    "code": "aB3xK9mQ",
    "url": "https://mewshot.com/i/aB3xK9mQ",
    "direct_url": "https://mewshot.com/raw/aB3xK9mQ",
    "download_url": "https://mewshot.com/raw/aB3xK9mQ?dl=1",
    "stats_url": "https://mewshot.com/file.php?c=aB3xK9mQ",
    "delete_token": "…",
    "size": 48231, "width": 1280, "height": 720,
    "expires_at": null, "claimed": true
  }
}

Files uploaded with a key belong to your account and never expire unless you set an expiry on the file page. Errors return {"ok": false, "error": "…"} with a matching status (401 bad/revoked key, 413 too large, 415 wrong type, 429 rate limited).

Connect flow for apps

When a user pastes a key into your app, call GET /api/v1/me.php. A 200 with user.email means "Connected as …"; a 401 means the key is wrong or was revoked from the website.