# turl.ca

> A reputation-first, non-profit URL shortener. Turn a long URL into an immutable,
> screened short link. Unsafe destinations are rejected; unverified ones resolve
> through a transparency/preview page instead of an instant redirect. Citation mode
> archives a snapshot of the destination for the record. Accounts, OAuth, and API
> keys are federated from pastebin.ca.

## How it works

- Short links are immutable: a code always points at the destination it was minted for.
- Family and curated high-reputation destinations can be shortened anonymously
  (browser + Turnstile). Arbitrary destinations require a free pastebin.ca account.
- Resolution depends on the destination's trust tier: trusted links redirect (302);
  unverified or pending links show a preview page first.

## Developer docs

- [Developer guide](https://turl.ca/docs): REST API, MCP, OAuth, and discovery.
- [OpenAPI 3.1 spec](https://turl.ca/api/v1/openapi.json): the full REST contract.
- [MCP server](https://turl.ca/mcp): Model Context Protocol endpoint for AI agents.
- [Agent card](https://turl.ca/.well-known/agent.json): machine-readable capabilities.
- [MCP discovery](https://turl.ca/.well-known/oauth-protected-resource/mcp): protected-resource metadata.

## API summary

- POST https://turl.ca/api/v1/links — shorten a URL (scope link:create). Body: {"url": "...", "mode": "redirect|cite"}.
- GET https://turl.ca/api/v1/links/{code} — read one of your links (scope link:read).
- GET https://turl.ca/api/v1/account/links — list your links (scope link:read).
- DELETE https://turl.ca/api/v1/links/{code} — retire one of your links (scope link:delete).
- POST https://turl.ca/api/v1/abuse — report an abusive link (no auth).

## Authentication

- Account API keys are minted on https://pastebin.ca and audience-bound to https://turl.ca.
- Send them as: Authorization: Bearer pbca_live_…
- OAuth 2.1 + PKCE (with optional DPoP) is available for interactive MCP clients;
  pastebin.ca is the authorization server.

## Policy

- Links are immutable and cannot be repointed after creation.
- Malicious destinations are blocked and existing links are continuously re-scanned.
- Report abuse at https://turl.ca/abuse or POST https://turl.ca/api/v1/abuse.