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:

Create a Dub account/workspace (if needed).
Go to the dashboard token section (per docs):
- ```
https://dub.co/docs/api-reference/tokens
```
Generate an API key and export it in shell:
- ```
export DUB_API_KEY="..."
```

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

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

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

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

7) Count

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

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

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

Detect intent: create/update/upsert/delete/get/list/count/bulk.
Validate minimum inputs (
```
url
```
,
```
linkId
```
, filters, bulk ids).
Execute request with
```
curl -s
```
and Bearer header.
Parse with
```
jq
```
and verify logical operation result.
Respond first with a useful snapshot:
- ```
id
```
  ,
```
shortLink
```
  ,
```
url
```
  , and
```
archived
```
  status when relevant.
For lists, provide a short table with relevant columns.
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

NPX Install

Tags

SKILL.md Content

Dub Links API

API Overview

API Key Onboarding

Links Endpoints

1) Create

2) Update

3) Upsert

4) Delete

5) Retrieve one

6) List

7) Count

8) Bulk create

9) Bulk update

10) Bulk delete

Key Fields

Recommended Workflow

Error Handling

Presenting Results

Out of Scope

OpenAPI Spec