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.

Documentation

Build with ibin.co

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

Quick start

ibin.co 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://ibin.co 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.

2. Mint a key bound to ibin.co on pastebin.ca:

pbca account api-key create \
  --scopes image:read,image:create,image:delete \
  --audience https://ibin.co

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://ibin.co/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 ibin.co.

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

ibin.co runs a Model Context Protocol server at https://ibin.co/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://ibin.co/.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://ibin.co/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://ibin.co/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; ibin.co is a protected resource and never mints tokens.

OAuth tokens are audience-bound to https://ibin.co/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) ↗