rii.linkDOCSAPI v1
API · OPERATIONALrii.link ↗Dashboard
CODE · ~5 MIN

Your first link, over the API

Four requests: mint a key, create a link, attach a routing rule, read the clicks back. Every pane below runs against /v1 — pick cURL, Node.js, or Python; the shapes are the same ones the dashboard itself uses.

1

Mint an API key

Dashboard → Settings → API keys

Keys are minted in the dashboard and shown once. Live keys start with rii_live_, test keys with rii_test_ — test-key writes never touch production links.

SHELL
# shown once at mint time — keep it in an env var
export RII_KEY="rii_live_8f31k2…"
2

Create the link

POST /v1/links

One required field: url. Add slug to choose the path — omit it and a readable one is generated. The response is the full link object; id is what every later call takes.

REQUEST
curl -X POST https://api.rii.link/v1/links \
-H "Authorization: Bearer $RII_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/summer",
"slug": "summer"
}'
RESPONSE · 201
{
"id": "lnk_8h2f0q",
"slug": "summer",
"domain": "rii.link",
"short_url": "https://rii.link/summer",
"url": "https://example.com/summer",
"routing": [],
"created_at": "2026-08-12T09:14:03Z"
}
3

Attach a routing rule

PATCH /v1/links/{id}

routing is an ordered array of if/then rules — the whole array is replaced on write. First match wins; url stays the fallback.

REQUEST
curl -X PATCH https://api.rii.link/v1/links/lnk_8h2f0q \
-H "Authorization: Bearer $RII_KEY" \
-H "Content-Type: application/json" \
-d '{
"routing": [
{ "if": { "country": "DE" }, "to": "https://example.de/sommer" }
]
}'
RESPONSE · 200
{
"id": "lnk_8h2f0q",
"routing": [
{ "if": { "country": "DE" }, "to": "https://example.de/sommer" }
],
"updated_at": "2026-08-12T09:15:21Z"
}
4

Read the clicks back

GET /v1/links/{id}/stats

Aggregates with from/to bounds, grouped by country, device, referrer, or rule. Need push instead of pull? The SSE stream is live today — webhook delivery is roadmap, dated on its own page.

REQUEST
curl "https://api.rii.link/v1/links/lnk_8h2f0q/stats?group_by=country" \
-H "Authorization: Bearer $RII_KEY"
RESPONSE · 200
{
"total": 1,
"group_by": "country",
"buckets": [
{ "key": "DE", "clicks": 1 }
]
}
WHERE NEXT
Full Links reference →Errors & rate limits →Webhooks — what exists →