shortkit

Agentic-first URL shortener service. Create, manage, and redirect short links with analytics. Plain text API, agent-driven, single Go binary with JSON file storage.

Quick Start

go install github.com/relentlessworks/shortkit/cmd/shortkit@latest
shortkit

Then point your AI agent at http://localhost:8080 and have it read GET /help for the full operating manual.

Key Features

• Plain text by default — one labeled, grepable line per record. JSON on demand via ?format=json.
• Instructive errors — every 4xx includes a hint telling the agent what to do next.
• Self-documenting — GET /help returns a one-page operating manual.
• Simple auth — OTP via email → long-lived bearer token. No OAuth.
• Multi-tenant — workspaces isolate data per tenant.
• MCP connector — speaks Model Context Protocol at /mcp.
• Short stable handles — every link gets a short handle like link_k7m2q.
• Single static binary — CGO_ENABLED=0, zero external dependencies.

API Reference

Auth

Method	Path	Body	Description
POST	/auth/request	email=user@example.com	Request OTP (logged to stderr in dev)
POST	/auth/verify	email=user@example.com&code=123456	Verify OTP, get bearer token

Links

Method	Path	Body	Description
POST	/links	url=https://example.com[&slug=mylink][&ttl=24h][&tags=foo,bar]	Create short link
GET	/links	—	List all links
GET	/links/{handle}	—	Get link details
PATCH	/links/{handle}	url=...&slug=...&tags=...	Update link
DELETE	/links/{handle}	—	Delete link

Redirects (Public)

Method	Path	Description
GET	/s/{handle}	301 redirect to original URL
GET	/s/{slug}	301 redirect via custom slug

Other

Method	Path	Description
GET	/help	Operating manual for agents
GET	/.well-known/agent.md	Same as /help
GET	/health	Health check
GET	/workspace	Workspace info
GET	/audit	Audit log
POST	/mcp	MCP JSON-RPC endpoint

Configuration

Flag	Env	Default	Description
-addr	SHORTKIT_ADDR	:8080	Listen address
-db	SHORTKIT_DB	shortkit.json	Database file path
-secret	SHORTKIT_SECRET	(auto-generated)	Token signing secret
-base-url	SHORTKIT_BASE_URL	http://localhost:8080	Base URL for short links

Config priority: defaults < env vars < flags.

Build

make build    # CGO_ENABLED=0 go build -trimpath
make test     # go test -race
make vet      # go vet
make run      # go run

License

MIT