OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Links API
description: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
version: 0.0.1
contact:
name: Dub Support
email: support@dub.co
url: https://dub.co/support
license:
name: AGPL-3.0 license
url: https://github.com/dubinc/dub/blob/main/LICENSE.md
servers:
- url: https://api.dub.co
description: Production API
tags:
- name: Links
paths:
/links:
post:
operationId: createLink
x-speakeasy-name-override: create
x-speakeasy-usage-example: true
summary: Create a link
description: Create a link for the authenticated workspace.
tags:
- Links
security:
- token: []
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
description: The destination URL of the short link.
example: https://google.com
maxLength: 32000
type: string
domain:
description: The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains).
type: string
maxLength: 190
key:
description: The short link slug. If not provided, a random 7-character slug will be generated.
type: string
maxLength: 190
keyLength:
description: The length of the short link slug. Defaults to 7 if not provided. When used with `prefix`, the total length of the key will be `prefix.length + keyLength`.
type: number
minimum: 3
maximum: 190
externalId:
description: The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace.
example: '123456'
nullable: true
type: string
minLength: 1
maxLength: 255
tenantId:
description: The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.
nullable: true
type: string
maxLength: 255
programId:
description: The ID of the program the short link is associated with.
nullable: true
type: string
partnerId:
description: The ID of the partner the short link is associated with.
nullable: true
type: string
prefix:
description: The prefix of the short link slug for randomly-generated keys (e.g. if prefix is `/c/`, generated keys will be in the `/c/:key` format). Will be ignored if `key` is provided.
type: string
trackConversion:
description: Whether to track conversions for the short link. Defaults to `false` if not provided.
type: boolean
archived:
description: Whether the short link is archived. Defaults to `false` if not provided.
type: boolean
tagIds:
description: The unique IDs of the tags assigned to the short link.
example:
- clux0rgak00011...
anyOf:
- type: string
- type: array
items:
type: string
tagNames:
description: The unique name of the tags assigned to the short link (case insensitive).
anyOf:
- type: string
- type: array
items:
type: string
folderId:
description: The unique ID existing folder to assign the short link to.
nullable: true
type: string
comments:
description: The comments for the short link.
nullable: true
type: string
expiresAt:
description: The date and time when the short link will expire at.
nullable: true
type: string
expiredUrl:
description: The URL to redirect to when the short link has expired.
maxLength: 32000
nullable: true
type: string
password:
description: The password required to access the destination URL of the short link.
nullable: true
type: string
proxy:
description: Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
type: boolean
title:
description: 'The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
description:
description: 'The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
image:
description: 'The custom link preview image (og:image). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
video:
description: 'The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
rewrite:
description: Whether the short link uses link cloaking. Defaults to `false` if not provided.
type: boolean
ios:
description: The iOS destination URL for the short link for iOS device targeting.
nullable: true
type: string
maxLength: 32000
android:
description: The Android destination URL for the short link for Android device targeting.
nullable: true
type: string
maxLength: 32000
geo:
$ref: '#/components/schemas/linkGeoTargeting'
doIndex:
description: 'Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex'
type: boolean
utm_source:
description: The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
nullable: true
type: string
utm_medium:
description: The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
nullable: true
type: string
utm_campaign:
description: The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
nullable: true
type: string
utm_term:
description: The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
nullable: true
type: string
utm_content:
description: The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
nullable: true
type: string
ref:
description: The referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
nullable: true
type: string
webhookIds:
description: An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.
nullable: true
type: array
items:
type: string
testVariants:
nullable: true
minItems: 2
maxItems: 4
type: array
items:
type: object
properties:
url:
type: string
percentage:
type: number
minimum: 10
maximum: 90
required:
- url
- percentage
description: An array of A/B test URLs and the percentage of traffic to send to each URL.
example:
- url: https://example.com/variant-1
percentage: 50
- url: https://example.com/variant-2
percentage: 50
testStartedAt:
description: The date and time when the tests started.
nullable: true
type: string
testCompletedAt:
description: The date and time when the tests were or will be completed.
nullable: true
type: string
publicStats:
description: 'Deprecated: Use `dashboard` instead. Whether the short link''s stats are publicly accessible. Defaults to `false` if not provided.'
deprecated: true
type: boolean
tagId:
description: 'Deprecated: Use `tagIds` instead. The unique ID of the tag assigned to the short link.'
deprecated: true
nullable: true
type: string
required:
- url
responses:
'200':
description: The created link
content:
application/json:
schema:
$ref: '#/components/schemas/LinkSchema'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
get:
operationId: getLinks
x-speakeasy-name-override: list
x-speakeasy-pagination:
type: offsetLimit
inputs:
- name: page
in: parameters
type: page
- name: pageSize
in: parameters
type: limit
outputs:
results: $
summary: List all links
description: Retrieve a paginated list of links for the authenticated workspace.
tags:
- Links
security:
- token: []
parameters:
- in: query
name: domain
schema:
description: The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
type: string
description: The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
- in: query
name: tagId
schema:
description: 'Deprecated: Use `tagIds` instead. The tag ID to filter the links by.'
deprecated: true
type: string
description: 'Deprecated: Use `tagIds` instead. The tag ID to filter the links by.'
- in: query
name: tagIds
schema:
description: The tag IDs to filter the links by.
anyOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
description: The tag IDs to filter the links by.
- in: query
name: tagNames
schema:
description: The unique name of the tags assigned to the short link (case insensitive).
anyOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
description: The unique name of the tags assigned to the short link (case insensitive).
- in: query
name: folderId
schema:
description: The folder ID to filter the links by.
type: string
description: The folder ID to filter the links by.
- in: query
name: search
schema:
description: The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
type: string
description: The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
- in: query
name: userId
schema:
description: The user ID to filter the links by.
type: string
description: The user ID to filter the links by.
- in: query
name: tenantId
schema:
description: The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
type: string
description: The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
- in: query
name: showArchived
schema:
default: false
description: Whether to include archived links in the response. Defaults to `false` if not provided.
type: boolean
description: Whether to include archived links in the response. Defaults to `false` if not provided.
- in: query
name: withTags
schema:
default: false
description: DEPRECATED. Filter for links that have at least one tag assigned to them.
deprecated: true
type: boolean
description: DEPRECATED. Filter for links that have at least one tag assigned to them.
- in: query
name: endingBefore
schema:
description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
example: link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...
type: string
description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
- in: query
name: startingAfter
schema:
description: If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
example: link_1KAP4CDPBSVMMBMH9XX3YZZ0Z...
type: string
description: If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
- in: query
name: page
schema:
description: DEPRECATED. Use `startingAfter` instead.
example: 1
deprecated: true
type: number
minimum: 0
exclusiveMinimum: true
description: DEPRECATED. Use `startingAfter` instead.
- in: query
name: pageSize
schema:
default: 100
description: The number of items per page.
example: 50
type: number
minimum: 0
exclusiveMinimum: true
maximum: 100
description: The number of items per page.
responses:
'200':
description: A list of links
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LinkSchema'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/links/count:
get:
operationId: getLinksCount
x-speakeasy-name-override: count
summary: Retrieve links count
description: Retrieve the number of links for the authenticated workspace.
tags:
- Links
security:
- token: []
parameters:
- in: query
name: domain
schema:
description: The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
type: string
description: The domain to filter the links by. E.g. `ac.me`. If not provided, all links for the workspace will be returned.
- in: query
name: tagId
schema:
description: 'Deprecated: Use `tagIds` instead. The tag ID to filter the links by.'
deprecated: true
type: string
description: 'Deprecated: Use `tagIds` instead. The tag ID to filter the links by.'
- in: query
name: tagIds
schema:
description: The tag IDs to filter the links by.
anyOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
description: The tag IDs to filter the links by.
- in: query
name: tagNames
schema:
description: The unique name of the tags assigned to the short link (case insensitive).
anyOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
description: The unique name of the tags assigned to the short link (case insensitive).
- in: query
name: folderId
schema:
description: The folder ID to filter the links by.
type: string
description: The folder ID to filter the links by.
- in: query
name: search
schema:
description: The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
type: string
description: The search term to filter the links by. The search term will be matched against the short link slug and the destination url.
- in: query
name: userId
schema:
description: The user ID to filter the links by.
type: string
description: The user ID to filter the links by.
- in: query
name: tenantId
schema:
description: The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
type: string
description: The ID of the tenant that created the link inside your system. If set, will only return links for the specified tenant.
- in: query
name: showArchived
schema:
default: false
description: Whether to include archived links in the response. Defaults to `false` if not provided.
type: boolean
description: Whether to include archived links in the response. Defaults to `false` if not provided.
- in: query
name: withTags
schema:
default: false
description: DEPRECATED. Filter for links that have at least one tag assigned to them.
deprecated: true
type: boolean
description: DEPRECATED. Filter for links that have at least one tag assigned to them.
- in: query
name: groupBy
schema:
description: The field to group the links by.
anyOf:
- type: string
enum:
- domain
- type: string
enum:
- tagId
- type: string
enum:
- userId
- type: string
enum:
- folderId
description: The field to group the links by.
responses:
'200':
description: A list of links
content:
application/json:
schema:
type: number
description: The number of links matching the query.
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/links/info:
get:
operationId: getLinkInfo
x-speakeasy-name-override: get
summary: Retrieve a link
description: Retrieve the info for a link.
tags:
- Links
security:
- token: []
parameters:
- in: query
name: domain
schema:
type: string
minLength: 1
description: The domain of the link to retrieve. E.g. for `d.to/github`, the domain is `d.to`.
- in: query
name: key
schema:
type: string
minLength: 1
description: The key of the link to retrieve. E.g. for `d.to/github`, the key is `github`.
- in: query
name: linkId
schema:
description: The unique ID of the short link.
example: clux0rgak00011...
type: string
description: The unique ID of the short link.
- in: query
name: externalId
schema:
description: This is the ID of the link in the your database.
example: '123456'
type: string
description: This is the ID of the link in the your database.
responses:
'200':
description: The retrieved link
content:
application/json:
schema:
$ref: '#/components/schemas/LinkSchema'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/links/{linkId}:
patch:
operationId: updateLink
x-speakeasy-name-override: update
x-speakeasy-max-method-params: 2
summary: Update a link
description: Update a link for the authenticated workspace. If there's no change, returns it as it is.
tags:
- Links
security:
- token: []
parameters:
- in: path
name: linkId
schema:
type: string
description: The id of the link to update. You may use either `linkId` (obtained via `/links/info` endpoint) or `externalId` prefixed with `ext_`.
required: true
description: The id of the link to update. You may use either `linkId` (obtained via `/links/info` endpoint) or `externalId` prefixed with `ext_`.
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
description: The destination URL of the short link.
example: https://google.com
maxLength: 32000
type: string
domain:
description: The domain of the short link (without protocol). If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains).
type: string
maxLength: 190
key:
description: The short link slug. If not provided, a random 7-character slug will be generated.
type: string
maxLength: 190
externalId:
description: The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace.
example: '123456'
nullable: true
type: string
minLength: 1
maxLength: 255
tenantId:
description: The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.
nullable: true
type: string
maxLength: 255
programId:
description: The ID of the program the short link is associated with.
nullable: true
type: string
partnerId:
description: The ID of the partner the short link is associated with.
nullable: true
type: string
trackConversion:
description: Whether to track conversions for the short link. Defaults to `false` if not provided.
type: boolean
archived:
description: Whether the short link is archived. Defaults to `false` if not provided.
type: boolean
tagIds:
description: The unique IDs of the tags assigned to the short link.
example:
- clux0rgak00011...
anyOf:
- type: string
- type: array
items:
type: string
tagNames:
description: The unique name of the tags assigned to the short link (case insensitive).
anyOf:
- type: string
- type: array
items:
type: string
folderId:
description: The unique ID existing folder to assign the short link to.
nullable: true
type: string
comments:
description: The comments for the short link.
nullable: true
type: string
expiresAt:
description: The date and time when the short link will expire at.
nullable: true
type: string
expiredUrl:
description: The URL to redirect to when the short link has expired.
maxLength: 32000
nullable: true
type: string
password:
description: The password required to access the destination URL of the short link.
nullable: true
type: string
proxy:
description: Whether the short link uses Custom Link Previews feature. Defaults to `false` if not provided.
type: boolean
title:
description: 'The custom link preview title (og:title). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
description:
description: 'The custom link preview description (og:description). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
image:
nullable: true
anyOf:
- type: string
pattern: ^data:image\/(png|jpeg|jpg|gif|webp);base64,
- type: string
format: uri
video:
description: 'The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
nullable: true
type: string
rewrite:
description: Whether the short link uses link cloaking. Defaults to `false` if not provided.
type: boolean
ios:
description: The iOS destination URL for the short link for iOS device targeting.
nullable: true
type: string
maxLength: 32000
android:
description: The Android destination URL for the short link for Android device targeting.
nullable: true
type: string
maxLength: 32000
geo:
allOf:
- $ref: '#/components/schemas/linkGeoTargeting'
doIndex:
description: 'Allow search engines to index your short link. Defaults to `false` if not provided. Learn more: https://d.to/noindex'
type: boolean
utm_source:
description: The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.
nullable: true
type: string
utm_medium:
description: The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.
nullable: true
type: string
utm_campaign:
description: The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.
nullable: true
type: string
utm_term:
description: The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.
nullable: true
type: string
utm_content:
description: The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.
nullable: true
type: string
ref:
description: The referral tag of the short link. If set, this will populate or override the `ref` query parameter in the destination URL.
nullable: true
type: string
webhookIds:
description: An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.
nullable: true
type: array
items:
type: string
testVariants:
nullable: true
minItems: 2
maxItems: 4
type: array
items:
type: object
properties:
url:
type: string
percentage:
type: number
minimum: 10
maximum: 90
required:
- url
- percentage
description: An array of A/B test URLs and the pe
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-links-api-openapi.yml