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

Your first link, over the API

Four steps: get a key, create a link, attach a routing rule, read the clicks back. Every pane below runs against /v1 — pick cURL, Node.js (fetch) or Python (requests); there is no package to install.

1

Get an API key

Dashboard → Settings → API keys

Create a key yourself — shown once at creation. Live keys start with rii_live_, test keys with rii_test_ — test-key writes never touch production links.

SHELL
# shown once — 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 short random 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_8h2f0qZ3Tk1mR4vXw9aBcQ",
"slug": "summer",
"domain": "rii.link",
"short_url": "https://rii.link/summer",
"url": "https://example.com/summer",
"routing": [],
"expires_at": null,
"created_at": "2026-08-12T09:14:03Z",
"updated_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. Routing rules need Premium; on Free the call answers 403 plan_upgrade_required.

REQUEST
curl -X PATCH https://api.rii.link/v1/links/lnk_8h2f0qZ3Tk1mR4vXw9aBcQ \
-H "Authorization: Bearer $RII_KEY" \
-H "Content-Type: application/json" \
-d '{
"routing": [
{ "if": { "country": "DE" }, "to": "https://example.de/sommer" }
]
}'
RESPONSE · 200
{
"id": "lnk_8h2f0qZ3Tk1mR4vXw9aBcQ",
"slug": "summer",
"domain": "rii.link",
"short_url": "https://rii.link/summer",
"url": "https://example.com/summer",
"routing": [
{ "if": { "country": "DE" }, "to": "https://example.de/sommer" }
],
"expires_at": null,
"created_at": "2026-08-12T09:14:03Z",
"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 carries live clicks on API-created links today — webhook delivery is roadmap, dated on its own page.

REQUEST
curl "https://api.rii.link/v1/links/lnk_8h2f0qZ3Tk1mR4vXw9aBcQ/stats?group_by=country" \
-H "Authorization: Bearer $RII_KEY"
RESPONSE · 200
{
"total": 1,
"group_by": "country",
"buckets": [
{ "key": "DE", "clicks": 1 }
],
"interval": null,
"series": [],
"from": "2026-07-13T09:16:00Z",
"to": "2026-08-12T09:16:00Z"
}
WHERE NEXT
Full Links reference →Errors & rate limits →Webhooks — what exists →