# imagebin.ca — full documentation


---

---
title: "Developer docs — imagebin.ca"
source: "https://imagebin.ca/docs"
---
Not a developer?This page is the technical guide (REST API, CLI, MCP). For how to upload, share, and use public vs private images, read the [user guide](/guide).

Documentation

# Build with imagebin.ca

REST API, the pbca CLI, and an MCP server for AI agents — all on your pastebin.ca account.

[Quick start](#quickstart) [REST API](#rest) [pbca CLI](#cli) [MCP for AI agents](#mcp) [OAuth & DPoP](#oauth) [Discovery](#discovery)

## Quick start

imagebin.ca shares your pastebin.ca account. Mint an API key bound to this site to use the REST API, the product CLI, or an MCP client.

Audience-boundMint a key with the scopes listed below and `https://imagebin.ca` as its audience.

**1.** Install the `pbca` CLI — a self-contained Rust binary:

```
curl -fsSL https://pastebin.ca/cli/install.sh | sh
```

Installs `pbca` to `/usr/local/bin` (override with `PBCA_INSTALL_PREFIX`). Prefer a direct download? Grab a platform binary — macOS, Linux, or Windows — from [pastebin.ca/cli](https://pastebin.ca/cli).

**2.** Mint a key bound to `imagebin.ca` on pastebin.ca:

```
pbca account api-key create \
  --scopes image:read,image:create,image:delete \
  --audience https://imagebin.ca
```

**3.** Give the key to the CLI via `PBCA_API_KEY` or `pbca account login`, then upload your first image:

```
pbca image upload ./your-image
```

## REST API

A small JSON surface. Send your key as `Authorization: Bearer <api-key>`. Anonymous browser uploads (with Turnstile) and signed-in cookie sessions also work; API-key callers must hold the matching scope.

### Scopes

image:read image:create image:delete

| Action | Method & path | Scope |
| --- | --- | --- |
| Upload an image | `POST /api/v1/items` | `image:create` |
| Read metadata | `GET /api/v1/items/:id` | `image:read` * |
| List your images | `GET /api/v1/account/items` | `image:read` |
| Delete an image | `DELETE /api/v1/items/:id` | `image:delete` |

* Reading a public image needs no key; a key, when sent, is scope-checked.

Uploads need a key (or a browser)Anonymous uploads are **browser-only** — they require a Turnstile challenge. From a script, the CLI, or an agent, send an API key with `image:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

```
curl -sS https://imagebin.ca/api/v1/account/items \
  -H 'Authorization: Bearer pbca_live_…'
```

Upload capsREST accepts up to **15 MiB** per image on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca image` commands default to `imagebin.ca`.

| Command | What it does |
| --- | --- |
| `pbca image upload <path>` | Upload an image (returns its id + URLs) |
| `pbca image get <id-or-url>` | Print metadata as JSON |
| `pbca image list` | List your images (cursor-paginated) |
| `pbca image delete <id>` | Delete one of your images |

## MCP for AI agents

imagebin.ca runs a Model Context Protocol server at `https://imagebin.ca/mcp`, so Claude Desktop, Cursor, the MCP Inspector, and other agents can manage your images directly.

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://imagebin.ca/.well-known/oauth-protected-resource/mcp`, registers with pastebin.ca (the authorization server), and runs the standard OAuth 2.1 + PKCE flow. Add to your Claude Desktop config:

```
{
  "mcpServers": {
    "imagebin": {
      "url": "https://imagebin.ca/mcp"
    }
  }
}
```

Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux). Cursor and Windsurf use the same `mcpServers` shape in `~/.cursor/mcp.json`. Try it live with `npx @modelcontextprotocol/inspector`.

### Option B — API-key bearer (automation)

For headless/server-side use, send a minted key directly:

```
{
  "mcpServers": {
    "imagebin": {
      "url": "https://imagebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_image` | `image:read` | JSON metadata for an image (visibility-aware). |
| `list_my_images` | `image:read` | List the caller's images; cursor-paginated. |
| `upload_image` | `image:create` | Upload from base64 bytes (capped — see below). |
| `delete_image` | `image:delete` | Delete one of the caller's images. |

MCP upload capMCP accepts up to **6 MiB** per image. Binary content is base64-encoded in the JSON-RPC request. REST accepts up to **15 MiB** per image.

## OAuth & DPoP

pastebin.ca is the OAuth authorization server; imagebin.ca is a protected resource and never mints tokens.

- OAuth tokens are **audience-bound** to `https://imagebin.ca/mcp` (RFC 8707) and honored only on the MCP route.
- If a key is **DPoP-bound** (RFC 9449), every MCP request must carry a matching ES256 proof; replays are rejected. Plain bearer keys work without DPoP.
- Revoke a key or connected app anytime from your pastebin.ca account.

## Discovery

Machine-readable metadata for clients and agents:

[Protected-resource metadata ↗](https://imagebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://imagebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://imagebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://imagebin.ca/mcp)


---

---
title: "Developer docs — imagebin.ca"
source: "https://imagebin.ca/docs/mcp"
---
Not a developer?This page is the technical guide (REST API, CLI, MCP). For how to upload, share, and use public vs private images, read the [user guide](/guide).

Documentation

# Build with imagebin.ca

REST API, the pbca CLI, and an MCP server for AI agents — all on your pastebin.ca account.

[Quick start](#quickstart) [REST API](#rest) [pbca CLI](#cli) [MCP for AI agents](#mcp) [OAuth & DPoP](#oauth) [Discovery](#discovery)

## Quick start

imagebin.ca shares your pastebin.ca account. Mint an API key bound to this site to use the REST API, the product CLI, or an MCP client.

Audience-boundMint a key with the scopes listed below and `https://imagebin.ca` as its audience.

**1.** Install the `pbca` CLI — a self-contained Rust binary:

```
curl -fsSL https://pastebin.ca/cli/install.sh | sh
```

Installs `pbca` to `/usr/local/bin` (override with `PBCA_INSTALL_PREFIX`). Prefer a direct download? Grab a platform binary — macOS, Linux, or Windows — from [pastebin.ca/cli](https://pastebin.ca/cli).

**2.** Mint a key bound to `imagebin.ca` on pastebin.ca:

```
pbca account api-key create \
  --scopes image:read,image:create,image:delete \
  --audience https://imagebin.ca
```

**3.** Give the key to the CLI via `PBCA_API_KEY` or `pbca account login`, then upload your first image:

```
pbca image upload ./your-image
```

## REST API

A small JSON surface. Send your key as `Authorization: Bearer <api-key>`. Anonymous browser uploads (with Turnstile) and signed-in cookie sessions also work; API-key callers must hold the matching scope.

### Scopes

image:read image:create image:delete

| Action | Method & path | Scope |
| --- | --- | --- |
| Upload an image | `POST /api/v1/items` | `image:create` |
| Read metadata | `GET /api/v1/items/:id` | `image:read` * |
| List your images | `GET /api/v1/account/items` | `image:read` |
| Delete an image | `DELETE /api/v1/items/:id` | `image:delete` |

* Reading a public image needs no key; a key, when sent, is scope-checked.

Uploads need a key (or a browser)Anonymous uploads are **browser-only** — they require a Turnstile challenge. From a script, the CLI, or an agent, send an API key with `image:create`; a keyless upload returns `403 {"error":"turnstile_failed"}`.

```
curl -sS https://imagebin.ca/api/v1/account/items \
  -H 'Authorization: Bearer pbca_live_…'
```

Upload capsREST accepts up to **15 MiB** per image on the API-key tier.

## pbca CLI

One CLI for the whole family. `pbca image` commands default to `imagebin.ca`.

| Command | What it does |
| --- | --- |
| `pbca image upload <path>` | Upload an image (returns its id + URLs) |
| `pbca image get <id-or-url>` | Print metadata as JSON |
| `pbca image list` | List your images (cursor-paginated) |
| `pbca image delete <id>` | Delete one of your images |

## MCP for AI agents

imagebin.ca runs a Model Context Protocol server at `https://imagebin.ca/mcp`, so Claude Desktop, Cursor, the MCP Inspector, and other agents can manage your images directly.

### Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads `https://imagebin.ca/.well-known/oauth-protected-resource/mcp`, registers with pastebin.ca (the authorization server), and runs the standard OAuth 2.1 + PKCE flow. Add to your Claude Desktop config:

```
{
  "mcpServers": {
    "imagebin": {
      "url": "https://imagebin.ca/mcp"
    }
  }
}
```

Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux). Cursor and Windsurf use the same `mcpServers` shape in `~/.cursor/mcp.json`. Try it live with `npx @modelcontextprotocol/inspector`.

### Option B — API-key bearer (automation)

For headless/server-side use, send a minted key directly:

```
{
  "mcpServers": {
    "imagebin": {
      "url": "https://imagebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}
```

### Tools

| Tool | Scope | Purpose |
| --- | --- | --- |
| `whoami` | — | Echo account id, scopes, audience, and token kind. |
| `get_image` | `image:read` | JSON metadata for an image (visibility-aware). |
| `list_my_images` | `image:read` | List the caller's images; cursor-paginated. |
| `upload_image` | `image:create` | Upload from base64 bytes (capped — see below). |
| `delete_image` | `image:delete` | Delete one of the caller's images. |

MCP upload capMCP accepts up to **6 MiB** per image. Binary content is base64-encoded in the JSON-RPC request. REST accepts up to **15 MiB** per image.

## OAuth & DPoP

pastebin.ca is the OAuth authorization server; imagebin.ca is a protected resource and never mints tokens.

- OAuth tokens are **audience-bound** to `https://imagebin.ca/mcp` (RFC 8707) and honored only on the MCP route.
- If a key is **DPoP-bound** (RFC 9449), every MCP request must carry a matching ES256 proof; replays are rejected. Plain bearer keys work without DPoP.
- Revoke a key or connected app anytime from your pastebin.ca account.

## Discovery

Machine-readable metadata for clients and agents:

[Protected-resource metadata ↗](https://imagebin.ca/.well-known/oauth-protected-resource/mcp) [Authorization-server metadata ↗](https://pastebin.ca/.well-known/oauth-authorization-server) [Agent discovery (agent.json) ↗](https://imagebin.ca/.well-known/agent.json) [OpenAPI 3.1 document ↗](https://imagebin.ca/api/v1/openapi.json) [MCP endpoint (POST) ↗](https://imagebin.ca/mcp)


---

---
title: "How to use imagebin.ca — User guide"
source: "https://imagebin.ca/guide"
---
User guide

# How to use imagebin.ca

What imagebin is, how public and private images work, and step-by-step how-tos — no technical knowledge needed.

[What is imagebin?](#what) [How it works](#how) [Public vs private](#privacy) [How-to guides](#howtos) [Protect your privacy](#metadata) [Limits & file types](#limits) [Staying safe](#safety) [FAQ](#faq) [For developers](#developers)

## What is imagebin?

imagebin.ca is a free, fast image host. Drop in a picture and you get a shareable link in seconds — no account required. It’s built for sharing screenshots, photos, and graphics anywhere you can paste a link: chats, forums, issue trackers, social posts, or your own website.

imagebin is part of the bin family (alongside pastebin.ca, filebin.ca and others). If you make a free account on any of them, the same sign-in works everywhere — it simply raises your limits and keeps a tidy list of everything you’ve uploaded.

## How it works

1. **You upload an image.** Drag it onto the page or use the Choose images button.
2. **We store it and give you a link.** Every image gets a short address you can share. Anonymous links last 90 days; signed-in uploads stay until you delete them.
3. **We make fast thumbnails.** When your image appears in a list or preview, we serve a small, optimised version from a global cache so pages load quickly — the full-quality original is always one click away.
4. **You share it however you like.** Copy a direct link, grab ready-made Markdown, or download the file again anytime.

Know how long your link lastsAnonymous uploads are removed after 90 days. Images uploaded while signed in stay until you delete them — see [Limits](#limits).

## Public vs private

Every image is either **public** or **private**. This is the most important choice to understand, so here’s exactly what each one means.

Anyone can find it

Public images

- Anyone with the link can view the image.
- Image pages are excluded from sitemaps. Public image pages can still be found by search engines, and images marked safe can appear in the [homepage gallery](/).
- Good for: things you’re happy for the world to see — screenshots for a public bug report, art you want discovered, a photo for a forum post.

Link-only — like an unlisted page

Private images

- Private images are excluded from the gallery. Like all image pages, they are omitted from sitemaps. Their pages ask search engines not to index them.
- The share link includes a secret access token (the long `?s=…` part of the URL). That token *is* the key: anyone who has the full link can view the image; anyone without it gets a “not found” page.
- Use private links to share without listing the image publicly. Anyone who receives or is forwarded the complete link can open it.

Treat a private link like a passwordBecause the link contains the access token, share it only with people who should see the image. Anyone you forward it to can open it, and can pass it on. There’s no per-person login on a private link.

By default, new uploads are **public**. You can flip any single upload to private before you send it, or set *private by default* once in your account so every new image starts private. See [the how-tos](#howtos) below.

## How-to guides

### Upload an image

1. Go to the [homepage](/).
2. **Drag** an image file onto the drop area or use **Choose images** to browse for a file.
3. Review the optional details, then choose **Upload**. When it’s done, your image and its links appear.

### Share your image

1. Open the link shown beside the completed upload, or find the image in your account while signed in.
2. Use **Direct link** to share the image itself, **Markdown** to paste into docs/issues that support it, or **Download** to save the stored image.
3. Click the *Copy* button next to a link to copy it to your clipboard.

### Make an upload private (or public)

1. Before uploading, tick **“Keep these uploads private (link-only)”** in the upload form to make that batch private.
2. Prefer it always on? Sign in, open [your account](/account), and turn on **“Make new uploads private by default.”**
3. Remember: a private link only works *with* its full `?s=…` token. Copy the whole link.

### Add a title, description, or tags

1. In the upload form, expand the details for an image and fill in a title, description, or comma-separated tags. All are optional.
2. These help you recognise images later and can add context for viewers.

### Find and manage your uploads

1. Sign in, then open [your account](/account) to see everything you’ve uploaded.
2. From there you can open any image or delete ones you no longer want.

### Delete an image

1. Open [your account](/account) and find the image.
2. Click **Delete** next to it. This removes the image and stops its link from working.

### Sign in (and why it helps)

1. Click **Sign in** in the top bar. Accounts are shared across the bin family via pastebin.ca — if you have one, use it here.
2. Signing in raises your upload limits, removes the automatic expiry on new uploads, and keeps a list of your images so you can manage them later.

## Protect your privacy

An image page shows selected camera fields, not every tag in the file. The downloaded file can contain more. Metadata removal edits supported file formats before storage; sign in and open [your account](/account) to choose:

| Setting | What it does |
| --- | --- |
| **Remove supported metadata** | Removes supported metadata containers from JPEG, PNG, and WebP uploads. GIF and BMP files are not rewritten. |
| **Remove location (GPS)** | Rebuilds JPEG camera metadata from selected fields, dropping GPS, serials, owner names, and unknown tags. Removes EXIF and text metadata from PNG, and EXIF/XMP from WebP. |
| **Remove camera & owner serial numbers** | Uses the same file treatment as Remove location (GPS). |
| **Private by default** | Every new upload starts as link-only private. |
| **No AI descriptions or tags** | Stops automated descriptions and tags and clears existing ones from your images. Safety classification still runs, including for private images. |

Anonymous uploads use the Remove location policy. New signed-in accounts leave metadata removal off until you choose it. GIF and BMP uploads keep their original bytes; other unsupported formats are rejected when removal is requested. These settings do not remove information visible in the picture itself.

GPS coordinates and serial numbers are omitted from the image page’s camera fields. That display choice does not mean they were removed from the downloadable file. See [imagebin privacy](/privacy) for storage and processing details.

## Limits & file types

imagebin accepts common image formats — JPEG, PNG, GIF, WebP, and similar. Limits depend on whether you’re signed in:

|  | Anonymous | Signed in (free) |
| --- | --- | --- |
| Maximum per image | 8 MB | 15 MB |
| Total storage | — | 1 GB |
| Uploads per hour | 30 | 120 |
| Auto-expiry | Removed after 90 days | Kept until you delete |

Need larger uploads or no automatic expiry?Create a free account (it’s the shared pastebin.ca sign-in). You get larger files, no automatic expiry, and a list of your images to manage.

## Staying safe

imagebin is a shared, public-friendly service. To keep it usable for everyone:

- Only upload images you have the right to share.
- No illegal content, and nothing that sexualises minors — such material is removed and reported.
- Uploads are automatically screened, and only images checked as safe appear in the public gallery.

If you come across something that breaks these rules, please report it via the [abuse page](https://pastebin.ca/abuse).

## FAQ

**Do I need an account?** No. You can upload and share without one. An account just raises limits and keeps your images from expiring. **How long do images last?** Images uploaded while signed in stay until you delete them. Anonymous uploads are removed after 90 days. **Who can see a private image?** Anyone with the complete link, including anyone it is forwarded to. The link contains an access token and does not identify a particular reader. **Can I change an image after uploading?** You can edit its title, description, and tags, and delete it. The image file itself can’t be swapped — upload a new one instead. **I lost a private link. Can you recover it?** If you were signed in, open [your account](/account) to find it again. If you uploaded anonymously, the link can’t be recovered — so save private links somewhere safe. **Can I make a public image private later (or the reverse)?** Set visibility at upload time. To change it afterwards, the simplest path is to re-upload with the visibility you want and delete the old one.

## For developers

Want to upload from a script, the terminal, or an AI agent? imagebin has a REST API, the `pbca` command-line tool, and a Model Context Protocol (MCP) server.

[Developer docs →](/docs) [REST API](/docs#rest) [CLI](/docs#cli) [MCP for agents](/docs#mcp)