Urlicer API v1

Changelog

Everything that has changed in v1, and how we treat changes that could break you.

The API is at version 1. Additions (a new endpoint, a new optional field, a new field in a response) arrive without a version bump, so write clients that ignore fields they do not recognise rather than rejecting them.

Anything that could break a working integration gets a new version instead, and v1 keeps answering. Entries below that could have affected an existing client are marked.

2026-10-01

App links on a link

Create and update take three new fields, on Team and above: iosAppLink and androidAppLink are links into your mobile app (your app's own scheme such as "myapp://product/42", or https://), and androidPackage is the Android app's package name, required with androidAppLink. A visitor on that system is offered the app and continues to url if it does not open. Every link in a response, and in a webhook payload, now carries the three fields, null when not set. On an update, null removes one. A plan without the feature answers 403 feature with the key DeepLinks. Bulk create does not take them.

2026-09-30

Shortest alias on the shared domain depends on the plan

Could affect existing clients

A custom alias on the shared short domain now has a minimum length that depends on the plan. A shorter one answers 400 validation on create, with the minimum in the message, and fails its own row in a bulk create. Aliases on your own custom domains are not affected, and aliases that already exist keep working whatever their length.

2026-09-30

Webhooks

Workspaces on Team and above can add HTTPS endpoints in the app and receive a signed POST when a link is created, edited or deleted (in the app or through the API), when links are bulk-created, when a custom domain is verified and when a member joins. The link in these events has the same fields as a link from the API. See /docs/webhooks for the payloads, the Urlicer-Signature header and the retry schedule. Nothing changes for an API client.

2026-09-29

Start dates, click limits and fallback URLs

Create and update take three new fields, on Pro and above: maxClicks stops a link after that many clicks since it was created (clicks from people; bots and link previews do not count), startsOn keeps it from resolving before a moment you choose, and fallbackUrl is where visitors go while the link is not live, before the start, after the expiry or past the limit, instead of our page. On an update, null removes each one. Bulk create takes them on each link, or at the top level as a default for the whole batch. Every link response now carries all three, null when not set. Nothing changes for a request that does not mention them.

2026-09-23

UTM naming rules can belong to a folder

A workspace can now set UTM naming rules on a folder as well as on the workspace. Which rules a request is checked against depends on where the link ends up: the folder named in "folder", or the folder the link is already in, then the nearest folder above it that has rules, then the workspace. A folder's rules replace the ones it would otherwise follow rather than adding to them. Nothing changes for a workspace that keeps its rules in one place, and moving a link between folders never fails on naming rules: only a tag you actually change is checked.

2026-09-23

Folders, names and notes

Links can be filed in folders through the API. Create, bulk create and update take a folder path such as "Campaigns/Q4", creating any level that does not exist yet, and "folder": null on an update takes a link out of its folder. Every link response now carries folder, title and notes; title and notes can be set on create, in a bulk row and on update, and are free on every plan. Listing takes ?folder= for a folder and everything beneath it, or ?unfiled=1 for the links in no folder. The new /api/v1/folders endpoints list, create, rename, move and delete folders, every one of them naming the folder by path rather than by id; deleting one moves its links and subfolders up rather than removing them. Folders are a paid feature, reading them included, so a plan without them answers 403 feature. Nothing changes for a request that does not mention folders.

2026-09-22

Workspace UTM naming rules apply to the API

A workspace on Pro or above can keep a list of allowed utm_source, utm_medium and utm_campaign values. Creating, bulk-creating or updating a link through the API follows those rules exactly as the app does: tags are lowercased first when the rules say so, a value that is not on a list answers 400 validation when the rules block, and when they warn the link is saved and the new warnings field (warning on a bulk row) says what. Every link response now carries warnings, an empty array unless that happened. A workspace without rules sees no change.

2026-09-21

Naming the domain of a link you read, change or delete

Could affect existing clients

GET, PATCH and DELETE /api/v1/links/{code} accept ?domain=: a custom domain by host, ivi.to, or "default". Before, when the same code existed on two of your domains, these requests acted on whichever link the database returned first. PATCH or DELETE could change or remove the wrong one. Now, with no domain, a code held on more than one domain answers 409 ambiguous_code and changes nothing. A code on only one domain works exactly as before.

2026-09-20

domain can be "default"

Creating a link, or a bulk batch, accepts "default" as the domain: it uses whichever custom domain the workspace has set as its default, as the app's own create form now does. A workspace with no default answers 400 validation. Nothing changes for a request that leaves the field out — that still uses ivi.to.

2026-09-19

Server errors carry an error field

Could affect existing clients

A 500 now answers like every other failure: error is server_error and message says what failed. The old body had no error field and listed messages in an errors array, which is gone. An unexpected failure also includes a reference, the same value as the X-Error-Reference header.

2026-09-10

A destination that is already a short link is refused

Could affect existing clients

Creating a link, or changing a link's destination with PATCH, now answers 400 validation when the destination is itself a short link: one of ours, a verified custom domain, or another known URL shortener. In a bulk request only that row fails. Point links at the final destination instead.

2026-09-03

Higher rate limits on every plan

Per-key budgets went from 5, 20, 60 and 600 requests per minute on Free, Pro, Team and Business to 30, 120, 600 and 3,000.

2026-08-21

Deleting a link frees its custom alias

A deleted link used to keep its code reserved, so its custom alias could never be created again. The alias is now released on delete. On the default ivi.to domain anyone can then create a link with it.

2026-08-17

The API is included in every plan, the free one included

It had been a paid feature. A free key uses the same endpoints as a paid one, with no trial period. Plans differ in throughput, in how many keys a workspace may hold, and in which link features a key may use. Per-minute budgets changed at the same time, and no plan lost any.

2026-08-16

A taken alias now answers 409 instead of 400

Could affect existing clients

Asking for a custom alias somebody already holds used to be reported as a malformed request, which told clients to give up when the right move is to try a different alias. It is now alias_taken with a 409, and the alias is named in the body. Clients that treated any 400 as fatal keep working; clients that want to retry can now tell the two apart.

2026-08-16

Writes made by a key appear in the workspace audit trail

Creating, updating and deleting through the API is recorded against the key's name rather than a person, since nobody was at a keyboard. Nothing about the API itself changed.

2026-08-07

Rules for custom aliases

Could affect existing clients

A custom alias can be at most 40 characters long and may contain only letters, digits, - and _. Any other alias answers 400 validation, and in a bulk request that row fails.

2026-07-22

PATCH /api/v1/links/{code}

Change a link's destination, set or clear an expiry or password, and switch a link off without deleting it. Only the fields present in the body change.

2026-07-22

X-RateLimit-Limit and X-RateLimit-Remaining on every response

Your remaining budget is now readable from any response instead of having to be inferred by running out.

2026-07-21

v1 launched

Create, list, read and delete links, plus bulk creation. Bearer key authentication, per-key rate limiting and the JSON error contract have been in place from this first release.

What will not change under you

A short link keeps resolving until you delete it or switch it off, its expiry passes, or we block it because its destination is harmful.
The generator never issues the same code twice. A custom alias is released when you delete its link, and on the default domain someone else can then create a link with it. To keep a code, switch the link off instead of deleting it.
The error values on the errors page are stable identifiers. The human-readable messages beside them are not, so do not match on those.
Times stay unix seconds, in both directions.