Brevu API Reference

Base URL: https://brevu.link/api/v1 Auth: Authorization: Bearer brv_xxxxx

Authentication

POST /auth/register        註冊（回傳 user + team + API key）
POST /auth/login           登入（回傳 API key）

Links

GET    /links              列出短網址（?page=1&per_page=20）
GET    /links/:code        取得單一短網址
PATCH  /links/:code        更新短網址
DELETE /links/:code        刪除短網址
POST   /links/bulk         批次建立（最多 1,000 筆）

A/B Test Targets

GET    /links/:code/targets              列出 variants
POST   /links/:code/targets              新增 variant
PATCH  /links/:code/targets/:id          更新 variant（weight/URL/條件）
DELETE /links/:code/targets/:id          刪除 variant

Statistics

GET    /links/:code/stats                總覽（PV/UV/daily/geo/device/referrer）

Bio Page

GET    /biopages/:slug                   取得 Markdown 原始碼
PUT    /biopages/:slug                   更新（Content-Type: text/plain）
POST   /biopages/:slug/preview           預覽渲染 HTML
GET    /biopages/:slug/versions          版本歷史
POST   /biopages/:slug/rollback          回滾到指定版本

QR Code

GET    /links/:code/qr                   QR Code（?format=png|svg&size=300）

UTM Templates

GET    /utm-templates                    12 種預設 UTM 範本

Export

POST   /export                           匯出統計（?format=csv|json）

API Keys

POST   /apikeys                          建立 API Key
GET    /apikeys                          列出 API Keys
DELETE /apikeys/:id                      撤銷 API Key

Webhooks

POST   /webhooks                         建立 Webhook
GET    /webhooks                         列出 Webhooks
DELETE /webhooks/:id                     刪除 Webhook

Events: link.created link.clicked biopage.updated link.flagged link.disabled

Custom Domains

POST   /domains                          新增域名
GET    /domains                          列出域名
POST   /domains/:id/verify              驗證 CNAME
DELETE /domains/:id                      刪除域名

Billing

GET    /billing/status                   目前方案 + 用量
POST   /billing/checkout                 Stripe 結帳（升級方案）
POST   /billing/cancel                   取消訂閱

Distill

GET    /proxy-fetch?url=xxx              代理抓取（給 WebGPU 頁面用）
POST   /distill-reward                   On-device 萃取獎勵（+0.5 credit）

AEO Sovereignty

GET    /aeo-check?url=xxx               AEO 主權（回傳 score + checks + suggestions）

MCP

/mcp/sse                                MCP Server（SSE transport，12 tools）

Content Extraction Modes

| Mode | Field | Credit | Description | |---|---|---|---| | Manual | auto_extract: false + fill OG fields | 0 | 手動填寫 | | Client upload | auto_extract: false + fill all fields | 0 | Agent/CLI 自行萃取後上傳 | | Server | auto_extract: true | 1 | Brevu 全包（Jina + LLM） |

Canonical Mode

The canonical_mode field controls the <link rel="canonical"> tag on preview mid-pages.

| Value | Behavior | |---|---| | auto | Custom domain → points to self; brevu.link → points to target URL | | target | Always points to the original target URL (mid-page won't be indexed) | | self | Always points to the mid-page itself (mid-page serves as AEO entry point) |

Default: auto. Accepted in POST /links and PATCH /links/:code.

Rate Limits

| Endpoint | Free | Starter | Pro | Business | |---|---|---|---|---| | Auth (login/register) | 10/min | 10/min | 10/min | 10/min | | Links CRUD | 10/hr | 100/hr | 500/hr | 2,000/hr | | Export | 5/hr | 20/hr | 50/hr | 200/hr |

Stats Tier Limits

Statistics endpoints return data scoped by plan tier. Exceeding your tier returns 403 Forbidden.

| Feature | Free | Starter | Pro | Business | |---|---|---|---|---| | Time range | 7 days | 90 days | 1 year | 3 years | | Geo detail | Country Top 5 | Country Top 20 | Country + City | Full | | Device/Browser | Top 5 | Top 20 | Full | Full | | Referrer | Top 5 | Top 20 | Full | Full | | A/B test report | ✗ | Basic | Full | Full | | Export CSV | ✗ | 5/month | Unlimited | Unlimited | | Export JSON | ✗ | ✗ | ✓ | ✓ | | API stats queries | 10/day | 100/day | 1,000/day | Unlimited | | Dashboard refresh | Hourly | Every 10 min | Real-time | Real-time | | Webhook click events | ✗ | ✗ | Aggregated/min | Real-time |

Query parameters start_date / end_date are clamped to the plan's allowed time range. The geo, devices, and referrers endpoints return at most the tier's top-N results.

Retention Policy (Downgrade / Cancellation)

When a subscription is cancelled or not renewed, resources are handled as follows:

| Resource | After downgrade | Retention | Then | |---|---|---|---| | Short link redirects | Free-tier quota keeps working | Permanent | Excess disabled after 90 days | | Preview pages (中間頁) | All downgraded to plain 302 | Immediate | HTML retained 90 days | | Bio Pages | Only 1 kept | 90 days | Others deleted | | Statistics | Limited to 7-day view | 90 days | History deleted | | OG images | Stop serving | 90 days | Deleted | | Custom domains | Disabled | 30 days | Deleted | | Tracking codes (GA/Pixel) | Stop rendering | Immediate | — |

Error Format

{"error": "description"}

TODO

[ ] OpenAPI 3.0 spec (swagger.json)
[x] 每個 endpoint 的 request/response 範例 (top 5)
[ ] 錯誤碼完整列表
[ ] SDK（Go / Python / JavaScript）
[ ] Webhook payload 格式文件
[ ] MCP tools 詳細參數文件

Request/Response Examples

POST /api/v1/links

Create a new short link.

Request:

curl -X POST https://brevu.link/api/v1/links \
  -H 'Authorization: Bearer brv_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "target_url": "https://example.com/my-long-page",
    "slug": "my-link",
    "og_title": "My Page",
    "og_desc": "A description of my page",
    "canonical_mode": "auto",
    "auto_extract": false
  }'

Response (201):

{
  "link": {
    "id": 1,
    "code": "my-link",
    "target_url": "https://example.com/my-long-page",
    "type": "redirect",
    "og_title": "My Page",
    "og_desc": "A description of my page",
    "canonical_mode": "auto",
    "is_active": true,
    "created_at": "2026-05-02T12:00:00Z",
    "updated_at": "2026-05-02T12:00:00Z"
  }
}

GET /api/v1/links

List all links for the authenticated team.

Request:

curl https://brevu.link/api/v1/links?page=1&per_page=20 \
  -H 'Authorization: Bearer brv_xxx'

Response (200):

{
  "links": [
    {
      "id": 1,
      "code": "my-link",
      "target_url": "https://example.com/my-long-page",
      "type": "redirect",
      "og_title": "My Page",
      "is_active": true,
      "created_at": "2026-05-02T12:00:00Z",
      "updated_at": "2026-05-02T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

GET /api/v1/links/:code/stats

Get click statistics for a link.

Request:

curl https://brevu.link/api/v1/links/my-link/stats \
  -H 'Authorization: Bearer brv_xxx'

Response (200):

{
  "code": "my-link",
  "total_pv": 1234,
  "total_uv": 567,
  "daily": [
    {"day": "2026-05-02", "pv": 100, "uv": 45},
    {"day": "2026-05-01", "pv": 150, "uv": 60}
  ],
  "countries": [
    {"name": "TW", "count": 400},
    {"name": "US", "count": 200}
  ],
  "devices": [
    {"name": "mobile", "count": 700},
    {"name": "desktop", "count": 500}
  ],
  "referrers": [
    {"name": "twitter.com", "count": 300},
    {"name": "direct", "count": 200}
  ]
}

PUT /api/v1/biopages/:slug

Create or update a bio page.

Request:

curl -X PUT https://brevu.link/api/v1/biopages/my-bio \
  -H 'Authorization: Bearer brv_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "---\ntheme: neon\n---\n# My Bio\n\nWelcome to my page!\n\n- [Twitter](https://twitter.com/me)\n- [GitHub](https://github.com/me)",
    "og_title": "My Bio Page",
    "og_desc": "Links and info"
  }'

Response (200):

{
  "slug": "my-bio",
  "markdown": "---\ntheme: neon\n---\n# My Bio\n...",
  "og_title": "My Bio Page",
  "og_desc": "Links and info",
  "updated_at": "2026-05-02T12:00:00Z"
}

POST /api/v1/auth/register

Request:

curl -X POST https://brevu.link/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "Felix",
    "team_name": "My Team"
  }'

Response (201):

{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Felix",
    "role": "admin",
    "team_id": 1,
    "is_active": true,
    "created_at": "2026-05-02T12:00:00Z"
  },
  "team": {
    "id": 1,
    "name": "My Team",
    "slug": "my-team",
    "plan": "free",
    "credits_balance": 5,
    "max_links": 50
  },
  "api_key": "brv_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}