Back to Details

dub-links-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dub Links API

Dub Links API

Skill for integrating Dub Links API with strict scope limited to 
/links*
endpoints.
用于集成Dub Links API的Skill，严格限定作用域为
/links*
端点。

API Overview

API概述

  • Base URL: 
    https://api.dub.co
  • Auth: Bearer token required
  • Header: 
    Authorization: Bearer <DUB_API_KEY>
  • Response format: JSON
  • Scope: Links endpoints only
  • Docs: 
    https://dub.co/docs/api-reference/endpoint/create-a-link
  • Token docs (onboarding): 
    https://dub.co/docs/api-reference/tokens
  • Local snapshot: 
    references/openapi-spec.json
  • 基础URL: 
    https://api.dub.co
  • 认证: 需要Bearer令牌
  • 请求头: 
    Authorization: Bearer <DUB_API_KEY>
  • 响应格式: JSON
  • 作用域: 仅链接端点
  • 文档: 
    https://dub.co/docs/api-reference/endpoint/create-a-link
  • 令牌文档（入门引导）: 
    https://dub.co/docs/api-reference/tokens
  • 本地快照: 
    references/openapi-spec.json

API Key Onboarding

API密钥入门引导

Use this flow when the user does not have an API key yet:
  1. Create a Dub account/workspace (if needed).
  2. Go to the dashboard token section (per docs): 
    • https://dub.co/docs/api-reference/tokens
  3. Generate an API key and export it in shell: 
    • export DUB_API_KEY="..."
  4. Validate credentials with a Links endpoint: 
    • curl -s -H "Authorization: Bearer $DUB_API_KEY" "https://api.dub.co/links/count" | jq '.'
Useful onboarding note: if initial signup is needed, this referral can be used: 
https://refer.dub.co/agents
当用户还没有API密钥时，使用以下流程：
  1. 创建Dub账户/工作区（如需要）。
  2. 前往控制台的令牌页面（参考文档）： 
    • https://dub.co/docs/api-reference/tokens
  3. 生成API密钥并在Shell中导出： 
    • export DUB_API_KEY="..."
  4. 通过Links端点验证凭据： 
    • curl -s -H "Authorization: Bearer $DUB_API_KEY" "https://api.dub.co/links/count" | jq '.'
实用入门提示：如果需要首次注册，可以使用此推荐链接： 
https://refer.dub.co/agents

Links Endpoints

Links端点

1) Create

1) 创建

  • POST /links
  • Creates a link in the authenticated workspace.
  • Minimum recommended body: 
    url
    .
bash
curl -s -X POST "https://api.dub.co/links" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq '.'
  • POST /links
  • 在已认证的工作区中创建一个链接。
  • 推荐的最小请求体：
    url
    。
bash
curl -s -X POST "https://api.dub.co/links" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq '.'

2) Update

2) 更新

  • PATCH /links/{linkId}
  • Updates an existing link by 
    linkId
    (also accepts 
    externalId
    prefixed with 
    ext_
    ).
bash
curl -s -X PATCH "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/new"}' | jq '.'
  • PATCH /links/{linkId}
  • 通过
    linkId
    更新现有链接（也接受前缀为
    ext_
    的
    externalId
    ）。
bash
curl -s -X PATCH "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/new"}' | jq '.'

3) Upsert

3) 插入或更新

  • PUT /links/upsert
  • If a link with the same URL exists, returns/updates it; otherwise creates it.
bash
curl -s -X PUT "https://api.dub.co/links/upsert" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq '.'
  • PUT /links/upsert
  • 如果存在相同URL的链接，则返回/更新该链接；否则创建新链接。
bash
curl -s -X PUT "https://api.dub.co/links/upsert" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq '.'

4) Delete

4) 删除

  • DELETE /links/{linkId}
  • Deletes a link by 
    linkId
    (also accepts 
    externalId
    prefixed with 
    ext_
    ).
  • Response: 
    {"id": "string"}
    .
bash
curl -s -X DELETE "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
  • DELETE /links/{linkId}
  • 通过
    linkId
    删除链接（也接受前缀为
    ext_
    的
    externalId
    ）。
  • 响应：
    {"id": "string"}
    。
bash
curl -s -X DELETE "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'

5) Retrieve one

5) 查询单个链接

  • GET /links/info
  • Retrieves a link by one of these selectors: 
    • domain + key
    • linkId
    • externalId
bash
curl -s "https://api.dub.co/links/info?domain=acme.link&key=promo" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
  • GET /links/info
  • 通过以下选择器之一查询链接： 
    • domain + key
    • linkId
    • externalId
bash
curl -s "https://api.dub.co/links/info?domain=acme.link&key=promo" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'

6) List

6) 列出链接

  • GET /links
  • Returns paginated list with filters.
  • Common query params: 
    domain
    , 
    search
    , 
    tagIds
    , 
    tagNames
    , 
    folderId
    , 
    userId
    , 
    tenantId
    , 
    showArchived
    , 
    page
    , 
    pageSize
    (default: 100, max: 100), 
    sortBy
    (
    createdAt
    |
    clicks
    |
    saleAmount
    |
    lastClicked
    ), 
    sortOrder
    (
    asc
    |
    desc
    ).
bash
curl -s "https://api.dub.co/links?page=1&pageSize=100&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
  • GET /links
  • 返回带筛选条件的分页列表。
  • 常用查询参数：
    domain
    、
    search
    、
    tagIds
    、
    tagNames
    、
    folderId
    、
    userId
    、
    tenantId
    、
    showArchived
    、
    page
    、
    pageSize
    （默认：100，最大值：100）、
    sortBy
    （
    createdAt
    |
    clicks
    |
    saleAmount
    |
    lastClicked
    ）、
    sortOrder
    （
    asc
    |
    desc
    ）。
bash
curl -s "https://api.dub.co/links?page=1&pageSize=100&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'

7) Count

7) 统计链接

  • GET /links/count
  • Returns number of links for the provided filters.
  • Common query params: 
    domain
    , 
    search
    , 
    tagIds
    , 
    tagNames
    , 
    folderId
    , 
    userId
    , 
    tenantId
    , 
    showArchived
    , 
    groupBy
    (
    domain
    |
    tagId
    |
    userId
    |
    folderId
    ).
bash
curl -s "https://api.dub.co/links/count?domain=acme.link" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
  • GET /links/count
  • 返回符合筛选条件的链接数量。
  • 常用查询参数：
    domain
    、
    search
    、
    tagIds
    、
    tagNames
    、
    folderId
    、
    userId
    、
    tenantId
    、
    showArchived
    、
    groupBy
    （
    domain
    |
    tagId
    |
    userId
    |
    folderId
    ）。
bash
curl -s "https://api.dub.co/links/count?domain=acme.link" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'

8) Bulk create

8) 批量创建

  • POST /links/bulk
  • Creates up to 100 links.
  • Body: array of objects (each item should include 
    url
    ).
bash
curl -s -X POST "https://api.dub.co/links/bulk" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url":"https://example.com/a"},{"url":"https://example.com/b"}]' | jq '.'
  • POST /links/bulk
  • 最多创建100个链接。
  • 请求体：对象数组（每个项需包含
    url
    ）。
bash
curl -s -X POST "https://api.dub.co/links/bulk" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"url":"https://example.com/a"},{"url":"https://example.com/b"}]' | jq '.'

9) Bulk update

9) 批量更新

  • PATCH /links/bulk
  • Updates up to 100 links.
  • Body requires 
    data
    ; target selection via 
    linkIds
    or 
    externalIds
    .
bash
curl -s -X PATCH "https://api.dub.co/links/bulk" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkIds":["lnk_123","lnk_456"],"data":{"archived":true}}' | jq '.'
  • PATCH /links/bulk
  • 最多更新100个链接。
  • 请求体需包含
    data
    ；通过
    linkIds
    或
    externalIds
    选择目标链接。
bash
curl -s -X PATCH "https://api.dub.co/links/bulk" \
  -H "Authorization: Bearer $DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkIds":["lnk_123","lnk_456"],"data":{"archived":true}}' | jq '.'

10) Bulk delete

10) 批量删除

  • DELETE /links/bulk
  • Deletes up to 100 links. Non-existing IDs are ignored. Irreversible.
  • Required query param: 
    linkIds
    (comma-separated).
  • Response: 
    {"deletedCount": number}
    .
bash
curl -s -X DELETE "https://api.dub.co/links/bulk?linkIds=lnk_123,lnk_456" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
  • DELETE /links/bulk
  • 最多删除100个链接。不存在的ID将被忽略。此操作不可撤销。
  • 必填查询参数：
    linkIds
    （逗号分隔）。
  • 响应：
    {"deletedCount": number}
    。
bash
curl -s -X DELETE "https://api.dub.co/links/bulk?linkIds=lnk_123,lnk_456" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'

Key Fields

关键字段

Common response fields (from 
LinkSchema
):
  • id
  • domain
  • key
  • shortLink
  • url
  • createdAt
  • updatedAt
  • archived
  • externalId
  • tags
  • folderId
Result shapes by endpoint:
  • GET /links
    : array of links
  • GET /links/count
    : number
  • Bulk endpoints: array/object depending on operation
来自
LinkSchema
的常见响应字段：
  • id
  • domain
  • key
  • shortLink
  • url
  • createdAt
  • updatedAt
  • archived
  • externalId
  • tags
  • folderId
各端点的结果格式：
  • GET /links
    : 链接数组
  • GET /links/count
    : 数字
  • 批量端点：根据操作返回数组/对象

Recommended Workflow

推荐工作流程

  1. Detect intent: create/update/upsert/delete/get/list/count/bulk.
  2. Validate minimum inputs (
    url
    , 
    linkId
    , filters, bulk ids).
  3. Execute request with 
    curl -s
    and Bearer header.
  4. Parse with 
    jq
    and verify logical operation result.
  5. Respond first with a useful snapshot: 
    • id
      , 
      shortLink
      , 
      url
      , and 
      archived
      status when relevant.
  6. For lists, provide a short table with relevant columns.
  7. Keep strict scope on 
    /links*
    .
  1. 识别意图：创建/更新/插入或更新/删除/查询/列出/统计/批量操作。
  2. 验证最小输入（
    url
    、
    linkId
    、筛选条件、批量ID）。
  3. 使用
    curl -s
    和Bearer头执行请求。
  4. 用
    jq
    解析并验证操作结果是否符合预期。
  5. 首先返回有用的快照信息：
    • 相关情况下返回
      id
      、
      shortLink
      、
      url
      和
      archived
      状态。
  6. 对于列表，提供包含相关列的简短表格。
  7. 严格限定作用域为
    /links*
    。

Error Handling

错误处理

  • 401/403: missing, invalid, or unauthorized token.
  • 404: link not found for 
    linkId
    or 
    GET /links/info
    criteria.
  • 422: invalid payload (missing/invalid fields).
  • 429: rate limited; respect 
    Retry-After
    if present.
  • Network/timeout: retry up to 2 times with short delay.
  • Unexpected JSON: return minimal raw output and warn about inconsistency.
  • 401/403: 令牌缺失、无效或未授权。
  • 404: 对应
    linkId
    的链接不存在，或
    GET /links/info
    的查询条件无匹配结果。
  • 422: 请求体无效（字段缺失/格式错误）。
  • 429: 请求频率超限；如果存在
    Retry-After
    响应头，请遵守其指示。
  • 网络/超时: 最多重试2次，每次重试前短暂延迟。
  • 非预期JSON: 返回最简原始输出并提示数据不一致。

Presenting Results

结果展示

Recommended output format:
  • Executive summary (action + result).
  • Short table for multiple links: 
    • id | domain | key | shortLink | url | createdAt
  • For bulk operations:
    • requested total, processed total, errors if any.
  • Clarify data is scoped to the authenticated workspace.
推荐输出格式：
  • 执行摘要（操作 + 结果）。
  • 多链接情况下使用简短表格： 
    • id | domain | key | shortLink | url | createdAt
  • 批量操作：
    • 请求总数、处理总数、错误信息（如有）。
  • 明确说明数据范围限于已认证的工作区。

Out of Scope

超出作用域

This skill must not use:
  • Analytics, events, conversions, partners, customers, commissions, payouts endpoints.
  • Domains, folders, tags endpoints.
  • /tokens/*
    endpoints (including 
    /tokens/embed/referrals
    ).
The tokens page is used only for API key onboarding, not as operational scope.
本Skill不得使用：
  • 分析、事件、转化、合作伙伴、客户、佣金、付款端点。
  • 域名、文件夹、标签端点。
  • /tokens/*
    端点（包括
    /tokens/embed/referrals
    ）。
令牌页面仅用于API密钥入门引导，不属于操作作用域。

OpenAPI Spec

OpenAPI规范

Use 
references/openapi-spec.json
as the stable local source for methods, paths, parameters, and schemas.
将
references/openapi-spec.json
作为方法、路径、参数和Schema的稳定本地数据源。