Documentation

Build with voicebin.ca

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

Quick start

voicebin.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 audio clip:* key only works on voicebin.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 voicebin.ca on pastebin.ca:

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

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

pbca audio upload ./your-audio clip

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

voice:read voice:create voice:delete

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

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

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

Upload capsREST accepts up to 50 MiB per audio clip on the API-key tier.

pbca CLI

One CLI for the whole family. pbca audio commands default to voicebin.ca.

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

MCP for AI agents

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

Option A — OAuth (interactive clients)

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

Tools

Tool	Scope	Purpose
`whoami`	—	Echo account id, scopes, audience, and token kind.
`get_audio`	`voice:read`	JSON metadata for an audio clip (visibility-aware).
`list_my_audio`	`voice:read`	List the caller's clips; cursor-paginated.
`upload_audio`	`voice:create`	Upload from base64 bytes (capped — see below).
`delete_audio`	`voice:delete`	Delete one of the caller's clips.

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

OAuth & DPoP

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

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