> ## 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.

# Quickstart

> Create your first Shortlink and read its analytics.

About five minutes, assuming you have a Dashlink account.

**1. Create an API key**

In the [dashboard](https://app.dashlink.ai), go to **Settings → API Keys** and create one. Choose the `organization` scope so the key can see links your whole team creates.

> [!WARNING]
>
> Copy it now. Dashlink stores only a hash of the key, so it cannot be shown again.

```bash theme={null}
export DASHLINK_API_KEY="dlk_live_..."
```

**2. Check the key works**

Listing links is the cheapest way to confirm the key authenticates:

```bash theme={null}
curl "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?per_page=1" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

A working key returns a `data` object. If you get `401`, the key is wrong or revoked; if `403`, it is valid but not permitted — check its permissions.

**3. Create a link**

```bash 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 "title=Spring sale"
```

`destination_url` is the only required field. Leave `domain` out and your default domain is used; leave `back_half` out and one is generated.

The response carries the link, including the `shortlink_url` to share and the `name` you will use to refer to it later.

**4. Read its analytics**

Use the `name` from the previous step:

```bash theme={null}
curl "https://api.dashlink.ai/api/v1/analytics/get_shortlink_metrics_aggregation\
?name=SHORT-0001&date_from=2026-01-01&date_to=2026-01-31&metric=country" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

> [!NOTE]
>
> A brand-new link has no clicks yet, so expect an empty result. Analytics are near-real-time but not instant.

## Creating links programmatically

```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 "title=Spring sale"

# data and error are mutually exclusive, so one check covers
# every failure mode the API has.
#   .data   -> the link
#   .error  -> {message, status_code, code}
```

```javascript Node.js theme={null}
const BASE = "https://api.dashlink.ai/api/v1";
const HEADERS = { "X-API-Key": process.env.DASHLINK_API_KEY };

async function createLink(destinationUrl, fields = {}) {
  const body = new FormData();
  body.append("destination_url", destinationUrl);
  for (const [key, value] of Object.entries(fields)) {
    body.append(key, value);
  }

  const response = await fetch(`${BASE}/shortlinks/create_shortlink`, {
    method: "POST",
    headers: HEADERS,
    body,
  });
  const payload = await response.json();

  // data and error are mutually exclusive.
  if (payload.error) throw new Error(payload.error.message);

  return payload.data;
}

const link = await createLink("https://example.com/spring-sale", {
  title: "Spring sale",
});
```

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

BASE = "https://api.dashlink.ai/api/v1"
HEADERS = {"X-API-Key": os.environ["DASHLINK_API_KEY"]}


def create_link(destination_url, title=None, **fields):
    response = requests.post(
        f"{BASE}/shortlinks/create_shortlink",
        headers=HEADERS,
        data={"destination_url": destination_url, "title": title, **fields},
    )
    payload = response.json()

    # data and error are mutually exclusive, so this one check covers
    # every failure mode the API has.
    if "error" in payload:
        raise RuntimeError(payload["error"]["message"])

    return payload["data"]


link = create_link("https://example.com/spring-sale", title="Spring sale")
print(link)
```

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

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"strings"
)

const base = "https://api.dashlink.ai/api/v1"

func createLink(fields url.Values) (map[string]any, error) {
	req, _ := http.NewRequest("POST",
		base+"/shortlinks/create_shortlink",
		strings.NewReader(fields.Encode()))
	req.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var payload struct {
		Data  map[string]any `json:"data"`
		Error *struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
		return nil, err
	}

	// data and error are mutually exclusive.
	if payload.Error != nil {
		return nil, fmt.Errorf("%s", payload.Error.Message)
	}

	return payload.Data, nil
}

func main() {
	link, err := createLink(url.Values{
		"destination_url": {"https://example.com/spring-sale"},
		"title":           {"Spring sale"},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(link)
}
```

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

BASE = "https://api.dashlink.ai/api/v1".freeze
HEADERS = { "X-API-Key" => ENV.fetch("DASHLINK_API_KEY") }.freeze

def create_link(destination_url, **fields)
  uri = URI("#{BASE}/shortlinks/create_shortlink")

  request = Net::HTTP::Post.new(uri, HEADERS)
  request.set_form_data(destination_url: destination_url, **fields)

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  payload = JSON.parse(response.body)

  # data and error are mutually exclusive.
  raise payload["error"]["message"] if payload.key?("error")

  payload["data"]
end

link = create_link("https://example.com/spring-sale", title: "Spring sale")
puts link
```

```php PHP theme={null}
<?php
const BASE = "https://api.dashlink.ai/api/v1";

function create_link(string $destinationUrl, array $fields = []): array
{
    $ch = curl_init(BASE . "/shortlinks/create_shortlink");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "X-API-Key: " . getenv("DASHLINK_API_KEY"),
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(
        ["destination_url" => $destinationUrl] + $fields
    ));

    $payload = json_decode(curl_exec($ch), true);
    curl_close($ch);

    // data and error are mutually exclusive.
    if (isset($payload["error"])) {
        throw new RuntimeException($payload["error"]["message"]);
    }

    return $payload["data"];
}

$link = create_link("https://example.com/spring-sale", ["title" => "Spring sale"]);
print_r($link);
```

## Where to go next

> [card] [Custom back halves](https://docs.dashlink.ai/guides/links/custom-back-halves.md)
>
> Choose the path instead of taking a generated one.

> [card] [Bulk operations](https://docs.dashlink.ai/guides/links/bulk-operations.md)
>
> Create and delete many links in one request.

> [card] [Branded links](https://docs.dashlink.ai/guides/branded-links/introduction.md)
>
> Serve links from your own domain.

> [card] [Analytics](https://docs.dashlink.ai/guides/analytics/introduction.md)
>
> Read clicks, scans and visitors.


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