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

# Tags

> Organise links and QR codes, and filter by them.

Tags are free-form labels on links and QR codes. They are how you find things again once you have more than a few hundred.

## Tagging at creation

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -F "destination_url=https://example.com/spring-sale" \
  -F 'tags=["spring-2026","email"]'
```

```javascript Node.js theme={null}
const body = new FormData();
body.append("destination_url", "https://example.com/spring-sale");
body.append("tags", "[\"spring-2026\",\"email\"]");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/create_shortlink',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'destination_url': 'https://example.com/spring-sale',
        'tags': '["spring-2026","email"]',
    },
)
payload = response.json()
```

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/create_shortlink"
	form0 := url.Values{
		"destination_url": {"https://example.com/spring-sale"},
		"tags": {"[\"spring-2026\",\"email\"]"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/create_shortlink")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("destination_url" => "https://example.com/spring-sale", "tags" => "[\"spring-2026\",\"email\"]")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/create_shortlink');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['destination_url' => 'https://example.com/spring-sale', 'tags' => '["spring-2026","email"]']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

## Tagging an existing link

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/add_tags" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d "shortlink_name=SHORT-0001" \
  -d 'tags=["priority"]'
```

```javascript Node.js theme={null}
const body = new URLSearchParams();
body.append("shortlink_name", "SHORT-0001");
body.append("tags", "[\"priority\"]");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/add_tags", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/add_tags',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'shortlink_name': 'SHORT-0001',
        'tags': '["priority"]',
    },
)
payload = response.json()
```

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/add_tags"
	form0 := url.Values{
		"shortlink_name": {"SHORT-0001"},
		"tags": {"[\"priority\"]"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/add_tags")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("shortlink_name" => "SHORT-0001", "tags" => "[\"priority\"]")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/add_tags');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['shortlink_name' => 'SHORT-0001', 'tags' => '["priority"]']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

Adding is additive — existing tags stay.

## Removing

From one link:

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/shortlinks/remove_tags" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d "shortlink_name=SHORT-0001" \
  -d 'tags=["priority"]'
```

```javascript Node.js theme={null}
const body = new URLSearchParams();
body.append("shortlink_name", "SHORT-0001");
body.append("tags", "[\"priority\"]");

const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/remove_tags", {
  method: "POST",
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
  body,
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.dashlink.ai/api/v1/shortlinks/remove_tags',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'shortlink_name': 'SHORT-0001',
        'tags': '["priority"]',
    },
)
payload = response.json()
```

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"net/url"
	"strings"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/remove_tags"
	form0 := url.Values{
		"shortlink_name": {"SHORT-0001"},
		"tags": {"[\"priority\"]"},
	}
	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/remove_tags")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("shortlink_name" => "SHORT-0001", "tags" => "[\"priority\"]")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/remove_tags');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['shortlink_name' => 'SHORT-0001', 'tags' => '["priority"]']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

> [!WARNING]
>
> The `tags` module has its own `remove_tags`, and calling it **without** `docname` deletes the tag from every one of your links, not just one:
>
> ```bash cURL theme={null}
> # Removes "priority" from one link.
> curl -X POST "https://api.dashlink.ai/api/v1/tags/remove_tags" \
>   -H "X-API-Key: $DASHLINK_API_KEY" \
>   -d "doctype=Shortlink" \
>   -d "docname=SHORT-0001" \
>   -d 'tags=["priority"]'
>
> # Deletes the tag everywhere in the organization.
> curl -X POST "https://api.dashlink.ai/api/v1/tags/remove_tags" \
>   -H "X-API-Key: $DASHLINK_API_KEY" \
>   -d 'tags=["priority"]'
> ```
>
> ```javascript Node.js theme={null}
> {
>   // Removes "priority" from one link.
>   const body = new URLSearchParams();
>   body.append("doctype", "Shortlink");
>   body.append("docname", "SHORT-0001");
>   body.append("tags", "[\"priority\"]");
>
>   const response = await fetch("https://api.dashlink.ai/api/v1/tags/remove_tags", {
>     method: "POST",
>     headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
>     body,
>   });
>   const payload = await response.json();
> }
>
> {
>   // Deletes the tag everywhere in the organization.
>   const body = new URLSearchParams();
>   body.append("tags", "[\"priority\"]");
>
>   const response = await fetch("https://api.dashlink.ai/api/v1/tags/remove_tags", {
>     method: "POST",
>     headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
>     body,
>   });
>   const payload = await response.json();
> }
> ```
>
> ```python Python theme={null}
> import os
> import requests
>
> response = requests.post(
>     'https://api.dashlink.ai/api/v1/tags/remove_tags',
>     headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
>     data={
>         'doctype': 'Shortlink',
>         'docname': 'SHORT-0001',
>         'tags': '["priority"]',
>     },
> )
> payload = response.json()
>
> response = requests.post(
>     'https://api.dashlink.ai/api/v1/tags/remove_tags',
>     headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
>     data={
>         'tags': '["priority"]',
>     },
> )
> payload = response.json()
> ```
>
> ```go Go theme={null}
> package main
>
> import (
> 	"fmt"
> 	"io"
> 	"net/http"
> 	"os"
> 	"net/url"
> 	"strings"
> )
>
> func main() {
> 	endpoint0 := "https://api.dashlink.ai/api/v1/tags/remove_tags"
> 	form0 := url.Values{
> 		"doctype": {"Shortlink"},
> 		"docname": {"SHORT-0001"},
> 		"tags": {"[\"priority\"]"},
> 	}
> 	req0, err0 := http.NewRequest("POST", endpoint0, strings.NewReader(form0.Encode()))
> 	if err0 != nil {
> 		panic(err0)
> 	}
> 	req0.Header.Set("Content-Type", "application/x-www-form-urlencoded")
> 	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
> 	resp0, err0b := http.DefaultClient.Do(req0)
> 	if err0b != nil {
> 		panic(err0b)
> 	}
> 	defer resp0.Body.Close()
> 	body0, _ := io.ReadAll(resp0.Body)
> 	fmt.Println(string(body0))
>
> 	endpoint1 := "https://api.dashlink.ai/api/v1/tags/remove_tags"
> 	form1 := url.Values{
> 		"tags": {"[\"priority\"]"},
> 	}
> 	req1, err1 := http.NewRequest("POST", endpoint1, strings.NewReader(form1.Encode()))
> 	if err1 != nil {
> 		panic(err1)
> 	}
> 	req1.Header.Set("Content-Type", "application/x-www-form-urlencoded")
> 	req1.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
> 	resp1, err1b := http.DefaultClient.Do(req1)
> 	if err1b != nil {
> 		panic(err1b)
> 	}
> 	defer resp1.Body.Close()
> 	body1, _ := io.ReadAll(resp1.Body)
> 	fmt.Println(string(body1))
> }
>
> ```
>
> ```ruby Ruby theme={null}
> require "net/http"
> require "json"
> require "uri"
>
> uri0 = URI("https://api.dashlink.ai/api/v1/tags/remove_tags")
> request0 = Net::HTTP::Post.new(uri0)
> request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
> request0.set_form_data("doctype" => "Shortlink", "docname" => "SHORT-0001", "tags" => "[\"priority\"]")
> response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
>   http.request(request0)
> end
> payload0 = JSON.parse(response0.body)
>
> uri1 = URI("https://api.dashlink.ai/api/v1/tags/remove_tags")
> request1 = Net::HTTP::Post.new(uri1)
> request1["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
> request1.set_form_data("tags" => "[\"priority\"]")
> response1 = Net::HTTP.start(uri1.hostname, uri1.port, use_ssl: true) do |http|
>   http.request(request1)
> end
> payload1 = JSON.parse(response1.body)
> ```
>
> ```php PHP theme={null}
> <?php
> $ch0 = curl_init('https://api.dashlink.ai/api/v1/tags/remove_tags');
> curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
> curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'POST');
> curl_setopt($ch0, CURLOPT_HTTPHEADER, [
>     "X-API-Key: " . getenv("DASHLINK_API_KEY"),
> ]);
> curl_setopt($ch0, CURLOPT_POSTFIELDS, http_build_query(['doctype' => 'Shortlink', 'docname' => 'SHORT-0001', 'tags' => '["priority"]']));
> $payload0 = json_decode(curl_exec($ch0), true);
> curl_close($ch0);
>
> $ch1 = curl_init('https://api.dashlink.ai/api/v1/tags/remove_tags');
> curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
> curl_setopt($ch1, CURLOPT_CUSTOMREQUEST, 'POST');
> curl_setopt($ch1, CURLOPT_HTTPHEADER, [
>     "X-API-Key: " . getenv("DASHLINK_API_KEY"),
> ]);
> curl_setopt($ch1, CURLOPT_POSTFIELDS, http_build_query(['tags' => '["priority"]']));
> $payload1 = json_decode(curl_exec($ch1), true);
> curl_close($ch1);
> ```
>
> Both return `200`. Pass `docname` unless you genuinely mean the second one.

## Filtering by tag

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=["spring-2026"]&per_page=100" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=[\"spring-2026\"]&per_page=100", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=["spring-2026"]&per_page=100',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=[\"spring-2026\"]&per_page=100"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=[\"spring-2026\"]&per_page=100")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?tags=["spring-2026"]&per_page=100');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

Several tags narrow the result — links must carry all of them:

```bash theme={null}
?tags=["spring-2026","email"]
```

Works the same on `get_qrcodes` and `search_shortlinks`.

## Listing tags

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

```python Python theme={null}
import os
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

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

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/tags/get_all_tags?per_page=100');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

Paginated like any other list. Supports `search`.

## A scheme that holds up

Tags are created by being used, so without a convention you end up with `email`, `Email` and `e-mail` as three separate tags.

Use a prefix per dimension:

```
channel:email      campaign:spring-2026      owner:growth
channel:social     campaign:q2-launch        owner:product
```

Then filtering by dimension is obvious, and a typo is visible rather than silently creating a fourth tag.

Normalise in code:

```python theme={null}
def normalize_tag(value):
    return value.strip().lower().replace(" ", "-")
```

> [!TIP]
>
> Tags are for how *you* organise links. UTM parameters are for how your analytics tool attributes traffic. Use tags to find links in Dashlink; use UTMs to attribute sessions elsewhere. They are not substitutes.


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