Documentation

Build with www.imagebin.ca

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

Quick start

www.imagebin.ca shares your pastebin.ca account. There is nothing new to sign up for — install the CLI, mint an API key bound to this site, and you can drive everything from the terminal, your scripts, or an AI agent.

Audience-boundKeys are scoped to one site. A image:* key only works on www.imagebin.ca; it is rejected everywhere else.

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.

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

pbca account api-key create \
  --scopes image:read,image:create,image:delete \
  --audience https://www.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:readimage:createimage:delete

Action	Method & path	Scope
Upload a 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 a 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://www.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 www.imagebin.ca.

Command	What it does
`pbca image upload <path>`	Upload a 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

www.imagebin.ca runs a Model Context Protocol server at https://www.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://www.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://www.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://www.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 uploads are capped at 6 MiB (base64 inflates inside the JSON-RPC envelope). Use the REST endpoint for larger images.

OAuth & DPoP

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

OAuth tokens are audience-bound to https://www.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 ↗ Authorization-server metadata ↗ Agent discovery (agent.json) ↗ OpenAPI 3.1 document ↗ MCP endpoint (POST) ↗