Links are the bread and butter of Dub.

Everything on Dub starts with a link. Whether you’re creating:

In this guide, we’ll cover the link model, how to create links, and more.

The link model consists of the following properties:

PropertyDescriptionExample
idThe unique identifier of the link (prefixed with link_)link_eBKA4MT44XnI17hYLchkjUOd
urlThe destination URL of the linkhttps://dub.co/home
shortLinkThe shortened version of the link (including https)https://dub.link/claim
domainThe domain of the linkdub.link
keyThe short link slugclaim

For more advanced features like custom link previews, conversion tracking, and more, see the full list of properties here.

You can use the various Dub SDKs to programmatically manage your links.

The url field, representing the destination URL, is the sole mandatory parameter required for the creation of a new short link.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.create({
  url: "https://google.com",
});

Check out the full API reference for the link creation endpoint.

An existing link can be updated by providing the id to the update method. This method returns the updated link as a response.

You can use either the linkId or an externalId prefixed with ext_ which is a unique identifier for the link in your own database to associate it with the link in Dub’s system.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.update("link_eBKA4MT44XnI17hYLchkjUOd", {
  url: "https://www.google.uk", // new URL
});

Check out the full API reference for the link update endpoint.

Upserting a link is a combination of creating and updating a link. If a link with the same URL already exists, return it (or update it if there are any changes). Otherwise, a new link will be created.

This allows you to use the upsert method without the necessity of checking for the link’s existence beforehand.

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const link = await dub.links.upsert({
  url: "https://google.com", // will always be the same short link
});

Check out the full API reference for the link upsert endpoint.