Basics

When you upload an image you'll get a link like this:

https://pictshare.net/abcef123.jpg

You can modify the size of the image by adding a size parameter to the URL. For example this will render the image in 800x600:

https://pictshare.net/800x600/abcef123.jpg

If you want to force the size to really be 800x600, you can use the "forcesize" parameter. It will still keep the aspect ratio but zoom in as needed to fit the dimensions

https://pictshare.net/800x600/forcesize/abcef123.jpg

There are many more of these modifiers and even filters available

Basics

All API calls are done via GET or POST requests. The API will return JSON encoded data.

Base URL

https://pictshare.net/api

Error handling

When the status is err there will always be a field "reason" that explains what went wrong.

{
  "status": "err",
  "reason": "File not a valid image"
}
                    

Uploading an image

API call

/upload

You can post a file using the POST variable file

CURL example

curl -s -F "[email protected]" "https://pictshare.net/api/upload"

Output

{
  "status": "ok",
  "hash": "7eli4d.jpg",
  "filetype": "image/jpeg",
  "url": "http://localhost:8080/7eli4d.jpg",
  "delete_code": "jxgat3wze8lmn9sqwxy4x32p2xm7211g",
  "delete_url": "http://localhost:8080/delete_jxgat3wze8lmn9sqwxy4x32p2xm7211g/7eli4d.jpg"
}

Grabbing a URL

API call

/upload?url=url of image

You can specify a URL in the POST or GET variable url that the call will try to download and process.

CURL example

curl -s "https://pictshare.net/api/upload?url=https://pictshare.net/d2j1e1.png

Output

{
  "status": "ok",
  "hash": "ysj455.webp",
  "filetype": "image/webp",
  "url": "http://localhost:8080/ysj455.webp",
  "delete_code": "4l0w04l4s42xddt2s5mrj1wikxz11l5z",
  "delete_url": "http://localhost:8080/delete_4l0w04l4s42xddt2s5mrj1wikxz11l5z/ysj455.webp"
}

Uploading Base64 encoded content

It's also possible to upload supported files via Base64 strings by providing the base64 http parameter

API call

/upload/?base64=base64 encoded string

CURL example

(echo -n "base64="; echo -n "data:image/jpeg;base64,$(base64 -w 0 Screenshot3.jpg)") | curl --data @- https://pictshare.net/api/upload

Output

{
  "status": "ok",
  "hash": "5e6alk.jpg",
  "filetype": "image/jpeg",
  "url": "http://localhost:8080/5e6alk.jpg",
  "delete_code": "7ha2b5ccvsuvdd3qdnegzb2zqa9zxb5t",
  "delete_url": "http://localhost:8080/delete_7ha2b5ccvsuvdd3qdnegzb2zqa9zxb5t/5e6alk.jpg"
}

On-the-fly modifications to images

You can modify images on-the-fly (without saving them to the server) by specifying additional parameters in the API call to use Pictshare to "clean up" or "normalize" images uploaded to your app. The passthrough endpoint allows you to use the normal image modifiers in the URL. It won't save the image on the Server and will respond with the modified image directly.

API call

/passthrough/image/[modifiers]

For example to force an uploaded image to 400x400 and have it grayscale you can do this:

CURL example

curl -s -F "[email protected]" "https://pictshare.net/api/passthrough/image/400x400/forcesize/gray" > result.jpg

If the status code is anything other than "200", it will return an error message in JSON format.

{
    "status": "err",
    "reason": "Not a valid image"
}

If the status code is "200", it will return the modified image directly.

Creating an Album

Upload files first, then combine their hashes into an immutable gallery album.

API call

/album

POST the hashes[] array (one entry per file). All hashes must already exist on this server.

CURL example

curl -s -X POST \
  -d "hashes[]=7eli4d.jpg" \
  -d "hashes[]=5e6alk.jpg" \
  "https://pictshare.net/api/album"

Output

{
  "status": "ok",
  "hash": "a3f8c1d2.album",
  "url": "https://pictshare.net/a3f8c1d2.album",
  "count": 2,
  "delete_code": "jxgat3wze8lmn9sqwxy4x32p2xm7211g",
  "delete_url": "https://pictshare.net/delete_jxgat3wze8lmn9sqwxy4x32p2xm7211g/a3f8c1d2.album"
}

Basics

PictShare has a built-in Model Context Protocol server, so LLM agents (Claude Code, Claude Desktop, and any other MCP-capable client) can upload and manage files on this instance directly — no REST API glue code needed.

Endpoint

POST https://pictshare.net/mcp

Transport: Streamable HTTP.

This instance has no upload code set, so the MCP endpoint is open — same as the REST API.

Connecting a client

Claude Code

claude mcp add --transport http pictshare https://pictshare.net/mcp

Claude Desktop / generic JSON config

{
  "mcpServers": {
    "pictshare": {
      "type": "http",
      "url": "https://pictshare.net/mcp"    }
  }
}

Available tools

Once connected, an agent gets these tools:

• upload_from_url — download a public http(s) URL and store it (max 20 MB)
• upload_base64 — upload base64-encoded / data-URI content
• get_file_info — fetch metadata for an uploaded file
• delete_file — permanently delete a file using its delete code
• create_album — group existing files into an immutable album (max 200 hashes)
• transform_image — build a URL for an on-the-fly resized/filtered/rotated image

Tool failures come back as MCP tool errors with the same human-readable reasons the REST API uses.

Testing with curl

The endpoint speaks plain JSON-RPC 2.0, so it can be poked without an MCP client:

# 1. initialize — note the Mcp-Session-Id response header
curl -i -X POST https://pictshare.net/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. list tools (replace SESSION_ID with the header value from step 1)
curl -X POST https://pictshare.net/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Session-Id: SESSION_ID' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Full reference, including per-tool parameters and troubleshooting: rtfm/MCP.md