rii.linkDOCSAPI v1
API STATUS ↗rii.link ↗Dashboard

Domains

BASE  https://api.rii.link/v1AUTH: BEARER → AUTHENTICATION

A domain is a host you connect through this API and route API links through. Connect it, set two DNS records, and verification flips on its own. Links can go onto it before that — they wait, staged, and go live with the domain.

POST/v1/domains

Connect a domain

Returns the two DNS records to set — copy the values exactly as returned. Status starts at pending_dns and flips automatically — see below. You can create links on it right away; they are staged until it is active.

PARAMETERS
hoststringREQUIRED

The fully-qualified host, e.g. go.example.com.

REQUEST
curl -X POST https://api.rii.link/v1/domains \
-H "Authorization: Bearer $RII_KEY" \
-H "Content-Type: application/json" \
-d '{ "host": "go.example.com" }'
RESPONSE · 201
{
"id": "dom_4kq2mR7vTx0bWn3sLc5hYA",
"host": "go.example.com",
"status": "pending_dns",
"records": [
{ "type": "CNAME", "name": "go.example.com", "value": "‹routing target›" },
{ "type": "TXT", "name": "_rii.go.example.com", "value": "rii-verify=7f3a…" }
],
"links": 0,
"staged_links": 0,
"created_at": "2026-08-12T09:14:03Z",
"updated_at": "2026-08-12T09:14:03Z"
}
GET/v1/domains

List domains

Every domain connected through this API, with status and link count. links tells you what a disconnect would break; staged_links counts the links still waiting for the domain to go active (0 once it is).

REQUEST
curl https://api.rii.link/v1/domains \
-H "Authorization: Bearer $RII_KEY"
RESPONSE · 200
{
"data": [
{
"id": "dom_4kq2mR7vTx0bWn3sLc5hYA",
"host": "go.example.com",
"status": "active",
"records": [ … ],
"links": 214,
"staged_links": 0,
"created_at": "2026-08-12T09:14:03Z",
"updated_at": "2026-08-12T09:20:11Z"
}
]
}
GET/v1/domains/{id}

Retrieve a domain

One domain, the same shape as a list entry. Poll it during a migration: staged_links is how many imported links are waiting on DNS.

REQUEST
curl https://api.rii.link/v1/domains/dom_4kq2mR7vTx0bWn3sLc5hYA \
-H "Authorization: Bearer $RII_KEY"
RESPONSE · 200 (MID-MIGRATION)
{
"id": "dom_4kq2mR7vTx0bWn3sLc5hYA",
"host": "go.example.com",
"status": "pending_dns",
"records": [ … ],
"links": 50000,
"staged_links": 50000,
"created_at": "2026-08-12T09:14:03Z",
"updated_at": "2026-08-12T09:14:03Z"
}

How verification flips

We re-check DNS every minute; status turns active once both records resolve and the certificate is issued. It is polling, not a callback — nothing to expose on your side; outbound webhooks are roadmap, dated on their own page. Staged links need nothing either: they were already loaded into routing, so they answer as soon as the domain does.

NO ACTION NEEDED AFTER THE RECORDS ARE SET — THE FLIP IS AUTOMATIC

DELETE/v1/domains/{id}

Disconnect a domain

Refused with 409 domain_in_use while links still resolve on the host. Move or delete them first, or force it and accept the breakage consciously.

PARAMETERS
forceboolean

Query param. Deletes the links on the host (slugs quarantined 30 days), then disconnects.

REQUEST
curl -X DELETE https://api.rii.link/v1/domains/dom_4kq2mR7vTx0bWn3sLc5hYA \
-H "Authorization: Bearer $RII_KEY"
RESPONSE · 409 (LINKS STILL LIVE)
{
"error": {
"code": "domain_in_use",
"message": "214 links still resolve on go.example.com.",
"doc_url": "https://rii.link/docs/api/errors#domain_in_use"
}
}