Dub Links API

openapi: 3.0.3
info:
  title: Dub 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: [email protected]
    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
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

# --- truncated at 32 KB (598 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-openapi.yml