Developers

Developer guide

Shorten and manage links from the REST API, an AI agent, or your scripts.

Quick start

turl.ca shares your pastebin.ca account — nothing new to sign up for. Mint an API key bound to this site, then shorten URLs from your scripts or an AI agent.

Audience-boundA link:* key only works on turl.ca; it is rejected everywhere else.

curl -sS https://turl.ca/api/v1/links \
  -H 'Authorization: Bearer pbca_live_…' \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/a/very/long/link"}'

REST API

A small JSON surface. Send your key as Authorization: Bearer <api-key>. Signed-in cookie sessions also work; API-key callers must hold the matching scope. The full spec is at /api/v1/openapi.json.

Scopes

link:create link:read link:delete

Action	Method & path	Scope
Shorten a URL	`POST /api/v1/links`	`link:create`
Read one of your links	`GET /api/v1/links/:code`	`link:read`
List your links	`GET /api/v1/account/links`	`link:read`
Retire one of your links	`DELETE /api/v1/links/:code`	`link:delete`
Report abuse	`POST /api/v1/abuse`	—

Trust tiersFamily and curated high-reputation destinations may be shortened anonymously (browser + Turnstile). Arbitrary destinations require a signed-in account and resolve through a preview page until a reputation check clears — a keyless or account-less create of an unknown destination returns 401 {"error":"account_required"}.

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

MCP for AI agents

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

Option A — OAuth (interactive clients)

Point your client at the MCP URL and it discovers the rest: it reads https://turl.ca/.well-known/oauth-protected-resource/mcp, registers with pastebin.ca (the authorization server), and runs OAuth 2.1 + PKCE. Add to your Claude Desktop config:

{
  "mcpServers": {
    "turl": {
      "url": "https://turl.ca/mcp"
    }
  }
}

Config path: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux). Cursor uses the same mcpServers shape in ~/.cursor/mcp.json. Try it live with npx @modelcontextprotocol/inspector.

Option B — API-key bearer (automation)

For headless use, send a minted key directly:

{
  "mcpServers": {
    "turl": {
      "url": "https://turl.ca/mcp",
      "headers": { "Authorization": "Bearer pbca_live_…" }
    }
  }
}

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

Tools

Tool	Scope	Purpose
`whoami`	—	Echo account id, scopes, audience, and token kind.
`create_link`	`link:create`	Shorten a URL; returns short + preview URLs and trust tier.
`get_link`	`link:read`	Fetch one of the caller's links by code.
`list_my_links`	`link:read`	List the caller's links; cursor-paginated.
`delete_link`	`link:delete`	Retire one of the caller's links.

OAuth & DPoP

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

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

Document	URL
OpenAPI 3.1	`/api/v1/openapi.json`
Agent card	`/.well-known/agent.json`
MCP protected resource	`/.well-known/oauth-protected-resource/mcp`
LLM site map	`/llms.txt`