URX

npx add-mcp 'https://urx.si/api/mcp'

URX documentation

Everything you need to create a Smart Link, route visitors, measure the results and connect URX to your own systems.

Getting started

1. Create your account and name your workspace (usually your company).
2. Add your app as a project: its website, App Store link and Google Play link. Only the name is required.
3. Claim your link, e.g. urx.si/acme. Custom slugs are free on every plan.
4. Pick a device in the preview to see where it goes, then create it. Share it, print its QR code, and open Analytics to see what happened.

Want to see routing first? Open urx.si/demo on your phone and on your laptop.

Concepts

Smart Link

A URL on a URX domain that resolves to a different destination depending on who opens it.

Slug

The part after the domain, like acme in urx.si/acme. Unique per domain.

Destination

Where a visitor lands: a store listing, an in-app screen or a web page.

Routing Rule

An IF/THEN condition on device, country, source and more that overrides the default destination.

Fallback

The destination used when no rule or platform default applies.

Project

One product - an app, a site or both. Links take their store and website URLs from their project.

Workspace

Your team and billing boundary. It can hold many projects.

Click

One visit to a link. A Scan is a click that came from a URX QR code.

Conversion

An outcome after a click, like an install or purchase, reported back to URX.

Projects

A project holds one app's store listings and identifiers. Links that use “From project” destinations follow the project: change the App Store link once and every link of the project updates. For deep linking, add the Apple Team ID and bundle ID (iOS) and the package name and SHA-256 signing fingerprint (Android). Free includes 2 projects, Pro 5, Growth 20.

Destinations

Every link has a destination for each platform, and a fallback:

• iPhone and iPad, Android, Desktop - from the project or a custom URL.
• Everyone else - unknown devices. Turn on “Let unknown devices choose” to show App Store, Google Play and website buttons instead.
• More destinations - extra targets for routing rules (a regional listing, a campaign page).

Change destinations any time: the link stays the same and visitors get the new routing within about 30 seconds. URX uses temporary (302) redirects so browsers never remember an old destination. Query parameters: UTM parameters are passed on by default (into Google Play's install referrer for Android); choose all, none or a list. With “Pass sub-paths through”, urx.si/acme/shoes/123 opens acme.com/shoes/123.

Routing rules

Every visit is resolved in the same order:

1. Routing rules, top to bottom. A rule matches when all (or any, your choice) of its conditions do. The first match wins.
2. Platform destinations - iPhone and iPad, Android, desktop.
3. Fallback - everyone else.

Device

Phone, tablet, desktop, bot or unknown

Operating system

iOS, iPadOS, Android, Windows, macOS, Linux, ChromeOS

Browser / in-app browser

Chrome, Safari, … and Instagram, Facebook, TikTok, LinkedIn, X …

Country and region

From the visitor's network location, e.g. IN or CA

Language

The browser's preferred language, e.g. ur, ar, en

Source and referrer

utm_source if present, else the referring site or app

UTM source / medium / campaign

From the link's query string

Query parameter

Any parameter: is, contains, starts with, present, missing

Date and time

Before or after a moment (UTC) - for launches and sales

Use Test routing next to the rules to simulate a visitor - device, country, app, referrer, query string, time - and see which rule matches before you save. Rules are part of Pro and up. Links can also start and expire at set times.

Slug rules

• 3–48 characters per part: lowercase letters, numbers and single hyphens. Up to three parts, like acme/ramadan - sub-links belong to whoever owns acme.
• Can't start or end with a hyphen. Case-insensitive: Acme and acme are the same slug.
• Some slugs are reserved because URX uses those paths itself, such as pricing, docs and login.
• A deleted link's address stays reserved for your workspace for 90 days, so nobody else can take over printed codes.
• Trademark concerns about a slug? See the Acceptable Use Policy.

QR codes

Every link has a QR code that encodes the link itself, not its destination - so you can change the destination after printing. Download PNG or SVG, choose colours and error correction (L, M, Q, H), and add the URX mark in the centre. Codes downloaded from URX carry a scan marker, so each link shows its QR scans alongside its clicks. Keep the white border around the code when printing.

Import, bulk edit and passwords

Import from Links → Import: a CSV file with a header line (slug, url or long_url, and optionally ios, android, name, tags, campaign), your recent Bitly links with a Bitly access token that is used once and not stored, or Firebase Dynamic Links long links, which become iPhone, Android and web destinations (migration guide). You review every row first; up to 100 links per import.

Bulk edit: tick links in the list to pause, resume, archive, tag or move them to a project together. Duplicate a link from its menu to start a new one with the same destinations, rules, tags and password.

Passwords (Pro): in a link's Settings, set a password and visitors enter it before they're sent on. People who enter it are remembered for 12 hours on that device; changing the password asks everyone again. Link previews in chat apps show the password page, not the destination. Ten wrong tries from one network lock it out for 15 minutes. UTM templates (Pro): save a set of UTM parameters in a link's Campaign section and apply it to other links in one click.

Analytics

Clicks, approximate unique visitors, app opens and conversions, with the change from the previous period; breakdowns by platform, device, browser, country, region, source, referrer, destination, rule, UTM parameters and domain; recent clicks, updated every few minutes; CSV export. Filter by link, project, campaign and date range. UTM parameters are read from the link people open, like urx.si/acme?utm_source=instagram. Days are in UTC. Link-preview bots and crawlers are excluded unless you include them.

URX doesn't store IP addresses or fingerprint visitors. Unique visitors are counted with a daily, salted hash, so the number is an estimate. Detailed analytics are kept for 30 days on Free, 1 year on Pro, 2 years on Growth and as agreed on Business.

Custom domains

On Growth and Business, serve links from a subdomain such as links.acme.com:

1. Dashboard → Domains → add the domain.
2. Create the CNAME record URX shows (and the TXT record, if shown) at your DNS provider. If your DNS is on Cloudflare, turn the proxy off for that record.
3. URX verifies ownership and issues HTTPS, usually within minutes. The domain only starts serving links once both are done.
4. Create links on it by choosing the domain next to the slug.

Deep links

Smart routing (every plan) needs nothing in your app. Universal Links (iOS, on urx.si and your own domain) and App Links (Android, on your own domain) open the installed app directly - from Pro, with the domain on Growth.

1. Add the identifiers to the project (Team ID and bundle ID; package name and SHA-256 fingerprint).
2. iOS: add applinks:urx.si (or your domain) to your app's Associated Domains. Android: add an autoVerify intent filter for your domain.
3. URX publishes the association files for you. Run the check on the link's Deep linking tab - it shows what Apple and Google see.

urx.si/acme/shoes/123  →  opens your app at /shoes/123   (installed, Universal Link)
                       →  App Store / Google Play          (not installed)
                       →  https://acme.com/shoes/123       (desktop, sub-paths on)

Deferred deep linking (Pro) opens a screen after a fresh install. Turn it on in the link's Deep linking tab and say which screen; on its first launch your app sends POST /api/deferred with { "referrer": "<Play install referrer>" } on Android, or an empty body on iOS, and gets back { "matched": true, "path": "/shoes/123", "data": { … } }. The tab has copy-paste Kotlin and Swift.

Conversion events

Report installs, sign-ups and purchases to POST /api/v1/events. Turn on “Conversion tracking” on a link and URX adds a signed urx_click parameter to its website destinations; send it back as clickId and the conversion is attributed to that click. Without proof of the click, events are stored unattributed.

Two kinds build Contacts (Growth). Send "kind": "lead" with "contact": { "externalId": "<your user id>" } when someone signs up, and "kind": "sale" with a value when they pay. A sale for a known contact is credited to the link that brought them, even without its own clickId. Dashboard → Contacts has a setup guide for Next.js, Better Auth, Supabase and Stripe.

Report a sign-up, then a purchase

curl https://urx.si/api/v1/events \
  -H "Authorization: Bearer $URX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "signup", "kind": "lead", "clickId": "<urx_click>", "contact": { "externalId": "user_123", "email": "amina@example.com" } }'

curl https://urx.si/api/v1/events \
  -H "Authorization: Bearer $URX_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "purchase", "kind": "sale", "value": 9.99, "currency": "USD", "contact": { "externalId": "user_123" }, "idempotencyKey": "order_123" }'

API and keys

The REST API is part of Growth and Business. Create a key in Dashboard → Developers → API keys, pick its permissions, and send it in the Authorization header. Keys are shown once; revoke and replace a lost key. Growth allows 120 requests a minute per workspace, shared by its keys. Full reference: OpenAPI spec.

• POST/api/v1/links - Create a Smart Link
• GET/api/v1/links/:id - Retrieve a link and its routing
• PATCH/api/v1/links/:id - Change destinations or rules
• GET/api/v1/analytics - Query clicks and breakdowns
• POST/api/v1/events - Report a conversion

curl https://urx.si/api/v1/links \
  -H "Authorization: Bearer $URX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "launch",
    "ios": "https://apps.apple.com/app/acme/id6450000000",
    "android": "https://play.google.com/store/apps/details?id=com.acme.app",
    "web": "https://acme.com/launch"
  }'

Webhooks

Add an HTTPS endpoint in Dashboard → Developers → Webhooks to receive signed JSON for:

• link.created - A link was created
• link.updated - Destinations, rules or status changed
• domain.verified - A custom domain is live
• conversion.created - A conversion was recorded
• usage.warning - The workspace is nearing its click allowance

Each request carries urx-signature: t=…,v1=…, an HMAC-SHA256 of `${t}.${body}` with the endpoint's secret. Reject requests older than 5 minutes, and use urx-event-id to ignore duplicates. Failed deliveries are retried for about an hour; you can resend any delivery from its history.

AI assistants (MCP)

Claude, ChatGPT, Cursor and other assistants that speak the Model Context Protocol can work with your links: create them, look them up, pause them, read their analytics and get their QR codes. Connect the assistant to https://urx.si/api/mcp with a workspace API key; the key's permissions decide which tools it gets (links:read, links:write, analytics:read). On Pro, assistants get the read-only tools (list and look up links, check a slug, analytics, projects, QR codes); Growth and Business add creating and changing links. In the dashboard, Developers → Copy prompt for your agent copies a ready-made setup prompt, optionally with a new read-only key that expires in 30 days.

claude mcp add --transport http urx https://urx.si/api/mcp \
  --header "Authorization: Bearer urx_live_…"

{
  "mcpServers": {
    "urx": {
      "type": "http",
      "url": "https://urx.si/api/mcp",
      "headers": { "Authorization": "Bearer urx_live_…" }
    }
  }
}

Teams

Invite people from Settings. Owners manage everything including billing; admins manage the team, domains, API keys and webhooks; members create and edit links and projects; viewers can only look. Invitations expire after 7 days and only work for the invited email address. Growth includes 5 seats.

Plans and billing

See pricing. Upgrade or change plan from Dashboard → Billing. Links never stop working when you go over your click allowance, and every click is still recorded: we email owners and admins at 80 %, 100 % and 120 % so you can pick a plan that fits. On Free, visits past the allowance see a URX page for up to 10 seconds (Continue works after 5), which may carry a sponsor, until the month resets; paid plans always redirect straight away and never show an ad. Free links with no activity for 6 months are switched off after two email reminders (one click keeps them), and can be reactivated for 90 days. Cancel from the same page; paid features last until the end of the period you've paid for. If you downgrade, links keep working; features your new plan doesn't include (like routing rules or removing URX branding) stop applying.

Troubleshooting

• An edit isn't showing yet. Changes reach every location within about 30 seconds. Your browser doesn't cache URX redirects.
• The wrong store opens. Use Test routing on the link. iPads in desktop mode say they're Macs; URX asks the browser before choosing when that matters.
• “This link is paused / expired / isn't available”. Check the link's status and schedule on its Settings tab.
• A domain won't verify. The CNAME must point at the target shown, with no proxy in front; DNS can take up to an hour to spread.
• Found a harmful URX link? Report it.

Stuck? Email support@urx.si or use the contact form.