Documentation

Build with voicebin.ca

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

Quick start

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

Audience-boundMint a key with the scopes listed below and https://voicebin.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.

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. Set BIN_API_KEY to the key from step 2, then list your audio clips:

curl -sS https://voicebin.ca/api/v1/account/items \
  -H "Authorization: Bearer $BIN_API_KEY"

REST API

Send your API 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
ActionMethod & pathScope
Upload an audio clipPOST /api/v1/audiovoice:create
Read metadataGET /api/v1/items/:idvoice:read *
List your audio clipsGET /api/v1/account/itemsvoice:read
Delete an audio clipDELETE /api/v1/items/:idvoice: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 or an agent, send an API key with voice: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.

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)

Connect your MCP client →

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

ToolScopePurpose
whoami—Echo account id, scopes, audience, and token kind.
get_audiovoice:readJSON metadata for an audio clip (visibility-aware).
list_my_audiovoice:readList the caller's clips; cursor-paginated.
upload_audiovoice:createUpload from base64 bytes (capped — see below).
delete_audiovoice:deleteDelete one of the caller's clips.
MCP upload capMCP accepts up to 8 MiB per audio clip. Binary content is base64-encoded in the JSON-RPC request. REST accepts up to 50 MiB per audio clip.

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: