> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn how to use Dub to programmatically create, update, and delete links at scale.

Links are the bread and butter of [Dub](https://dub.co).

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

* a handful of links for your marketing campaign
* hundreds of links for your [affiliate program](https://dub.co/partners)
* thousands of links, [programmatically](/docs/api-reference/links/bulk-create), for your SMS campaign

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

## The link model

The link model consists of the following properties:

| Property    | Description                                               | Example                          |
| ----------- | :-------------------------------------------------------- | :------------------------------- |
| `id`        | The unique identifier of the link (prefixed with `link_`) | `link_1KJ1H3PZGE081A22TC6PTQYJP` |
| `url`       | The destination URL of the link                           | `https://dub.co/home`            |
| `shortLink` | The shortened version of the link (including https)       | `https://dub.link/claim`         |
| `domain`    | The domain of the link                                    | `dub.link`                       |
| `key`       | The short link slug                                       | `claim`                          |

For more advanced features like [custom link previews](/help/article/custom-link-previews), [conversion tracking](/docs/concepts/attribution), and more, see the full list of properties [here](/docs/api-reference/links/create).

You can use the various [Dub SDKs](/docs/sdks/overview) to programmatically manage your links.

## Create a link

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

<CodeGroup>
  ```javascript Node.js theme={null}
  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",
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Create(ctx, &operations.CreateLinkRequestBody{
      URL: "https://google.com",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.create(request={
    "url": "https://google.com",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
    url: "https://google.com",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\CreateLinkRequestBody(
    url: 'https://google.com',
  );

  $response = $sdk->links->create(
    request: $request
  );
  ```

  ```bash cURL {5} theme={null}
  curl --request POST \
    --url https://api.dub.co/links \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://google.com"}'
  ```
</CodeGroup>

Check out the [full API reference for the link creation endpoint](/docs/api-reference/links/create).

## Update a link

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.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { Dub } from "dub";

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

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

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Update(ctx, "link_1KJ1H3PZGE081A22TC6PTQYJP", &operations.UpdateLinkRequestBody{
      URL: "https://www.google.uk", // new URL
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = dub.links.update(link_id="link_1KJ1H3PZGE081A22TC6PTQYJP", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  res = s.links.update(link_id="link_1KJ1H3PZGE081A22TC6PTQYJP", request_body={
    "url": "https://www.google.uk", // new URL
  })
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $requestBody = new Operations\UpdateLinkRequestBody(
    url: 'https://www.google.uk', // new URL
  );

  $response = $sdk->links->update(
    linkId: 'link_1KJ1H3PZGE081A22TC6PTQYJP',
    requestBody: $requestBody
  );
  ```

  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.dub.co/links/link_1KJ1H3PZGE081A22TC6PTQYJP \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://www.google.uk"}'
  ```
</CodeGroup>

Check out the [full API reference for the link update endpoint](/docs/api-reference/links/update).

## Upsert a link

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.

<CodeGroup>
  ```javascript Node.js theme={null}
  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
  });
  ```

  ```go Go theme={null}
  package main

  import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
    "os"
  )

  func main() {
    ctx := context.Background()

    s := dubgo.New(
      dubgo.WithSecurity(os.Getenv("DUB_API_KEY")),
    )

    res, err := s.Links.Upsert(ctx, &operations.UpsertLinkRequestBody{
      URL: "https://google.com",
    })

    if err != nil {
      log.Fatal(err)
    }

    if res != nil {
      // handle response
    }
  }
  ```

  ```python Python theme={null}
  import os
  import dub
  from dub.models import operations

  d = dub.Dub(
    token=os.environ['DUB_API_KEY'],
  )

  res = d.links.upsert(request={
    "url": "https://google.com",
  })
  ```

  ```ruby Ruby theme={null}
  require 'dub'

  s = ::OpenApiSDK::Dub.new
  s.config_security(
    ::OpenApiSDK::Shared::Security.new(
      token: "DUB_API_KEY",
    )
  )

  req = ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
    url: "https://google.com",
  )
  ```

  ```php PHP theme={null}
  declare(strict_types=1);

  require 'vendor/autoload.php';

  use Dub;
  use Dub\Models\Operations;

  $sdk = Dub\Dub::builder()->setSecurity('DUB_API_KEY')->build();

  $request = new Operations\UpsertLinkRequestBody(
    url: 'https://google.com',
  );

  $response = $sdk->links->upsert(
    request: $request
  );
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.dub.co/links/upsert \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{"url": "https://google.com"}'
  ```
</CodeGroup>

Check out the [full API reference for the link upsert endpoint](/docs/api-reference/links/upsert).