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

There are three. All three share the same authentication and rate limiting.

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 is server-configurable and may expand over time). Max size: configurable server-side; 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.webp",
"src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
"direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
"expires_at": null
}}

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",
"expires_at": null,
"created_at": "2026-07-23T15:43:28+01:00"
}],
"meta": { "current_page": 1, "last_page": 1, "total": 1 }}

path, src, direct, and expires_at mean the same thing here as they do on the upload response above. 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. All three endpoints share the same limits - there's no extra cost for uploads versus lists or deletes.

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/MediaShareORG/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.0"}

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

Also listed on Smithery and Glama, if your MCP client installs from either 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 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"
# 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.

Firefox Extension

The YourImageShare Capture extension for 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 on desktop and Firefox for Android.

Get YourImageShare Capture for Firefox

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.

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 instructionsPunBB instructionsZetaBoards 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, not just new uploads
• Restore any offloaded file back to local storage at any time
• A Media Library column shows what's offloaded vs. still local

Download the plugin

Install via Plugins > Add New > Upload Plugin. Not yet on the WordPress.org Plugin Directory.

From the Blog