Developers

Links

Notes

Free-slot previews created by a third party who is not the site owner (such as a hosting provider or agency) must be given to the end customer (for example, in the migration ticket). Free-slot links offered for commercial use are intended as an acquisition channel for paying customers. Links used only internally must be created as paid-slot links on a paid plan, regardless of traffic.

Within a rolling 30-day window per destination (hostname and origin IP), free-slot lifetime follows recent preview clicks:

  • Up to 100 clicks: 1 week
  • Above 100 clicks: 1 day
  • Above 1,000 clicks: 1 hour
  • Above 10,000 clicks: 1 minute

When a free-slot preview expires, you can renew it for free. Paid-slot links can be deleted to free a slot.

Integrations should read lifetime and click-window fields from GET /system.

Migration preview (old_ip)

Optional old_ip is the previous host’s public IPv4 or IPv6. When set, SkipDNS serves a migration preview at https://{alias}.{migration-preview-domain} (for example oldhost.link) that pins origin traffic to that IP. Create and update return 422 when a non-empty old_ip is sent and the platform has no active migration-preview domain, or when the alias is already used by another link (migration preview requires a unique alias across all brand domains).

Link JSON always keeps brand URLs on preview_url and landing_url. When migration preview applies, responses also include:

  • old_ip — stored previous-server IP, or null
  • oldhost_preview_url — https://{alias}.{migration-preview-domain}, or null
  • oldhost_landing_url — https://{migration-preview-domain}/{alias}, or null

List

API endpoint:

GET https://skipdns.link/api/v2/links

Request example:

curl --location --request GET 'https://skipdns.link/api/v2/links' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {api_token}'

Show

API endpoint:

GET https://skipdns.link/api/v2/links/{id}

Request example:

curl --location --request GET 'https://skipdns.link/api/v2/links/{id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {api_token}'

Store

API endpoint:

POST https://skipdns.link/api/v2/links

Request example:

curl --location --request POST 'https://skipdns.link/api/v2/links' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_token}' \
--data-raw '{"url":"https://www.example.com","ip_address":"203.0.113.10","old_ip":"203.0.113.20"}'

Parameters:

Parameter Type Description
url
required string
Website URL to preview.
ip_address
optional string
Destination server IP. Links inherit the space default when linked to a space and no IP is set on the link.
old_ip
optional string|null
Optional previous-host public IPv4 or IPv6 (nullable; max 45). Enables migration preview at {alias}.{migration-preview-domain}. Must be a public address and must differ from the link target IP. Returns 422 when no migration-preview domain is configured, or when the alias is already used on another domain.
alias
optional string
Link alias (min 5 characters).
http_port
optional integer
Non-standard HTTP port override (1–65535). Omit or send 80 to inherit from the space.
https_port
optional integer
Non-standard HTTPS port override (1–65535). Omit or send 443 to inherit from the space.
space_id
optional integer
Optional space ID. When omitted, the link is not attached to a space. When set, the link can inherit IP and ports from that space. List spaces with GET /spaces.
domain_id
optional integer
Optional brand domain ID. When omitted, the platform default domain is used (not profile defaults from the dashboard).
is_wildcard_multisite
optional boolean
Apply this link's routing settings to all subdomains, not only apex and www. Useful for multisite or multitenant setups and when the domain and its subdomains integrate or cross-link.
is_flexible_ssl
optional boolean
Terminate HTTPS at SkipDNS and forward HTTP to the origin.
slot_type
optional string
Default free. Allowed values: free, paid. Free-slot expiration follows click-based lifetime rules for the destination (see Notes).
destination_clicks
optional integer
Read-only in responses: preview clicks on this link’s destination in the rolling window from GET /system. Creating or renewing a free-slot link uses this count to choose the lifetime tier.
password
optional string
Optional link password (free-slot and paid-slot).
oldhost_preview_url
optional string|null
Read-only in responses: https://{alias}.{migration-preview-domain} when old_ip is set and a migration-preview domain is active; otherwise null. preview_url stays the brand preview URL.
oldhost_landing_url
optional string|null
Read-only in responses: https://{migration-preview-domain}/{alias} when old_ip is set and a migration-preview domain is active; otherwise null. landing_url stays the brand landing URL.
Paid-slot links only
expiration
optional datetime
Custom expiration datetime (ISO 8601).

Update

API endpoint:

PUT / PATCH https://skipdns.link/api/v2/links/{id}

Request example:

curl --location --request PATCH 'https://skipdns.link/api/v2/links/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_token}' \
--data-raw '{"url":"https://www.example.com","old_ip":"203.0.113.20"}'

Parameters:

Parameter Type Description
url
optional string
Updated website URL.
ip_address
optional string
Destination server IP. Links inherit the space default when linked to a space and no IP is set on the link.
old_ip
optional string|null
Optional previous-host public IPv4 or IPv6 (nullable; max 45). Same migration-preview rules as create. Omit to leave unchanged; send null or empty to clear. Returns 422 when no migration-preview domain is configured, or when the alias conflicts with another link.
alias
optional string
Updated link alias (min 5 characters).
http_port
optional integer
Non-standard HTTP port override (1–65535). Omit or send 80 to inherit from the space.
https_port
optional integer
Non-standard HTTPS port override (1–65535). Omit or send 443 to inherit from the space.
space_id
optional integer
Space ID. Send null to detach the link from its space.
domain_id
optional integer
Brand domain ID.
is_wildcard_multisite
optional boolean
Enable or disable applying this link's routing settings to all subdomains (see create).
is_flexible_ssl
optional boolean
Enable or disable Flexible SSL.
slot_type
optional string
Convert between free and paid when your plan allows. Allowed values: free, paid. Setting free recalculates free-slot expiration.
password
optional string
Optional link password (free-slot and paid-slot).
oldhost_preview_url
optional string|null
Read-only in responses: migration preview URL when old_ip is set; otherwise null. preview_url is unchanged.
oldhost_landing_url
optional string|null
Read-only in responses: migration landing URL when old_ip is set; otherwise null. landing_url is unchanged.
Paid-slot links only
expiration
optional datetime
Custom expiration datetime (ISO 8601).

Push to paid slot

API endpoint:

POST https://skipdns.link/api/v2/links/{id}/push-to-paid-slot

Request example:

curl --location --request POST 'https://skipdns.link/api/v2/links/{id}/push-to-paid-slot' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {owner_api_token}' \
--header 'Content-Type: application/json' \
--data '{"recipient_api_token":"{recipient_api_token}"}'

Parameters:

Parameter Type Description
id
optional integer|string
Link ID or alias owned by the authenticated account (Bearer owner_api_token).
recipient_api_token
optional string
JSON body field. API token of the SkipDNS account that receives the preview. Requires an available paid slot on the recipient plan. Free-slot previews are converted to paid-slot and their expiration is cleared (response expiration is null). Paid-slot previews transferred to another account keep their expiration.

Delete

API endpoint:

DELETE https://skipdns.link/api/v2/links/{id}

Request example:

curl --location --request DELETE 'https://skipdns.link/api/v2/links/{id}' \
--header 'Authorization: Bearer {api_token}'