dub-links-api

name	dub-links-api
description	Integrates Dub Links API endpoints to create, update, delete, retrieve, list, count, and run bulk operations on short links. Use when the user asks for "dub links api", "create link dub", "upsert link dub", "list links", "count links", "bulk links", or lookups by 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.

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.