# y.hn

> y.hn is a modern URL shortener with a full HTTP API: links, analytics, A/B testing, conversion tracking, custom domains, webhooks, QR codes, and bulk imports. Free tier supports 25 links/month with 30-day auto-expiry; paid tiers unlock unlimited links, custom expiry, password-protected redirects, and short slugs.

## How to use the API as an AI agent

- Base URL: `https://y.hn/api`
- Auth: send header `x-api-key: yhn_<your-key>` on every request.
- The user generates their key at `https://y.hn/dashboard/settings`.
- OpenAPI 3.0 spec (machine-readable, full schema): `https://y.hn/api/openapi`
- MCP server (recommended for Claude Code / Cursor / Cline / etc.):
  - npm package: `yhn-mcp`
  - Config: `{ "command": "npx", "args": ["-y", "yhn-mcp"], "env": { "YHN_API_KEY": "yhn_..." } }`
  - The MCP server exposes 19 tools covering links, folders, tags, analytics, conversions, webhooks, and domains.

## Most common operations

### Shorten a URL

```
curl -X POST https://y.hn/api/links \
  -H "x-api-key: yhn_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","customSlug":"demo"}'
# → { "shortUrl": "https://y.hn/demo", "slug": "demo", "id": "...", "targetUrl": "..." }
```

### Bulk shorten (import)

```
POST /api/links/bulk
{ "links": [ {"url":"..."}, {"url":"...", "customSlug":"..."} ] }
```

### Read account-wide stats

```
GET /api/analytics/overview
# → { plan, totalClicks: {today,week,month,allTime}, uniqueVisitors, growthRate, topLinks }
```

### Per-link analytics

```
GET /api/links/{linkId}/stats?period=7d
```

### Webhooks (subscribe to click events)

```
POST /api/webhooks
{ "url": "https://you.example.com/yhn-hook", "events": ["create","click"] }
```

Verify incoming hooks with the returned `secret` (HMAC-SHA256, header `x-yhn-signature`).

### QR code

```
GET /api/links/{linkId}/qr?size=512
# → image/png bytes
```

## Plan gates to remember

- Free: 25 links/month, 30-day auto-expiry, slug ≥6 chars, no password, no custom domain.
- Pro: unlimited links, custom expiry, password, slug ≥3 chars, A/B test, geo/device routing rules.
- Business: everything Pro + custom domains + team seats + higher rate limits.

Rate limits (all tiers): 10 links/min, 20 links/hour per account.

## What NOT to do

- Don't put the API key in the URL or browser-side code; use the `x-api-key` header server-side.
- Don't poll `/api/links` to detect new clicks — register a webhook.
- Don't shorten URLs flagged by Google Safe Browsing / VirusTotal — y.hn refuses with 403.

## Related

- Docs (human): https://y.hn/docs
- OpenAPI spec: https://y.hn/api/openapi
- MCP server source: https://github.com/97wow/yhn/tree/main/sdk/mcp
- TypeScript SDK: https://github.com/97wow/yhn/tree/main/sdk/typescript
- Python SDK: https://github.com/97wow/yhn/tree/main/sdk/python