Documentation

Build with filebin.ca

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

Quick start

filebin.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 file:* key only works on filebin.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 filebin.ca on pastebin.ca:

pbca account api-key create \
  --scopes file:read,file:create,file:delete \
  --audience https://filebin.ca

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

pbca file upload ./your-file

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

file:readfile:createfile:delete

Action	Method & path	Scope
Upload a file	`POST /api/v1/files`	`file:create`
Read metadata	`GET /api/v1/items/:id`	`file:read` *
List your files	`GET /api/v1/account/items`	`file:read`
Delete a file	`DELETE /api/v1/items/:id`	`file:delete`

* Reading a public file 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 file:create; a keyless upload returns 403 {"error":"turnstile_failed"}.

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

Upload capsREST accepts up to 25 MiB per file on the API-key tier.

pbca CLI

One CLI for the whole family. pbca file commands default to filebin.ca.

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

MCP for AI agents

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

Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest. It reads https://filebin.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": {
    "filebin": {
      "url": "https://filebin.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": {
    "filebin": {
      "url": "https://filebin.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}

Tools

Tool	Scope	Purpose
`whoami`	—	Echo account id, scopes, audience, and token kind.
`get_file`	`file:read`	JSON metadata for a file (visibility-aware).
`list_my_files`	`file:read`	List the caller's files; cursor-paginated.
`upload_file`	`file:create`	Upload from base64 bytes (capped — see below).
`delete_file`	`file:delete`	Delete one of the caller's files.

MCP upload capMCP uploads are capped at 8 MiB (base64 inflates inside the JSON-RPC envelope). Use the REST endpoint for larger files.

OAuth & DPoP

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

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