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

# Short links

> Tracked short links for bios, video descriptions and creators. Each click adds your UTMs to the target and records a link_clicked event.

A short video (YouTube Shorts, TikTok, Reels) can carry one link, often to a Steam page, itch.io or Discord. Those sites do not run your analytics, so a plain link tells you nothing. A **short link** gives each post, channel and creator its own link. When someone opens it, ManaLens:

1. records a `link_clicked` event in your project, and
2. sends the visitor on to the target with your UTMs added (HTTP 302).

Open **Links** in the project sidebar to manage them.

## Create a link

Click **New link** and enter:

| Field | Description |
| - | - |
| **Target URL** | Where visitors go. A full `http` or `https` URL on your project domain or a subdomain, on a host in **Allowed origins** (project settings), or on a game store: Steam (`store.steampowered.com`, `s.team`), itch.io, Epic Games Store, GOG, App Store, Google Play, PlayStation Store, Xbox, Nintendo and Discord (`discord.gg`, `discord.com`). To link to another site, add its host to Allowed origins first. |
| **Slug** | Optional. 3 to 64 characters: `a` to `z`, `0` to `9` and `-`. Slugs are not case sensitive and are unique across all projects. Leave it empty for a random 7-character slug. A slug is never given to another project, even after its link, project or workspace is deleted or the slug is changed. Old posts and videos can never send visitors to someone else's page. |
| **Label** | Optional note, for example `YouTube bio`. |
| **Creator**, **Channel** | Optional tags. They are sent with every click, so you can split clicks by creator or channel. |
| **UTM builder** | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term`. |

The dialog shows a live preview of the URL that visitors land on.

### How UTMs are added

* Each UTM you set is added to the target's query string.
* A UTM that the target URL already has is kept as it is. Your link's value does not replace it.
* A link with no `utm_content` gets its slug as `utm_content`. The [Attribution](https://docs.manalens.dev/attribution/models.md) page groups by this value as **Short link**.
* A link with a **Creator** gets `ref` set to the creator's referral code: the name in upper case, with spaces and other characters made into hyphens (`Jane Doe` is `JANE-DOE`). The Attribution page groups by it as **Creator**. A code that a player types in game (see [Referral codes](https://docs.manalens.dev/features/referral-codes.md)) credits the same creator. A target that already has `ref`, `referral` or `referral_code` keeps its own value. A `ref` puts the visit in the Referrals channel.
* Other query parameters and the `#fragment` stay as they are.
* Query parameters on the short link itself are not passed on. The redirect uses only the stored target.

### Links to Steam

Steam's [UTM Analytics](https://partner.steamgames.com/doc/marketing/utm_analytics) reads the same five UTM fields. It counts only `store.steampowered.com/app/<id>` and `/sale/<name>` pages, and only links with `utm_source` or `utm_campaign`. The editor warns you when a Steam target breaks one of these rules. Keep the number of different UTM values small: Steam hides combinations with little traffic. Use **Test a UTM Link** in Steamworks to confirm a new link.

## Bulk create

Click **Bulk create** and paste up to 100 rows from a spreadsheet (tab separated) or a CSV. The columns are:

```
url, slug, utm_source, utm_medium, utm_campaign, utm_content, utm_term, label, creator, channel
```

Only `url` is required. A first row with column names lets you use another order. The result lists the new short link or the error for each row; a bad row does not stop the others.

## Clicks, QR codes and archive

* The **Clicks** column counts `link_clicked` events in the selected date range. The filter menu and segments apply. Bots (link preview crawlers, for example) are labelled `device: bot` and not counted.
* **QR code** shows an SVG QR code of the short link. **Download SVG** saves it for print or video.
* **CSV** downloads all links with their short URL and clicks.
* **Archive** turns a link off: the short link shows a "Link not found" page (HTTP 404). Archived links keep their history and can be restored.

## The link\_clicked event

Each click is a server-side custom event (`channel: server`), so it shows in [Activity](https://docs.manalens.dev/features/activity.md) and can be a [funnel](https://docs.manalens.dev/features/funnels.md) step.

| Field | Value |
| - | - |
| `event` | `link_clicked` |
| `properties.slug`, `properties.link_id` | The link |
| `properties.target_host` | Host of the target, for example `store.steampowered.com` |
| `properties.creator`, `properties.channel`, `properties.campaign` | Link tags and the final `utm_campaign` |
| `context.utm_*`, `context.ref` | The UTMs and the creator code in the final URL |
| `context.referrer` | Origin of the page that opened the link, for example `https://www.youtube.com` |
| `context.channel_type` | Acquisition channel, for example `Organic Video` |
| `context.country`, `device`, `os`, `browser` | Derived as for other events |

Privacy: the redirect sets no cookie. The IP address is used only for the country lookup and the user agent only for device, OS and browser; neither is stored. Each click gets a new random anonymous ID, so a click is not joined to a later visit on your site. To follow visitors after the click, send them to your own site: the UTMs on the landing page are captured by the SDK as usual.

## API

Viewers can read links; editors, admins and owners can change them. Every change is in the workspace audit log (`link.created`, `link.updated`, `link.archived`).

| Method | Path | Description |
| - | - | - |
| `GET` | `/v0/projects/:projectId/links?status=active\|archived\|all` | List links with `short_link` and `destination` |
| `POST` | `/v0/projects/:projectId/links` | Create one link: `url` (required), `slug`, `utm_*`, `label`, `creator`, `channel` |
| `POST` | `/v0/projects/:projectId/links/bulk` | `{ "links": [...] }`, 1 to 100 links; one result per item |
| `PATCH` | `/v0/projects/:projectId/links/:linkId` | Change fields; `{ "archived": true }` archives |
| `GET` | `/v0/projects/:projectId/links/clicks` | Clicks by `slug` and `day` for the date range and filters |
| `GET` | `/l/:slug` | Public redirect (302, `Cache-Control: no-store`) |

The redirect always works. Clicks count against the per-project ingest limit (`INGEST_PROJECT_EVENTS_PER_MINUTE`) in their own bucket; over the limit, visitors are still redirected, but those clicks are not recorded. HEAD requests (link previews) are never recorded. Set `SHORT_LINK_BASE_URL` on the API (for example `https://go.example.com/l`) to show full short URLs; the address must route to the API's `/l/` path.


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