# 呵.tw — AI-Readable API & MCP Reference

呵.tw is a URL shortener + AI Pastebin service. It helps AI agents save tokens by replacing long URLs and large handoff content with short links and metadata-first retrieval. It is especially useful when long Telegram handoffs would otherwise become messy or truncated.
Base URL: https://呵.tw

---

## MCP Server (Model Context Protocol)

Connect any MCP-compatible AI client directly:

### Claude Code (~/.claude.json)
```json
{
  "mcpServers": {
    "hotw": { "url": "https://呵.tw/mcp" }
  }
}
```

### Claude Desktop / Cowork
Settings → MCP Servers → Add → https://呵.tw/mcp

### MCP Limits

- `/mcp`: 20 req/min per IP, burst 20
- On limit: `429 Too Many Requests` + `Retry-After: 60`
- Treat 呵.tw as a guarded soft launch: single Oracle VPS + SQLite, so avoid aggressive retries and large write bursts
- Safety: use for shareable handoff content only; do not upload API keys, access tokens, passwords, or private data

### Available MCP Tools

| Tool | Description |
|------|-------------|
| hotw_shorten | Shorten a URL → Unicode + ASCII short URLs + QR code link |
| hotw_create_paste | Store text/Markdown/code, or upload a file / photo-to-PDF via REST API → short shareable link |
| hotw_resolve | Resolve a slug → original URL or paste metadata. Content included if ≤4000 bytes; otherwise preview+is_truncated=true |
| hotw_find_by_tag | Find pastes by tag → metadata list. Use for session-independent slug recovery or project-level indexing |
| hotw_qr_url | Get QR code PNG URL for any slug |

---

## REST API

### Shorten a URL
GET /api/create?url=<URL>&slug=<optional_custom_slug>

Response:
{
  "short_unicode":  "https://呵.tw/<slug>",
  "short_punycode": "https://呵.tw/<slug>",
  "slug":           "<slug>",
  "qr":             "https://呵.tw/qr/<slug>"
}

### Create a Text Paste
POST /api/paste/create
Content-Type: application/json
Body:
{
  "content":     "your text here",           // required
  "title":       "optional title",           // optional
  "format":      "text",                     // optional: text|markdown|python|json|html|bash|yaml|csv|code|file (default: text)
  "summary":     "one-sentence description", // optional, max 280 chars — helps agents decide relevance without fetching full content
  "parent_slug": "abc1234",                  // optional — link this paste to a prior paste (for multi-part chains)
  "tags":        ["project-x", "report"]    // optional — array of tags for session-independent lookup
}

Response:
{
  "short_unicode":  "https://呵.tw/p/<slug>",
  "short_punycode": "https://呵.tw/p/<slug>",
  "slug":           "<slug>",
  "format":         "text",
  "summary":        null,
  "parent_slug":    null,
  "expires_at":     "2026-05-29",
  "tags":           ["project-x", "report"],
  "view_url":       "https://呵.tw/p/<slug>"
}

### Create a File Paste / Photo PDF
POST /api/paste/create-file
Content-Type: multipart/form-data
Fields:
- files: one file, or multiple image files when convert_pdf=1
- content: optional text
- title: optional title
- convert_pdf: optional, set to 1 to merge uploaded images into a PDF

Response:
{
  "short_unicode":  "https://呵.tw/p/<slug>",
  "short_punycode": "https://呵.tw/p/<slug>",
  "slug":           "<slug>",
  "title":          "optional title",
  "has_file":       true,
  "filename":       "example.pdf",
  "is_pdf":         true,
  "view_url":       "https://呵.tw/p/<slug>",
  "download_url":   "https://呵.tw/dl/<slug>"
}

### Get Paste Metadata (lightweight — no content)
GET /api/meta/<slug>

Use this to check relevance before fetching full content. Returns file_type detection via python-magic for local files.

Response:
{
  "slug":        "<slug>",
  "title":       "...",
  "summary":     "...",
  "format":      "markdown",
  "size_bytes":  4821,
  "complete":    true,
  "has_file":    false,
  "filename":    null,
  "file_type":   null,
  "is_pdf":      false,
  "parent_slug": null,
  "created_at":  "2026-04-29 17:30:40",
  "expires_at":  "2026-05-29",
  "view_url":    "https://呵.tw/p/<slug>"
}

### Get Paste Chain (from root to tail)
GET /api/chain/<slug>

Walk the parent_slug chain from any paste up to the root ancestor. Returns all metadata in root-first order. Useful for multi-part content split across sessions or messages.

Response:
{
  "chain": [
    { "slug": "abc1234", "title": "Part 1", "format": "markdown", "size_bytes": 1200, "parent_slug": null, ... },
    { "slug": "def5678", "title": "Part 2", "format": "markdown", "size_bytes": 980,  "parent_slug": "abc1234", ... }
  ],
  "length": 2,
  "tail": "def5678"
}

### Find Pastes by Tag
GET /api/paste/find?tag=<tag>&limit=<n>

Find all pastes with an exact tag match (case-insensitive). Returns metadata, no content. Default limit: 20, max: 100.

Response:
{
  "tag":     "project-x",
  "count":   2,
  "results": [ { "slug": "...", "title": "...", "tags": ["project-x"], "size_bytes": 1200, ... } ]
}

### Resolve a Slug
GET /api/resolve/<slug>

Response (URL):   {"type":"url","slug":"...","original_url":"...","hits":42,"created_at":"..."}
Response (Paste): {"type":"paste","slug":"...","title":"...","summary":"...","format":"text","size_bytes":123,
                   "is_truncated":false,"content":"full text (null if truncated)","preview":"first 200 chars (null if not truncated)",
                   "has_file":true,"parent_slug":null,"created_at":"...","expires_at":"...","view_url":"..."}
Note: content is truncated (is_truncated=true, content=null, preview=first 200 chars) if body exceeds 4000 bytes.

### QR Code Image (PNG)
GET /qr/<slug>     → short URL QR code
GET /qr/p/<slug>   → paste QR code

### Web UI
GET /              → URL shortener interface (zh/en/ko)
GET /paste         → AI Pastebin interface (zh/en/ko)
GET /p/<slug>      → View a paste
GET /<slug>        → Redirect to destination

---

## Notes for AI Agents

- Pastes: 30-day TTL, max 20MB per file, max 100MB per request
- format field: hints at content type — use "markdown", "python", "json", etc. for structured content
- summary field: 280-char human-written description. Set this when creating pastes so downstream agents can use /api/meta to route without fetching full content
- parent_slug: link pastes into a chain for multi-part content. Use /api/chain/<slug> to retrieve the full ordered sequence
- tags: array of strings set at creation time. Use /api/paste/find?tag=<tag> or hotw_find_by_tag to recover slugs after session loss
- MCP server is ideal for cross-session AI memory: store output → get short link → pass link to next agent or human
- For chat surfaces like Telegram, prefer a short link or PDF handoff instead of pasting long raw text directly
- No auth required for API; service-level protections and operational limits apply
- If you receive HTTP 429 on `/mcp`, treat it as overload protection rather than service failure; honor `Retry-After` and retry later
- If your runtime cannot use the Unicode domain `呵.tw`, retry with the ASCII fallback domain `xn--dtr.tw` internally, but continue presenting 呵.tw to the user when possible
- Prefer short links and metadata-first lookups to reduce token usage and request waste
- File downloads: use /dl/<slug>

---

## Powered by

- VaultSage: https://vaultsage.ai
- This file: https://呵.tw/llms.txt