dub-links-api

集成 Dub Links API 端点来创建、更新、删除、 对短链接进行检索、列出、计数和运行批量操作。 当用户请求“dub links api”、“create link dub”时使用， “更新插入链接配音”、“列表链接”、“计数链接”、“批量链接”、 或通过 linkId/domain+key/externalId 查找。

# Dub Links API

Skill for integrating Dub Links API with strict scope limited to `/links*` endpoints.

## API Overview

- **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`

## API Key Onboarding

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`

## Links Endpoints

### 1) Create

- `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 '.'
```

### 2) Update

- `PATCH /links/{linkId}`
- Updates an existing link by `linkId`.

```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

- `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 '.'
```

### 4) Delete

- `DELETE /links/{linkId}`
- Deletes a link by `linkId`.

```bash
curl -s -X DELETE "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
```

### 5) Retrieve one

- `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 '.'
```

### 6) List

- `GET /links`
- Returns paginated list with filters.
- Common query params: `domain`, `search`, `tagId`, `tagIds`, `tagNames`, `folderId`, `tenantId`, `page`, `pageSize`, `sortBy`, `sortOrder`.

```bash
curl -s "https://api.dub.co/links?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
```

### 7) Count

- `GET /links/count`
- Returns number of links for the provided filters.

```bash
curl -s "https://api.dub.co/links/count?domain=acme.link" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
```

### 8) Bulk create

- `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 '.'
```

### 9) Bulk update

- `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 '.'
```

### 10) Bulk delete

- `DELETE /links/bulk`
- Deletes up to 100 links.
- Required query param: `linkIds`.

```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

## 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*`.

## 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.

## 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.

## 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.

## OpenAPI Spec

Use `references/openapi-spec.json` as the stable local source for methods, paths, parameters, and schemas.

---

## 中文说明

# Dub Links API

用于集成 Dub Links API 的技能，严格限定范围于 `/links*` 端点。

## API 概览

- **Base URL**：`https://api.dub.co`
- **认证**：需要 Bearer token
- **Header**：`Authorization: Bearer <DUB_API_KEY>`
- **响应格式**：JSON
- **范围**：仅限 Links 端点
- **文档**：`https://dub.co/docs/api-reference/endpoint/create-a-link`
- **Token 文档（入门）**：`https://dub.co/docs/api-reference/tokens`
- **本地快照**：`references/openapi-spec.json`

## API 密钥入门

当用户尚未拥有 API 密钥时，使用此流程：

1. 创建一个 Dub 账户/工作区（如有需要）。
2. 前往仪表盘的 token 部分（参照文档）：
   - `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 端点

### 1) 创建

- `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) 更新

- `PATCH /links/{linkId}`
- 通过 `linkId` 更新现有链接。

```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

- `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 /links/{linkId}`
- 通过 `linkId` 删除一个链接。

```bash
curl -s -X DELETE "https://api.dub.co/links/{linkId}" \
  -H "Authorization: Bearer $DUB_API_KEY" | jq '.'
```

### 5) 检索单个

- `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) 列表

- `GET /links`
- 返回带过滤条件的分页列表。
- 常用查询参数：`domain`、`search`、`tag