Documentation

List own domains

GET/v1/domainsDomains

The account's own domains with their status and the plan's allowance. Pro holds 5; other plans answer 403 forbidden with details.upgrade. Also available as the MCP tool list_domains.

Example request

curl -s "https://snip.link/v1/domains" \
  -H "Authorization: Bearer $SNIP_KEY"

Example response

{
  "domains": [
    {
      "id": "dom_3c1f0a9e2b7d4c55",
      "hostname": "go.example.com",
      "status": "active",
      "detail": null,
      "cname_target": "customers.snip.link",
      "root_url": "https://example.com",
      "links": 42,
      "created_at": "2026-10-20T12:00:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
`domains`	Domain[]
`domains[].id`	string	Stable id. Every domain route accepts it, or the hostname.
`domains[].hostname`	string	The domain links live on, without a scheme.
`domains[].status`	pending \| active \| failed	`pending` until the CNAME points at us and the certificate is issued, `active` once links on it answer, `failed` when verification gave up.
`domains[].detail`	string, null	What a pending domain is waiting for, or why it failed. Null once active.
`domains[].cname_target`	string	The DNS record to add at your DNS provider: a CNAME from the hostname to this target (customers.snip.link).
`domains[].root_url`	string, null	Where the bare domain (https://go.example.com/) sends visitors. Null answers 404.
`domains[].links`	integer	Links on this domain.
`domains[].created_at`	string
`limit`	integer	Own domains the plan holds. 0: an upgrade unlocks them.
`enabled`	boolean	False while own domains are switched off for the service.
`cname_target`	string
`upgrade`	object, null	The plan that unlocks own domains, when this one has none.

Errors

Status	Meaning
401	The API key is missing, malformed or revoked.
429	Either the key exceeded its requests-per-second limit (honor Retry-After), or a daily or plan quota is used up (`details.reason`).

Back to the guide