Domains

Custom domains let your short links use your own branded hostname (go.acme.com/summer) instead of the shared Link Squeeze domain. Adding one through the API runs the same DNS check and free SSL certificate provisioning as adding one from the dashboard.

Method	Path	Scope
`GET`	`/v1/domains`	`domains:read`
`POST`	`/v1/domains`	`domains:write`
`GET`	`/v1/domains/{id}`	`domains:read`
`PATCH`	`/v1/domains/{id}`	`domains:write`
`POST`	`/v1/domains/{id}/verify`	`domains:write`
`DELETE`	`/v1/domains/{id}`	`domains:write`

The domain object


{
  "id": "7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37",
  "hostname": "go.acme.com",
  "not_found_url": "https://acme.com/404",
  "verification_status": "pending",
  "verification": {
    "record_type": "CNAME",
    "record_name": "go.acme.com",
    "record_value": "app.linksqueeze.io",
    "instructions": "Add this CNAME record at your DNS provider, then call POST https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37/verify to check status."
  },
  "created_at": "2026-08-28T10:14:02.000000Z",
  "updated_at": "2026-08-28T10:14:02.000000Z"
}

Field	Type	Description
`id`	uuid	The domain’s identifier
`hostname`	string	The domain itself
`not_found_url`	string \| null	Where visitors are sent when a slug on this domain does not resolve
`verification_status`	string	One of `verified`, `pending`, `inactive`, or `unverified`
`verification`	object	The DNS record to add. Present only while the domain is not yet verified.
`created_at`	timestamp	When the domain was added
`updated_at`	timestamp	When the domain was last modified

Verification statuses

Status	Meaning
`pending`	The domain has been added and is waiting on DNS propagation or certificate issuance
`verified`	DNS resolves correctly and an SSL certificate has been issued — the domain is live
`inactive`	The domain has been deactivated and is not serving links
`unverified`	No verification state has been recorded yet

The verification object disappears from the response once the domain reaches verified, so its presence is a reliable signal that there is still DNS work to do.

Set up a custom domain

Add the domain

POST /v1/domains with the hostname. The response comes back pending, with the exact CNAME record to create in its verification object.

Create the DNS record

At your DNS provider, add the CNAME record named in verification.record_name pointing at verification.record_value (app.linksqueeze.io).

Verify

Call POST /v1/domains/{id}/verify to check propagation on demand. Link Squeeze also checks in the background, so this step is optional — it just gets you an answer sooner.

Wait for the certificate

Once DNS resolves, certificate issuance starts automatically. verification_status flips to verified when the certificate is live. DNS propagation can take up to 24–48 hours.

List domains


GET /v1/domains

Scope: domains:read

Returns your domains, newest first, in the standard paginated shape. Supports page and per_page (default 15, maximum 100).


curl https://app.linksqueeze.io/api/v1/domains \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Add a domain


POST /v1/domains

Scope: domains:write

Field	Type	Required	Description
`hostname`	string	Yes	The domain to add, maximum 255 characters. Must be a valid hostname and not already registered on Link Squeeze.
`not_found_url`	string \| null	No	Where to send visitors when a slug does not resolve. Must be a valid URL, maximum 2048 characters.

Returns 201 Created with the domain object in pending status.


curl -X POST https://app.linksqueeze.io/api/v1/domains \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "hostname": "go.acme.com",
    "not_found_url": "https://acme.com/404"
  }'

Adding a domain also queues the background DNS propagation check, so it will be verified in due course whether or not you call the verify endpoint.

Hostnames are unique across all of Link Squeeze, not just within your account. A domain already registered by anyone is rejected with 422.

Retrieve a domain


GET /v1/domains/{id}

Scope: domains:read

Poll this endpoint to watch verification_status move from pending to verified.


curl https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Update a domain


PATCH /v1/domains/{id}

Scope: domains:write

Field	Type	Description
`hostname`	string	Rename the domain. Must be a valid, unused hostname.
`not_found_url`	string \| null	Change or clear the not-found redirect.

Returns 200 OK with the updated domain object.


curl -X PATCH https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "not_found_url": "https://acme.com/gone" }'

Changing hostname does not move the DNS record or the SSL certificate. The new hostname needs its own CNAME record and its own certificate before links on it will resolve.

Verify a domain


POST /v1/domains/{id}/verify

Scope: domains:write

Runs the DNS check immediately rather than waiting for the background job. Takes no request body.

Always returns 202 Accepted — verification is asynchronous, and this endpoint reports what happened rather than the final outcome. The response is the domain object plus a top-level message:


{
  "data": {
    "id": "7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37",
    "hostname": "go.acme.com",
    "verification_status": "pending",
    "verification": { "record_type": "CNAME", "record_name": "go.acme.com", "record_value": "app.linksqueeze.io", "instructions": "..." },
    "created_at": "2026-08-28T10:14:02.000000Z",
    "updated_at": "2026-08-28T10:14:02.000000Z"
  },
  "message": "DNS is correctly configured. SSL certificate provisioning has started."
}

`message`	What it means
`DNS is correctly configured. SSL certificate provisioning has started.`	The CNAME resolved. Certificate issuance has begun.
`DNS record not found yet. Add the CNAME record shown below, then try again.`	The record is missing or has not propagated. The background check was requeued.
`This domain is already verified.`	Nothing to do.

verification_status stays pending in the response even when the DNS check passes. The status only becomes verified once the certificate has actually been issued, which happens asynchronously — poll GET /v1/domains/{id} to observe it.

Delete a domain


DELETE /v1/domains/{id}

Scope: domains:write

Returns 204 No Content. The SSL certificate is revoked as part of the cleanup.


curl -X DELETE https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Every short link on a deleted domain stops resolving. Move those links to another hostname first — see updating a link.

Domains

Method	Path	Scope
`GET`	`/v1/domains`	`domains:read`
`POST`	`/v1/domains`	`domains:write`
`GET`	`/v1/domains/{id}`	`domains:read`
`PATCH`	`/v1/domains/{id}`	`domains:write`
`POST`	`/v1/domains/{id}/verify`	`domains:write`
`DELETE`	`/v1/domains/{id}`	`domains:write`

The domain object


{
  "id": "7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37",
  "hostname": "go.acme.com",
  "not_found_url": "https://acme.com/404",
  "verification_status": "pending",
  "verification": {
    "record_type": "CNAME",
    "record_name": "go.acme.com",
    "record_value": "app.linksqueeze.io",
    "instructions": "Add this CNAME record at your DNS provider, then call POST https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37/verify to check status."
  },
  "created_at": "2026-08-28T10:14:02.000000Z",
  "updated_at": "2026-08-28T10:14:02.000000Z"
}

Field	Type	Description
`id`	uuid	The domain’s identifier
`hostname`	string	The domain itself
`not_found_url`	string \| null	Where visitors are sent when a slug on this domain does not resolve
`verification_status`	string	One of `verified`, `pending`, `inactive`, or `unverified`
`verification`	object	The DNS record to add. Present only while the domain is not yet verified.
`created_at`	timestamp	When the domain was added
`updated_at`	timestamp	When the domain was last modified

Verification statuses

Status	Meaning
`pending`	The domain has been added and is waiting on DNS propagation or certificate issuance
`verified`	DNS resolves correctly and an SSL certificate has been issued — the domain is live
`inactive`	The domain has been deactivated and is not serving links
`unverified`	No verification state has been recorded yet

The verification object disappears from the response once the domain reaches verified, so its presence is a reliable signal that there is still DNS work to do.

Set up a custom domain

Add the domain

POST /v1/domains with the hostname. The response comes back pending, with the exact CNAME record to create in its verification object.

Create the DNS record

At your DNS provider, add the CNAME record named in verification.record_name pointing at verification.record_value (app.linksqueeze.io).

Verify

Call POST /v1/domains/{id}/verify to check propagation on demand. Link Squeeze also checks in the background, so this step is optional — it just gets you an answer sooner.

Wait for the certificate

Once DNS resolves, certificate issuance starts automatically. verification_status flips to verified when the certificate is live. DNS propagation can take up to 24–48 hours.

List domains


GET /v1/domains

Scope: domains:read

Returns your domains, newest first, in the standard paginated shape. Supports page and per_page (default 15, maximum 100).


curl https://app.linksqueeze.io/api/v1/domains \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Add a domain


POST /v1/domains

Scope: domains:write

Field	Type	Required	Description
`hostname`	string	Yes	The domain to add, maximum 255 characters. Must be a valid hostname and not already registered on Link Squeeze.
`not_found_url`	string \| null	No	Where to send visitors when a slug does not resolve. Must be a valid URL, maximum 2048 characters.

Returns 201 Created with the domain object in pending status.


curl -X POST https://app.linksqueeze.io/api/v1/domains \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "hostname": "go.acme.com",
    "not_found_url": "https://acme.com/404"
  }'

Adding a domain also queues the background DNS propagation check, so it will be verified in due course whether or not you call the verify endpoint.

Hostnames are unique across all of Link Squeeze, not just within your account. A domain already registered by anyone is rejected with 422.

Retrieve a domain


GET /v1/domains/{id}

Scope: domains:read

Poll this endpoint to watch verification_status move from pending to verified.


curl https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Update a domain


PATCH /v1/domains/{id}

Scope: domains:write

Field	Type	Description
`hostname`	string	Rename the domain. Must be a valid, unused hostname.
`not_found_url`	string \| null	Change or clear the not-found redirect.

Returns 200 OK with the updated domain object.


curl -X PATCH https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "not_found_url": "https://acme.com/gone" }'

Changing hostname does not move the DNS record or the SSL certificate. The new hostname needs its own CNAME record and its own certificate before links on it will resolve.

Verify a domain


POST /v1/domains/{id}/verify

Scope: domains:write

Runs the DNS check immediately rather than waiting for the background job. Takes no request body.

Always returns 202 Accepted — verification is asynchronous, and this endpoint reports what happened rather than the final outcome. The response is the domain object plus a top-level message:


{
  "data": {
    "id": "7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37",
    "hostname": "go.acme.com",
    "verification_status": "pending",
    "verification": { "record_type": "CNAME", "record_name": "go.acme.com", "record_value": "app.linksqueeze.io", "instructions": "..." },
    "created_at": "2026-08-28T10:14:02.000000Z",
    "updated_at": "2026-08-28T10:14:02.000000Z"
  },
  "message": "DNS is correctly configured. SSL certificate provisioning has started."
}

`message`	What it means
`DNS is correctly configured. SSL certificate provisioning has started.`	The CNAME resolved. Certificate issuance has begun.
`DNS record not found yet. Add the CNAME record shown below, then try again.`	The record is missing or has not propagated. The background check was requeued.
`This domain is already verified.`	Nothing to do.

Delete a domain


DELETE /v1/domains/{id}

Scope: domains:write

Returns 204 No Content. The SSL certificate is revoked as part of the cleanup.


curl -X DELETE https://app.linksqueeze.io/api/v1/domains/7a2c9d14-3e58-4b71-a0f6-2c1d8e5b9a37 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Every short link on a deleted domain stops resolving. Move those links to another hostname first — see updating a link.