Create a domain

curl --request POST \
  --url https://biq.li/api/v1/domain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "host": "go.example.com"
}
'

import requests

url = "https://biq.li/api/v1/domain"

payload = { "host": "go.example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({host: 'go.example.com'})
};

fetch('https://biq.li/api/v1/domain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/domain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'host' => 'go.example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://biq.li/api/v1/domain"

	payload := strings.NewReader("{\n  \"host\": \"go.example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/domain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"host\": \"go.example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/domain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"host\": \"go.example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "domain": {
    "id": "<string>",
    "host": "go.example.com",
    "url": "<string>",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": true,
    "active": true,
    "is_subdomain": true,
    "links_count": 1,
    "claim_expires_at": "2023-11-07T05:31:56Z",
    "dns_last_checked_at": "2023-11-07T05:31:56Z",
    "dns_verified_at": "2023-11-07T05:31:56Z",
    "ssl_last_checked_at": "2023-11-07T05:31:56Z",
    "use_default_redirect": true,
    "default_redirect_url": "<string>",
    "use_not_found_redirect": true,
    "not_found_redirect_url": "<string>",
    "use_expired_redirect": true,
    "expired_redirect_url": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dns_config": {
    "host": "<string>",
    "is_subdomain": true,
    "records": [
      {
        "type": "A",
        "name": "<string>",
        "value": "<string>",
        "ttl": "auto"
      }
    ]
  },
  "created": true,
  "attached": true,
  "status": "success"
}

{
  "domain": {
    "id": "<string>",
    "host": "go.example.com",
    "url": "<string>",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": true,
    "active": true,
    "is_subdomain": true,
    "links_count": 1,
    "claim_expires_at": "2023-11-07T05:31:56Z",
    "dns_last_checked_at": "2023-11-07T05:31:56Z",
    "dns_verified_at": "2023-11-07T05:31:56Z",
    "ssl_last_checked_at": "2023-11-07T05:31:56Z",
    "use_default_redirect": true,
    "default_redirect_url": "<string>",
    "use_not_found_redirect": true,
    "not_found_redirect_url": "<string>",
    "use_expired_redirect": true,
    "expired_redirect_url": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dns_config": {
    "host": "<string>",
    "is_subdomain": true,
    "records": [
      {
        "type": "A",
        "name": "<string>",
        "value": "<string>",
        "ttl": "auto"
      }
    ]
  },
  "created": true,
  "attached": true,
  "status": "success"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

POST

domain

Create a domain

curl --request POST \
  --url https://biq.li/api/v1/domain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "host": "go.example.com"
}
'

import requests

url = "https://biq.li/api/v1/domain"

payload = { "host": "go.example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({host: 'go.example.com'})
};

fetch('https://biq.li/api/v1/domain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/domain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'host' => 'go.example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://biq.li/api/v1/domain"

	payload := strings.NewReader("{\n  \"host\": \"go.example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/domain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"host\": \"go.example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/domain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"host\": \"go.example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "domain": {
    "id": "<string>",
    "host": "go.example.com",
    "url": "<string>",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": true,
    "active": true,
    "is_subdomain": true,
    "links_count": 1,
    "claim_expires_at": "2023-11-07T05:31:56Z",
    "dns_last_checked_at": "2023-11-07T05:31:56Z",
    "dns_verified_at": "2023-11-07T05:31:56Z",
    "ssl_last_checked_at": "2023-11-07T05:31:56Z",
    "use_default_redirect": true,
    "default_redirect_url": "<string>",
    "use_not_found_redirect": true,
    "not_found_redirect_url": "<string>",
    "use_expired_redirect": true,
    "expired_redirect_url": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dns_config": {
    "host": "<string>",
    "is_subdomain": true,
    "records": [
      {
        "type": "A",
        "name": "<string>",
        "value": "<string>",
        "ttl": "auto"
      }
    ]
  },
  "created": true,
  "attached": true,
  "status": "success"
}

{
  "domain": {
    "id": "<string>",
    "host": "go.example.com",
    "url": "<string>",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": true,
    "active": true,
    "is_subdomain": true,
    "links_count": 1,
    "claim_expires_at": "2023-11-07T05:31:56Z",
    "dns_last_checked_at": "2023-11-07T05:31:56Z",
    "dns_verified_at": "2023-11-07T05:31:56Z",
    "ssl_last_checked_at": "2023-11-07T05:31:56Z",
    "use_default_redirect": true,
    "default_redirect_url": "<string>",
    "use_not_found_redirect": true,
    "not_found_redirect_url": "<string>",
    "use_expired_redirect": true,
    "expired_redirect_url": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "dns_config": {
    "host": "<string>",
    "is_subdomain": true,
    "records": [
      {
        "type": "A",
        "name": "<string>",
        "value": "<string>",
        "ttl": "auto"
      }
    ]
  },
  "created": true,
  "attached": true,
  "status": "success"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

Connect a domain you already own to the workspace bound to your API key. This endpoint does not buy or register a domain.

Authentication and permission

Use a workspace API key with Custom domains: Write (custom_domains.create). Do not send a workspace ID; the key determines it. The workspace plan must also include custom domains.

curl --request POST \
  --url https://biq.li/api/v1/domain \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"host":"go.example.com"}'

Field	Type	Description
`host`	string, required	Apex domain or subdomain, without a path. A full HTTP(S) URL is normalized to its host. Maximum 100 characters.

Biqli rejects its own application domain, malformed hosts, unsafe or blacklisted hosts, and domains claimed by another account. Unknown fields and internal numeric IDs are not accepted.

Successful response

A new claim returns 201 Created. Add every record exactly as returned:

{
  "domain": {
    "id": "biq_dom_01M18D4A8QRJY5G6K3N2W7X9TZ",
    "host": "go.example.com",
    "url": "https://go.example.com",
    "status": "pending_dns",
    "dns_status": "pending",
    "ssl_status": "pending",
    "dns_verified": false,
    "active": false,
    "is_subdomain": true,
    "links_count": 0,
    "claim_expires_at": "2026-08-30T14:30:00+00:00",
    "dns_last_checked_at": null,
    "dns_verified_at": null,
    "ssl_last_checked_at": null,
    "use_default_redirect": false,
    "default_redirect_url": null,
    "use_not_found_redirect": false,
    "not_found_redirect_url": null,
    "use_expired_redirect": false,
    "expired_redirect_url": null,
    "created_at": "2026-08-30T02:30:00+00:00",
    "updated_at": "2026-08-30T02:30:00+00:00"
  },
  "dns_config": {
    "host": "go.example.com",
    "is_subdomain": true,
    "records": [
      {"type":"CNAME","name":"go","value":"biq.li","ttl":"auto"},
      {"type":"TXT","name":"_verify.example.com","value":"domain-verify=...","ttl":"auto"}
    ]
  },
  "created": true,
  "attached": true,
  "status": "success"
}

For an apex host such as example.com, the routing record is an A record whose name is @. Subdomains use a CNAME. The TXT record proves ownership. Use the returned values rather than assuming a target. Biqli also sends the domain owner a professional setup email containing these records for a brand-new claim. It does not send that email again when an already-owned domain is attached to another workspace.

Idempotent attachment

If the same API-key owner already owns the host, Biqli safely attaches it to the current workspace and returns 200 OK. created is false; attached is true only when this call created a new workspace attachment. Its existing DNS verification and SSL state are preserved.

Next steps

Publish both records from dns_config at your DNS provider.
Use Retrieve DNS configuration whenever you need the exact values again.
Call Verify a domain after DNS propagation.
Wait until the returned domain has status: active before using it for production links.

Errors

HTTP status	Error code	Meaning
`401`	`invalid_token`	The workspace API key is missing, invalid, malformed, or revoked.
`403`	`insufficient_scope`	The key or its user cannot create domains in this workspace.
`403`	`upgrade_required`	The workspace plan does not include custom domains.
`409`	`domain_taken`	Another Biqli account has already claimed this host.
`422`	`validation_error`	The host or payload is invalid, unsafe, or unsupported.
`429`	`rate_limit_exceeded`	The workspace exceeded its API request limit.

Every error includes a request_id, also returned in X-Biq-Request-Id.

Shared API behavior

Authentication is workspace-scoped; see Authentication. Errors use the standard envelope and request IDs described in Errors, and requests are subject to Rate limits.

Authorizations

Authorization

string

header

required

A workspace API key beginning with biqli_.

Body

application/json

host

string

required

Maximum string length: 100

Example:

"go.example.com"

Response

An already-owned domain was returned or attached.

domain

object

required

Show child attributes

dns_config

object

required

Show child attributes

created

boolean

required

attached

boolean

required

status

string

required

Allowed value: "success"

GETTING STARTED

BIQLI LINKS API

Create a domain

Authentication and permission

Successful response

Idempotent attachment

Next steps

Errors

Shared API behavior

Authorizations

Body

Response

​Authentication and permission

​Successful response

​Idempotent attachment

​Next steps

​Errors

​Shared API behavior

Authorizations

Body

Response

Authentication and permission

Successful response

Idempotent attachment

Next steps

Errors

Shared API behavior