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

# Introduction

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

Links are the bread and butter of [CodeQR](https://codeqr.io).

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

* a handful of links for your marketing campaign
* hundreds of links for your affiliate program
* thousands of links, [programmatically](/api-reference/endpoint/bulk-create-links), 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_eBKA4MT44XnI17hYLchkjUOd` |
| `url` | The destination URL of the link | `https://codeqr.io/home` |
| `shortLink` | The shortened version of the link (including https) | `https://codeqr.link/claim` |
| `domain` | The domain of the link | `codeqr.link` |
| `key` | The short link slug | `claim` |

For more advanced features like [custom link previews](https://codeqr.io/help/article/custom-link-previews), [conversion tracking](/conversions/quickstart), and more, see the full list of properties [here](/api-reference/endpoint/create-a-link).

You can use the various [CodeQR SDKs](/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>
  ```bash cURL {5} theme={null}
  curl --request POST \
    --url https://api.codeqr.io/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](/api-reference/endpoint/create-a-link).

## 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 CodeQR's system.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \
    --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](/api-reference/endpoint/update-a-link).

## 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>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.codeqr.io/links/update \
    --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](/api-reference/endpoint/upsert-a-link).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.