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

# Custom domains

> Connect a domain you own, verify it, and get a certificate.

**1. Add the domain**

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/domains/create_domain" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d "domain_name=go.example.com" \
  -d 'verification_method=DNS Record'
```

```javascript Node.js theme={null}
const body = new URLSearchParams();
body.append("domain_name", "go.example.com");
body.append("verification_method", "DNS Record");

const response = await fetch("https://api.dashlink.ai/api/v1/domains/create_domain", {
  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/domains/create_domain',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'domain_name': 'go.example.com',
        'verification_method': 'DNS Record',
    },
)
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/domains/create_domain"
	form0 := url.Values{
		"domain_name": {"go.example.com"},
		"verification_method": {"DNS Record"},
	}
	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/domains/create_domain")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("domain_name" => "go.example.com", "verification_method" => "DNS Record")
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/domains/create_domain');
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(['domain_name' => 'go.example.com', 'verification_method' => 'DNS Record']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

Use a subdomain such as `go.` or `links.` rather than your apex domain — pointing the apex at a link service takes your website with it.

**2. Get the DNS records**

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/domains/get_domain_verification_info?id=DOMAIN-0001" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/domains/get_domain_verification_info?id=DOMAIN-0001", {
  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/domains/get_domain_verification_info?id=DOMAIN-0001',
    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/domains/get_domain_verification_info?id=DOMAIN-0001"
	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/domains/get_domain_verification_info?id=DOMAIN-0001")
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/domains/get_domain_verification_info?id=DOMAIN-0001');
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);
```

Two records: a `TXT` proving ownership, and a `CNAME` routing traffic.

**3. Create them at your DNS provider**

Exactly as returned. A trailing dot, a missing one, or a provider that silently appends your domain to the record name are all enough to fail verification.

> [!TIP]
>
> Many providers append the zone automatically. If the record name comes back as `_dashlink.go.example.com`, you may need to enter only `_dashlink.go`. Check what your provider shows after saving.

**4. Verify**

```bash cURL theme={null}
curl -X POST "https://api.dashlink.ai/api/v1/domains/verify_domain" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  -d "id=DOMAIN-0001"
```

```javascript Node.js theme={null}
const body = new URLSearchParams();
body.append("id", "DOMAIN-0001");

const response = await fetch("https://api.dashlink.ai/api/v1/domains/verify_domain", {
  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/domains/verify_domain',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
    data={
        'id': 'DOMAIN-0001',
    },
)
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/domains/verify_domain"
	form0 := url.Values{
		"id": {"DOMAIN-0001"},
	}
	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/domains/verify_domain")
request0 = Net::HTTP::Post.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
request0.set_form_data("id" => "DOMAIN-0001")
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/domains/verify_domain');
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(['id' => 'DOMAIN-0001']));
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

DNS propagation takes anywhere from a minute to a few hours. Poll rather than assuming the first attempt will work.

**5. Wait for the certificate**

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/domains/get_domain_ssl_status?id=DOMAIN-0001" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/domains/get_domain_ssl_status?id=DOMAIN-0001", {
  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/domains/get_domain_ssl_status?id=DOMAIN-0001',
    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/domains/get_domain_ssl_status?id=DOMAIN-0001"
	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/domains/get_domain_ssl_status?id=DOMAIN-0001")
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/domains/get_domain_ssl_status?id=DOMAIN-0001');
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);
```

Issued automatically after verification, usually within minutes. Links work once this reports issued.

## Polling properly

```python theme={null}
import time

def wait_for_domain(domain_id, timeout=3600, interval=30):
    deadline = time.time() + timeout

    while time.time() < deadline:
        response = requests.post(
            f"{BASE}/domains/verify_domain",
            headers=HEADERS,
            data={"id": domain_id},
        )
        payload = response.json()

        if "data" in payload:
            return payload["data"]

        # VERIFICATION_FAILED here means "not visible yet", which is the
        # normal state while DNS propagates. Anything else is a real error
        # and will not fix itself.
        if payload["error"].get("code") != "VERIFICATION_FAILED":
            raise RuntimeError(payload["error"]["message"])

        time.sleep(interval)

    raise TimeoutError("Domain did not verify within the timeout")
```

## When verification keeps failing

> [accordion] Check what is actually published
>
> ```bash theme={null}
> dig TXT _dashlink.go.example.com +short
> dig CNAME go.example.com +short
> ```
>
> Query a public resolver rather than your own — your network may be caching an older answer.

> [accordion] The record name got doubled
>
> `_dashlink.go.example.com.example.com` is the classic symptom of a provider appending the zone to a name you already qualified.

> [accordion] A proxy is in front of it
>
> If your DNS provider offers proxying — Cloudflare's orange cloud — turn it off for this record. A proxied CNAME resolves to the proxy, not to us.

> [accordion] A conflicting record exists
>
> A hostname cannot have a CNAME alongside an A or AAAA record. Remove the others.

## File verification

If you cannot change DNS but can publish files:

```bash theme={null}
-d "verification_method=File Upload"
```

You then serve a verification file at `https://go.example.com/dashlink-verification.txt`. You will still need a DNS record to route traffic, so this only helps when the two are managed by different people.


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