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.

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_).

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.

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"}.

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

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

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

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

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.

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

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.