URLd.me API Documentation

Version 1.0.0 — Official API for URLd.me, an all-in-one link management platform. Integrate and automate short links, targeting rules, QR codes, and link analytics through our REST API.

Authentication & Base Setup

API access is available as a team feature. Authenticate requests by attaching your API key in the request header:

X-Api-Key: ukp_your_api_key_here

Base Environments:

· https://urld.me/api/v1 — Production Environment (for interactive web tryout, requires login)
· https://api.urld.me/v1 — Production Environment (for real integration, requires api key)

API Specification:

An OpenAPI compatible API-spec is available at {BASE}/openapi.yaml.

API Path Alias Note:

Endpoints with path pattern /u/{domain}/{code} also support direct lookups by URL ID using the alias /i/{url_id}. Both endpoints behave exactly the same.

JSON Request Payload:

Our illustration and examples may have comments (`// ...`) in them but that is only for explanation and actual request must send a valid JSON without comments.

API Endpoints

GET/ping

System health check to verify service status and underlying infrastructure readiness.

Response 200 OK

{
  "status": 200,
  "pong": true
}

Response 500 Server Error

{
  "code": "internal_error",
  "error": "Internal server error, some services unavailable at the moment: cache",
  "status": 500
}

GET/urls

List and query all short links with extensive filtering and pagination options.

Query Parameters

Parameter	Type	Description
`domain`	string	Filter by domain serving short URLs.
`short_code`	string	Filter by specific short code identifier.
`tag`	string	Filter URLs by assigned tag keyword.
`source`	string (enum)	Source channel: `api`, `admin`, `front`, `import`, `ext`.
`from` / `to` (YYYY-MM-DD)	string	Filter creation date range boundaries.
`has_qr` / `has_rules` / `is_custom` / `is_expiring`	integer (enum)	Binary filter options: `0` (false) or `1` (true).
`page` / `size`	integer	Pagination controls. Defaults: `page=1`, `size=25`.

Response 200 OK

{
  "data": [
    {
      "created_at": "2026-08-11T04:54:05.344Z",
      "short_code": "nexus1",
      "domain": "ugo.li",
      "url": "https://www.nexusdigitech.com/another/long/url",
      "source": "api",
      "short_url": "https://ugo.li/nexus1",
      "tags": [
        "nexus"
      ],
      "id": "6a7aaaedc3d9b4bd69d65b17",
      "is_custom": true
    },
    {
      "created_at": "2026-08-11T04:54:05.34Z",
      "short_code": "nexus1",
      "domain": "root",
      "url": "https://www.nexusdigitech.com/very/long/url",
      "title": "NexusDigitech LLC",
      "desc": "NexusDigitech LLC is parent company of URLd.me",
      "source": "api",
      "utm_source": "urld",
      "utm_medium": "shortlink",
      "short_url": "https://urld.me/nexus1",
      "tags": [
        "nexus",
        "digitech",
        "digital"
      ],
      "id": "6a7aaaedc3d9b4bd69d65b16",
      "is_custom": true
    },
    {
      "created_at": "2026-08-10T09:52:54.078Z",
      "short_code": "nexus",
      "domain": "ugo.li",
      "url": "https://www.nexusdigitech.com/another/long/url",
      "source": "api",
      "short_url": "https://ugo.li/nexus",
      "tags": [
        "nexus"
      ],
      "id": "6a799f76c3d9b4bd69d65b12",
      "is_custom": true
    },
    {
      "created_at": "2026-08-10T09:46:45.201Z",
      "short_code": "nexus2",
      "domain": "root",
      "url": "https://www.nexusdigitech.com/another/long/url",
      "source": "api",
      "short_url": "https://urld.me/nexus2",
      "tags": [
        "nexus"
      ],
      "id": "6a799e05c3d9b4bd69d65b0f",
      "is_custom": true
    }
  ],
  "meta": {
    "prev": "",
    "next": "/api/v1/urls?domain=&from=&has_qr=&has_rules=&is_custom=&is_expiring=&short_code=&source=&tag=&to=&username=&page=2&size=5",
    "page": 1,
    "size": 5,
    "count": 5
  },
  "status": 200
}

POST/urls

Create short URLs individually or in bulk. Supports UTM campaign tags, custom short codes, dynamic targeting rules, and QR code generation flags.

Request Body Structure

{
  "data": [
    { // only the url field is required
      "url": "https://www.nexusdigitech.com/very/long/url", // required
      "title": "NexusDigitech LLC",
      "desc": "NexusDigitech LLC is parent company of URLd.me",
      "image": "", // URL of banner image
      "domain": "",
      "short_code": "nexus1",
      "passphrase": "",
      "expires_on": "",
      "event_id": "", // event id (takes precedence over utm_ fields)
      "utm_medium": "shortlink",
      "utm_source": "urld",
      "utm_campaign": "",
      "utm_content": "",
      "rules": [ // any one rule match is enough
        { // the first match in this list wins
          "key": "iso", // iso for country iso2 (uppercase)
          "val": "US", // matches request country to USA
          "url": "?us=1" // relative to main url (full url works too)
        },
        {
          "key": "lang", // lang for language iso (lowercase)
          "val": "de",
          "url": "?lang=de"
        },
        {
          "key": "dev", // dev for device
          "val": "bot", // one of Desktop, Tablet, Mobile, Bot
          "url": "/404" // show 404 for bot
        },
        {
          "key": "os", // os for operating system
          "val": "Linux", // one of Linux, Windows, Mac, Android, iOS
          "url": "?os=linux"
        }
      ],
      "tags": [
        "nexus",
        "digitech",
        "digital"
      ],
      "has_qr": true,
      "fallback": false // if true, uses default if domain, short_code and has_qr field cause errors due to conflicts or limits
    },
    {
      "url": "https://www.nexusdigitech.com/another/long/url",
      "domain": "ugo.li",
      "short_code": "nexus1",
      "tags": [
        "nexus"
      ]
    }
  ]
}

Response 201 Created (Full Success)

{
  "data": [
    {
      "url": "https://www.nexusdigitech.com/very/long/url",
      "has_qr": false,
      "url_id": "6a7aaaedc3d9b4bd69d65b16",
      "status": 201,
      "short_code": "nexus1",
      "short_url": "https://urld.me/nexus1"
    },
    {
      "short_url": "https://ugo.li/nexus1",
      "url": "https://www.nexusdigitech.com/another/long/url",
      "has_qr": false,
      "url_id": "6a7aaaedc3d9b4bd69d65b17",
      "status": 201,
      "short_code": "nexus1"
    }
  ],
  "meta": {
    "subs": "ULTRA",
    "quota": {
      "custom": 1593,
      "qr": 8000,
      "shorten": 7977
    },
    "newer": 2,
    "empty": 0
  },
  "status": 201
}

Response 207 Multi-Status (Partial Success)

{
  "data": [
    {
      "url": "https://www.nexusdigitech.com/very/long/url",
      "status": 409,
      "short_code": "nexus",
      "short_url": "https://urld.me/nexus",
      "url_id": "678f8cf3bd37ae25c5fe3f36",
      "error": "URL is already shortened"
    },
    {
      "status": 201,
      "short_code": "nexus",
      "short_url": "https://ugo.li/nexus",
      "url": "https://www.nexusdigitech.com/another/long/url",
      "has_qr": false,
      "url_id": "6a799f76c3d9b4bd69d65b12"
    }
  ],
  "meta": {
    "subs": "ULTRA",
    "quota": {
      "shorten": 7981,
      "custom": 1596,
      "qr": 8000
    },
    "newer": 1,
    "empty": 0
  },
  "status": 207
}

GET/urls/u/{domain}/{code}ᴏʀ/urls/i/{url_id}

Get single URL details by domain and short code, or by URL ID. The response payload is similar to GET /urls with some additional details like rules and metrics.

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Response 200 OK

{
  "data": {
    "created_at": "2026-08-11T04:54:05.34Z",
    "short_code": "nexus1",
    "domain": "root",
    "url": "https://www.nexusdigitech.com/very/long/url",
    "title": "NexusDigitech LLC",
    "desc": "NexusDigitech LLC is parent company of URLd.me",
    "source": "api",
    "short_url": "https://urld.me/nexus1",
    "tags": [
      "nexus",
      "digitech",
      "brand"
    ],
    "rules": [
      {
        "key": "iso",
        "val": "US",
        "url": "?us=1"
      },
      {
        "key": "lang",
        "val": "de",
        "url": "?lang=de"
      },
      {
        "key": "dev",
        "val": "bot",
        "url": "/404"
      },
      {
        "key": "os",
        "val": "Linux",
        "url": "?os=linux"
      }
    ],
    "id": "6a7aaaedc3d9b4bd69d65b16",
    "is_custom": true,
    "has_qr": true
  },
  "status": 200
}

Response 404 Not Found

{
  "code": "data_error",
  "message": "Requested URL not found",
  "status": 404
}

PUT/urls/u/{domain}/{code}ᴏʀ/urls/i/{url_id}

Replace single URL detail by domain and short code, or by URL ID.

Use this endpoint carefully as omitted fields (expires_on domain passphrase tags utm_*) are cleared. The field event_id can be cleared with a value of 0.

For partial update of some properties, use PATCH method instead.

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Request Body Structure

The request payload is same as POST /urls except that instead of array inside topmost `data` node, send a single URL object.

{
  "data": {
    "tags": ["nexus", "digitech", "brand"],
    "has_qr": true // ... other fields below
  }
}

Response 200 OK

{
  "message": "URL updated successfully",
  "status": 200
}

Response 404 Not Found

{
  "code": "data_error",
  "message": "Requested URL not found",
  "status": 404
}

Response 422 Unprocessable

{
  "code": "user_error",
  "error": "Invalid or unavailable custom short code",
  "status": 422
}

PATCH/urls/u/{domain}/{code}ᴏʀ/urls/i/{url_id}

Partially update a short URL by domain and short code, or by URL ID. The fields missing in payload are not affected.

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Request Body Structure

The request payload is same as POST /urls except that instead of array inside topmost `data` node, send a single URL object.

{
  "data": {
    "tags": ["ugoli", "nexus", "digitech"],
    "has_qr": true // ... other fields below
  }
}

Response 200 OK

{
  "message": "URL patched successfully",
  "status": 200
}

Response 404 Not Found

{
  "code": "data_error",
  "message": "Requested URL not found",
  "status": 404
}

DELETE/urls/u/{domain}/{code}ᴏʀ/urls/i/{url_id}

Delete a single short URL by domain and short code, or by URL ID.

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Response 200 OK

{
  "message": "URL deleted successfully",
  "status": 200
}

Response 404 Not Found

{
  "code": "data_error",
  "message": "Requested URL not found",
  "status": 404
}

GET/hits/u/{domain}/{code}ᴏʀ/hits/i/{url_id}

Retrieve click and QR scan statistics grouped by time aggregation windows.

Query Parameters

Parameter	Type	Default	Enum Values
`interval`	string	Based on plan	`hour`, `day`, `week`, `month`

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Response 200 OK (Day)

{
  "status": 200,
  "data": {
    "latest": [
      {
        "date": "2026-08-05T00:00:00Z",
        "total": 45,
        "clicks": 32,
        "scans": 13
      }
    ],
    "lifetime": {
      "date": "2026-08-05T07:20:35.949Z",
      "total": 45,
      "clicks": 32,
      "scans": 13
    }
  },
  "meta": {
    "plan": "ULTRA",
    "interval": "day"
  }
}

Response 200 OK (Hour)

{
  "data": {
    "latest": [
      {
        "date": "2026-08-05T08:00:00Z",
        "total": 10,
        "clicks": 6,
        "scans": 4
      },
      {
        "date": "2026-08-05T07:00:00Z",
        "total": 45,
        "clicks": 32,
        "scans": 13
      }
    ],
    "lifetime": {
      "date": "2026-08-05T07:20:35.949Z",
      "total": 55,
      "clicks": 38,
      "scans": 17
    }
  },
  "meta": {
    "interval": "hour",
    "plan": "ULTRA"
  },
  "status": 200
}

PATCH/qrs/u/{domain}/{code}ᴏʀ/qrs/i/{url_id}

Enable or update custom visual styling parameters for generated QR codes. Once enabled, a QR can never be disabled again.

Path Parameters

Parameter	Status	Description
`domain`	required in `/urls/u/` path	Domain name (eg: `root`, `ugo.li`)
`code`	required in `/urls/u/` path	Short code identifier or alias.
`url_id`	required in `/urls/i/` path	The URL ID.

Response 200 OK

{
  "status": 200,
  "message": "QR enabled successfully",
  "uri": "/qr/test-code.png?_sh=C&_tr=0&_fg=ff55ff&_bg=ffffff&_ht=0&_gr=emerald"
}

GET/qrs/svg/u/{domain}/{code}ᴏʀ/qrs/svg/i/{url_id}

Get SVG image of the QR code. Currently styling is not supported in this API.

Response 200 OK

Response 404 Not Found

{
  "status": 404,
  "code": "data_error",
  "error": "URL not found or doesn't support QR"
}

GET/events

Get all currently active events. Expired events can be found in backend.

Response 200 OK

{
  "data": [
    {
      "created_at": "2026-08-12T06:42:18.458Z",
      "expires_on": "2026-12-31T23:59:59Z",
      "name": "Camp One",
      "campaign": "camp1",
      "source": "social",
      "medium": "urld",
      "event_id": "6a7c15cacca95cf3b98fe86d",
      "urls_count": 0,
      "paused": false
    },
    {
      "created_at": "2026-08-12T07:15:27.213Z",
      "expires_on": "2026-09-30T23:59:59Z",
      "name": "Camp Two",
      "campaign": "camp2",
      "source": "social",
      "medium": "urld",
      "event_id": "6a7c1d8fcca95cf3b98fe879",
      "urls_count": 0,
      "paused": false
    }
  ],
  "status": 200
}

POST/events

Create new campaign Event.

Request Body Structure

{
  "data": {
    "name": "Year Long Campaign", // required, 5-25 chars
    "expires_on": "2026-12-31T11:23:44Z",
    "campaign": "sale26",  // utm campaign
    "source": "social",    // utm source
    "medium": "urld.me",   // utm medium
    "content": ""    // utm content
  }
}

Response 200 OK

{
  "status": 201,
  "message": "Event created successfully",
  "data": {
    "event_id": "6a7c1f75cca95cf3b98fe87e",
    "name": "Year Long Campaign",
    // other details ...
  }
}

PATCH/events/{event_id}

Update an event by it's ID.

Request Body Structure

{
  "data": {
    "name": "Year Long Campaign", // required, 5-25 chars
    "paused": true // put this event on hold before expiry
  }
}

Response 200 OK

{
  "status": 200,
  "message": "Event updated successfully",
  "data": {
    "event_id": "6a7c1f75cca95cf3b98fe87e",
    "name": "Year Long Campaign"
    // other event details ...
  }
}

Response 400 Not Found

{
  "status": 404,
  "code": "data_error",
  "error": "Requested Event not found",
}

GET/analytics

List and query multi-faceted analytics with filtering options.

Query Parameters

All query params are optional.

Parameter	Type	Description
`domain`	string	Filter analytics by short domain.
`from`	string (Date)	Start date in `YYYY-MM-DD` format.
`to`	string (Date)	End date in `YYYY-MM-DD` format.
`interval`	string	Time aggregation interval (e.g., `day`, `month`). Default is `day`.
`url_id`	string	Filter analytics by specific URL ID.
`event_id`	string	Filter analytics by specific Event ID.
`page`	integer	Page index for paginated results (Default: `1`).
`size`	integer	Number of results per page (Default: `25`).

Response 200 OK

{
  "data": {
    "hits": [
      {
        "date": "2026-08-01T00:00:00Z",
        "counts": {
          "all": 1,
          "qr": 0,
          "uniq": 1
        }
      },
      {
        "date": "2026-08-02T00:00:00Z",
        "counts": {
          "qr": 0,
          "uniq": 4,
          "all": 4
        }
      }
    ],
    "countries": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "SG": 1,
          "TH": 3,
          "US": 8
        }
      }
    ],
    "regions": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "Bangkok": 2,
          "Singapore": 1,
          "The Dalles": 6
        }
      }
    ],
    "browsers": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "Safari": 6,
          "Android": 2,
          "Bingbot": 1,
          "Chrome": 7
        }
      }
    ],
    "referrers": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "urld.me": 12,
          "ugo.li": 14,
          "Direct": 33
        }
      }
    ],
    "domains": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "urld.me": 2,
          "ugo.li": 6
        }
      }
    ],
    "languages": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "en-us": 9,
          "zh-cn": 3
        }
      }
    ],
    "devices": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "Desktop": 35,
          "Bot": 5,
          "Mobile": 20
        }
      }
    ],
    "models": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "K": 11,
          "IPhone": 2,
          "Xiaomi 11T Pro": 1,
          "Pixel 6": 5
        }
      }
    ],
    "oses": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "Windows": 13,
          "Android": 18,
          "Other": 26,
          "Linux": 3
        }
      }
    ],
    "platforms": [
      {
        "date": "2026-01-01T00:00:00Z",
        "counts": {
          "Windows": 13,
          "Linux": 18,
          "Macintosh": 6,
          "IPhone": 2,
          "X11": 3
        }
      }
    ]
  },
  "meta": {
    "domain": "",
    "from": "2026-08-01T00:00:00Z",
    "plan": "ULTRA",
    "interval": "day"
  },
  "status": 200
}

Component Schemas

URL Object / Payload

Combined schema of URL payload and response objects. Fields vary by nature of request and scope.

Property	Type	Scope	Example	Description
`url`	string	Request Response	`"https://www.somesite.com/r/all"`	Target destination URL.
`title`	string	Request Response	`"somesite - r/all"`	Custom title tag for link preview metadata.
`desc`	string	Request Response	`"All the trending stuffs in somesite.com"`	Description string for meta tag embedding.
`domain`	string	Request Response	Default: `"root"`	Domain attached to the shortened link.
`short_code`	string	Request Response	`"somesite-all"`	Custom or auto-assigned short alias slug.
`tags`	array [string]	Request Response	`["somesite", "trend"]`	Keywords attached to organize and search links.
`rules`	array [Rule]	Request Response	Default: `[]`	Targeting rules for conditional redirects.
`image`	string	Request Response	Default: `""`	Custom social media thumbnail image URL.
`passphrase`	string	Request	Default: `""`	Optional password to restrict target access.
`expires_on`	string	Request Response	Default: `""`	ISO date string indicating URL expiration.
`event_id`	string	Request	`"6a72e443d0a34051c8fcaca2"`	Event ID (takes precedence over UTM tracking parameters).
`utm_medium`	string	Request Response	`"cpc"`	Marketing medium parameter.
`utm_source`	string	Request Response	`"google"`	Marketing source parameter.
`utm_campaign`	string	Request Response	`"summer_sale"`	Campaign identifier parameter.
`utm_content`	string	Request Response	`"banner_ad"`	Campaign content variant parameter.
`has_qr`	boolean	Request Response	Default: `false`	Flag specifying whether to auto-generate a companion QR code.
`fallback`	boolean	Request	Default: `false`	Fallback behavior option when no matching rules trigger.
`url_id`	string	Response	`"6a72e443d0a34051c8fcaca2"`	Unique record ID assigned to the URL entry.
`created_at`	string (date-time)	Response	`"2026-08-05T07:20:35.949Z"`	ISO-8601 timestamp of creation date.
`source`	string	Response	`"api"`	Channel through which the URL was generated.
`short_url`	string	Response	`"https://urld.me/nexus"`	Fully qualified short link URI.
`hits`	integer	Response	`45`	Total click count (included in detailed item views).
`uniques`	integer	Response	`7`	Unique visitor count (included in detailed item views).
`scans`	integer	Response	`13`	QR code scan count (included in detailed item views).
`is_custom`	boolean	Response	`true`	Indicates if a user-supplied short code was set.
`status`	integer	Response	`201` `419`	HTTP status code returned in response wrapper object.
`error`	string	Response	`"URL is already shortened"`	Status description or action outcome message.

Event

The campaign Event object used across endpoints. Fields vary by nature of request and scope.

Field	Type	Scope	Description
`event_id`	string	Response	Unique identifier for the event.
`name`	string	Required	Name of the campaign event (5–25 characters).
`expires_on`	string (ISO-8601)	Request Response	Expiration timestamp for the event.
`campaign`	string	Request Response	UTM campaign parameter associated with the event.
`source`	string	Request Response	UTM source parameter associated with the event.
`medium`	string	Request Response	UTM medium parameter associated with the event.
`content`	string	Request Response	UTM content parameter associated with the event.
`paused`	boolean	Request Response	Whether the event is put on hold prior to expiration. Default is `false`.
`urls_count`	integer	Response	Total number of URLs linked to this event.
`created_at`	string (ISO-8601)	Response	Creation timestamp of the event.
`status`	integer	Response	HTTP status code returned in response wrapper object.
`message`	string	Response	Status description or action outcome message (e.g. "Event created successfully").

Rule (Redirection Rule)

Dynamic redirection rules based on geo-location, client language, or device/operating system characteristics.

Property	Type	Example / Enums	Description
`key`	string	`iso`, `lang`, `dev`, `os`	Rule trigger type. `"iso"`: Country ISO2 `"lang"`: Language code `"dev"`: Device type `"os"`: Operating system
`val`	string	eg: `"US"`	Trigger value to match. `"iso"` values: Refer wikipedia `"lang"` values: Refer gist `"dev"` values: Desktop, Tablet, Mobile, Bot `"os"` values: Linux, Windows, Mac, Android, iOS
`url`	string	eg: `"?us=1"`	Target URL path or query parameter append on trigger match.

Error

Standardized error format returned across invalid input, authentication failures, and conflict errors.

Property	Type	Example / Enums
`status`	integer	`400` `401` `403` `413` `422` `429` `500`
`code`	string	`auth_error` `input_error` `data_error` `user_error` `internal_error` `limit_error` `plan_error`
`error`	string	eg: `"Empty data or invalid JSON or unsupported format in post body"`