API Documentation

Getting an API Key

Sign in, go to My account, and open the API tab. Your key is shown there, along with a Regenerate button. Regenerating a key invalidates the old one immediately, so update anywhere it's in use before you click it.

That tab also has a second, independent Upload-only key - see the tip below and Forum Plugins for when to use it instead.

Authentication

Send your key as a header - preferred, since query strings tend to end up in access logs, proxy logs, and Referer headers:

X-API-Key: YOUR_API_KEY

A ?key= query parameter also works, kept for compatibility with older integrations and quick one-off curl commands. If both are present, the header wins.

?key=YOUR_API_KEY

Endpoints

Upload, list and delete share the same authentication and rate limiting; large files can be sent in pieces first.

POST /api - Upload a File

Uploads a single file for the authenticated account.

Accepted types: JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC, or HEIF images; MP4, WEBM, or AVI video (exact list may expand over time). HEIC/HEIF and TIFF are stored as WebP, video other than MP4/WebM is converted to MP4, and larger JPEG/PNG images are converted to WebP shortly after upload when that makes them noticeably smaller. Max size: 200MB; oversized or unreadable files are rejected with a 422.

Response - 200 OK:

{
  "type": "success",
  "msg": "success",
  "data": {
    "id": "aB3xY9qRz1",
    "type": "image",
    "path": "https://i.yourimageshare.com/aB3xY9qRz1.png",
    "src": "https://yourimageshare.com/ib/aB3xY9qRz1.png",
    "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
    "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
    "width": 1920,
    "height": 1080,
    "size": 482113,
    "locked": false,
    "visibility": "unlisted",
    "title": null,
    "description": null,
    "expires_at": null,
    "duplicate": false,
    "delete_url": "https://yourimageshare.com/delete#iV3x...k9"
  }
}

POST /api/chunk - Large Files

A single request can carry at most 100MB. For bigger files (up to 200MB), or to keep each request small on a slow connection, send the file in pieces of at most 5MB, then finish with POST /api:

1. Pick an upload id: 32 random hex characters.
2. For each piece, POST /api/chunk (multipart/form-data) with upload_id, index (0-based), total (number of pieces) and the bytes in chunk. The answer is {"type": "success", "chunk_size": 5242880}.
3. POST /api with upload_id and filename instead of uploads, plus any other upload field. The answer is the normal upload response.

Pieces of an upload that isn't finished are deleted after 2 hours. Only the finishing POST /api counts toward the upload rate limits.

GET /api/{id} and PATCH /api/{id} - One Upload

GET returns one of your uploads with the same fields as the list below. PATCH changes its visibility, title or description (form fields or JSON; an empty title or description clears it) and answers with the updated upload. Both need the full API key; 404 if there's no such upload on your account.

curl -X PATCH https://yourimageshare.com/api/aB3xY9qRz1 \
  -H "X-API-Key: YOUR_API_KEY" -d visibility=public -d title="Sunset"

POST /api/{id}/replace - Replace the File

Swaps the file behind one of your uploads and keeps its id, page and every link. Any allowed type works, even a different one (an image can become a video). Send the new file as uploads (or upload_id of a file sent in pieces with POST /api/chunk); keep_original works as on upload. The new file gets the same checks and conversions as a new upload, and the previous version is removed. Needs the full API key; 404 if there's no such upload on your account, 409 if it is password-protected or view-limited.

curl -X POST https://yourimageshare.com/api/aB3xY9qRz1/replace \
  -H "X-API-Key: YOUR_API_KEY" -F [email protected]

GET /api - List Your Uploads

Returns a paginated list of the authenticated account's uploads (from any source - API, website, or editor), newest first, 50 per page.

Response - 200 OK:

{
  "type": "success",
  "data": [
    {
      "id": "aB3xY9qRz1",
      "type": "image",
      "title": null,
      "path": "https://i.yourimageshare.com/aB3xY9qRz1.webp",
      "src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
      "direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
      "thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
      "width": 1920,
      "height": 1080,
      "size": 482113,
      "locked": false,
      "visibility": "unlisted",
      "description": null,
      "expires_at": null,
      "created_at": "2026-07-23T15:43:28+01:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

The fields mean the same thing here as they do on the upload response above (for a password-protected upload, path and thumb are short-lived signed links). There's no single "get one upload" endpoint yet, so this list is also the way to look up a file's id after the fact.

DELETE /api/{id} - Delete an Upload

Permanently deletes one of the authenticated account's uploads. This cannot be undone from the API. {id} is the value returned as id by the upload or list endpoints.

Response - 200 OK:

{ "type": "success", "msg": "Deleted." }

404 if no upload with that id exists on your account (either it was never yours, or it's already been deleted).

Rate Limits

Each API key has independent per-minute and per-day quotas, plus a coarser per-IP daily ceiling as a backstop against one IP cycling through multiple keys. Uploads, lists and deletes share the same limits.

These limits may change. Every response includes standard rate-limit headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14

A 429 is returned once a limit is exceeded, with a Retry-After header telling you how many seconds to wait.

Errors

Every error response uses the same shape, regardless of endpoint or cause:

{ "type": "error", "errors": "A human-readable description of what went wrong." }

Client Libraries

Official SDKs that wrap the endpoints above with typed results and raise on API errors instead of raw HTTP handling.

JavaScript / TypeScript

Zero dependencies, works in Node.js and browsers. Also on JSR as @yourimageshare/yourimageshare - npx jsr add @yourimageshare/yourimageshare - same source, published as TypeScript directly.

npm install yourimageshare

Python

One dependency (requests), Python 3.8+.

pip install yourimageshare

PHP

Zero Composer dependencies (uses PHP's own curl extension), PHP 7.4+. Source on GitHub.

composer require yourimageshare/yourimageshare-php

Go

Zero dependencies (standard library only), Go 1.18+. See pkg.go.dev for full reference docs.

go get github.com/yourimageshare/yourimageshare/go

Rust

Two dependencies (ureq for blocking HTTP - no async runtime pulled in - plus serde), Rust 1.70+. Source on GitHub.

cargo add yourimageshare

Ruby

Zero gem dependencies (stdlib Net::HTTP + json), Ruby 2.7+. Source on GitHub.

gem install yourimageshare

.NET

One dependency (Microsoft's own System.Text.Json), targets netstandard2.0 so it works from both .NET Framework and modern .NET. Source on GitHub. Built and verified against this live API; publishing to NuGet shortly.

dotnet add package YourImageShare

Dart / Flutter

One dependency (http, the Dart team's own package), Dart 2.17+. Source on GitHub. Built and verified against this live API; publishing to pub.dev shortly.

dart pub add yourimageshare

Elixir

One dependency (Req), Elixir 1.14+. Returns {:ok, result}| {:error, reason} tagged tuples - the direct equivalent of this API's error handling in every other SDK - plus bang variants that raise. Source on GitHub, docs on HexDocs.

{:yourimageshare, "~> 1.1"}

MCP Server

For AI coding agents (Claude Code, Cursor, and other MCP-compatible tools) - paste a screenshot into a bug report, a PR description, or a support thread as a real URL instead of a base64 blob or a manual upload step. Works the same way with Claude Desktop and any other MCP client. Run directly with npx, no install step:

npx yourimageshare-mcp

Tools: upload_image (a local file, inline content or a link, up to 200MB, with optional visibility, title and auto-delete), list_uploads, get_upload, update_upload and delete_upload.

Also in the official MCP Registry (as io.github.yourimageshare/yourimageshare) and listed on Smithery and Glama, if your MCP client installs from one of those instead.

New to MCP? See how to connect Claude and ChatGPT to this API over MCP for a full setup walkthrough.

Code Examples

curl

# Upload a file
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg"

# Upload from a link (files up to 200MB; one direct upload request stops at 100MB -
# bigger files go in pieces, see Large Files above)
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "url=https://example.com/video.mp4"

# Upload a file that auto-deletes after 1 hour
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "expires_in=3600"

# List uploads
curl "https://yourimageshare.com/api" -H "X-API-Key: YOUR_API_KEY"

# Upload a file without a page of its own (file only) and give it a title
curl "https://yourimageshare.com/api" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "uploads=@/path/to/photo.jpg" \
  -F "visibility=private" \
  -F "title=Sunset"

# Look up one upload, then make it public
curl "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"
curl -X PATCH "https://yourimageshare.com/api/aB3xY9qRz1" \
  -H "X-API-Key: YOUR_API_KEY" -d "visibility=public"

# Delete an upload
curl -X DELETE "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"

JavaScript (fetch)

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://yourimageshare.com/api';

async function uploadFile(file) {
  const form = new FormData();
  form.append('uploads', file);

  const res = await fetch(BASE, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: form,
  });
  const json = await res.json();
  if (json.type !== 'success') throw new Error(json.errors);
  return json.data;
}

async function listUploads(page = 1) {
  const res = await fetch(`${BASE}?page=${page}`, {
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

async function deleteUpload(id) {
  const res = await fetch(`${BASE}/${id}`, {
    method: 'DELETE',
    headers: { 'X-API-Key': API_KEY },
  });
  return res.json();
}

Python (requests)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://yourimageshare.com/api"

HEADERS = {"X-API-Key": API_KEY}

# Upload a file
with open("/path/to/photo.jpg", "rb") as f:
    res = requests.post(BASE, headers=HEADERS, files={"uploads": f})
res.raise_for_status()
upload = res.json()["data"]

# List uploads
res = requests.get(BASE, headers=HEADERS, params={"page": 1})
uploads = res.json()

# Delete an upload
res = requests.delete(f"{BASE}/{upload['id']}", headers=HEADERS)

PHP (curl)

<?php

$apiKey = 'YOUR_API_KEY';
$base = 'https://yourimageshare.com/api';

// Upload a file
$curl = curl_init($base);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
    CURLOPT_POSTFIELDS => ['uploads' => new CURLFile('/path/to/photo.jpg')],
    CURLOPT_RETURNTRANSFER => true,
]);
$upload = json_decode(curl_exec($curl), true)['data'];
curl_close($curl);

// List uploads
$curl = curl_init("$base?page=1");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$uploads = json_decode(curl_exec($curl), true);
curl_close($curl);

Go (net/http)

The official Go SDK above wraps this for you - this raw version is here for anyone who'd rather not add the dependency.

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

const apiKey = "YOUR_API_KEY"
const base = "https://yourimageshare.com/api"

func uploadFile(path string) (map[string]any, error) {
    file, err := os.Open(path)
    if err != nil {
        return nil, err
    }
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("uploads", path)
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", base, body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("X-API-Key", apiKey)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    var result map[string]any
    json.NewDecoder(res.Body).Decode(&result)
    return result, nil
}

Screenshot Tools

A browser extension plus ready-made configs and scripts to send screenshots straight to YourImageShare, no manual upload required. Each one uploads through the same /api endpoint documented above.

Browser Extension (Chrome & Firefox)

The YourImageShare Capture extension for Chrome and Firefox skips scripts and config files entirely. It captures the visible area, a drag-selected region, or a full scrolling page, opens a built-in editor for arrows, text, blur/redact and other annotations, then downloads the result, copies it to your clipboard, or publishes it straight to YourImageShare with one click. Publishing uses the same /api endpoint documented above - add your API key once under the extension's Settings and every publish from then on returns a shareable link immediately. Works in desktop Chrome (and other Chromium browsers), desktop Firefox and Firefox for Android.

Get YourImageShare Capture for Firefox Get YourImageShare Capture for Chrome

ShareX

Download the custom uploader below, then in ShareX go to Destinations > Custom uploader settings > Import > from file, open the downloaded .sxcu, and replace YOUR_API_KEY in the Headers field with your real key. Set it as your image/file destination and captures upload automatically.

Download YourImageShare.sxcu

Flameshot (Linux)

A small shell script that runs flameshot gui, uploads the capture, and copies the link to your clipboard. Bind it to a keyboard shortcut in your desktop environment in place of Flameshot's default one.

Download yis-flameshot-upload.sh

# One-time setup
chmod +x yis-flameshot-upload.sh
export YIS_API_KEY="YOUR_API_KEY"   # or add to ~/.config/yourimageshare/api_key

# Then bind this to a hotkey instead of calling flameshot directly:
/path/to/yis-flameshot-upload.sh

Greenshot (Windows)

A PowerShell script for Greenshot's built-in External command destination. Compatible with the Windows PowerShell 5.1 that ships with Windows, no extra install needed.

Download yis-greenshot-upload.ps1

# One-time setup
setx YIS_API_KEY "YOUR_API_KEY"

# In Greenshot: Preferences > Destinations > External command > Settings
#   Command:   powershell.exe
#   Arguments: -ExecutionPolicy Bypass -File "C:\path\to\yis-greenshot-upload.ps1" "%1"

Forum Plugins

Add a real "Upload Image" button next to your forum's post editor. Each one uploads through the same /api endpoint documented above and inserts BBCode at your cursor - no separate tab, no manual copy-paste.

Forum uploads are private by default: the image works in the post, but YourImageShare gives it no page of its own (no comments, reactions or ads). Each plugin has a setting to switch to unlisted if you'd also like a page for anyone with the link.

phpBB

A real phpBB 3.2/3.3 extension. Unzip into ext/, enable it under Customise > Manage extensions, then replace YOUR_UPLOAD_ONLY_KEY in the extension's template event file with your real upload-only key.

Download for phpBB

SMF (Simple Machines Forum)

A real SMF package - install via Admin > Package Manager, then replace YOUR_UPLOAD_ONLY_KEY in Sources/yis_forumupload.php with your real upload-only key.

Download for SMF

MyBB

A real MyBB 1.8 plugin. Copy into inc/plugins/, activate under Configuration > Plugins, then replace YOUR_UPLOAD_ONLY_KEY in the plugin file with your real upload-only key.

Download for MyBB

FluxBB, PunBB & ZetaBoards

These don't have a formal plugin system, so it's a small snippet pasted directly into your template (FluxBB/PunBB) or Admin CP (ZetaBoards) - full copy-paste instructions for each:

FluxBB instructions PunBB instructions ZetaBoards instructions

WordPress Plugin

Offload your Media Library to YourImageShare instead of local disk. New image/video uploads go through the same /api endpoint documented above automatically, the local file (and every generated thumbnail size) is deleted once the upload is confirmed, and every WordPress attachment URL - the block editor, featured images, galleries, REST API - resolves to the YourImageShare-hosted file. No shortcode, no workflow change.

• Bulk-offload an existing Media Library in the background (or with wp yis offload --all), not just new uploads
• Images and videos already placed in posts keep working after their local files are removed
• Thumbnails and srcset use our 280px thumbnail, so small image slots don't load full-size files
• Files up to 200MB, sent in pieces so big videos never strain a shared host
• Restore any offloaded file back to local storage at any time
• A Media Library column shows what's offloaded vs. still local
• Offloaded files are stored as private: they load wherever your site uses them, but get no page of their own on YourImageShare

Get it on WordPress.org Download the ZIP

In WordPress: Plugins > Add New, search for YourImageShare Media Offload, then Install and Activate.

Telegram Bot

Get a link for a photo, video or GIF without leaving Telegram. Send it to @YourImageShare_bot and the link comes straight back - no account and no API key needed. The bot uploads through the same /api endpoint documented above.

• Send a photo, video, GIF or an image or video file; an album of up to 10 comes back in one reply
• In a group, reply /link to a photo or video and the bot posts its link for everyone
• /autodelete makes your next uploads delete themselves after 1 hour, 1 day, 1 week or 30 days
• Every result has a Delete button that only works for the person who uploaded the file
• Links are unlisted: only people who have the link can see the file
• The bot answers in your Telegram language when the site is available in it

Open @YourImageShare_bot in Telegram

From the Blog