Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/org-quicko/linq/llms.txt

Use this file to discover all available pages before exploring further.

Links are the core entity in linq. Every short URL is a link: a slug on a domain that either redirects a visitor to a long destination or serves a hosted link-tree page. Links carry their own metadata, optional expiry, visit counters, and a full lifecycle from creation through optional soft-deletion to permanent purge. Understanding how links and slugs work is the foundation for everything else you build with the API. Every link has a kind that controls what happens when a visitor lands on its short URL.
A redirect link sends visitors to a Destination URL with an HTTP 302 response. This is the standard short-link use case. A redirect link may carry up to 50 conditional Rules (see Dynamic Links) to route different visitors to different destinations.

​
Slugs

A slug is the path segment after the host that uniquely identifies a link within a domain — the abc123 in https://go.example.com/abc123.

Random slugs

When you omit slug on create, linq generates a random slug using base-62 characters ([A-Za-z0-9_-]). The default length is 6 characters, controlled by the LINQ_SLUG_LENGTH environment variable. With the default length you have 62⁶ ≈ 56 billion possible slugs per domain.

Custom slugs

Supply any value matching ^[A-Za-z0-9_-]{1,64}$ in the slug field when creating a link. If that slug is already taken on the domain, the API returns 409 Conflict. Reserved path segments (such as /api and the Client UI base path) are rejected with 400.
Slugs are immutable once set — changing a slug would break any live short URL. To move a link to a different slug, archive the old one and create a new link. A slug remains reserved for as long as its link row exists, archived or not; only a Purge releases it.

​
Short URL Format

The short_url field on every link response contains the fully assembled URL. The scheme is chosen automatically: 
// From apps/server/src/http/api/links.ts
export function shortUrl(host: string, slug: string): string {
  const scheme = /^(localhost|127\.0\.0\.1)(:\d+)?$/.test(host) ? "http" : "https"
  return `${scheme}://${host}/${slug}`
}
  • localhost or 127.0.0.1 (with or without a port) → http://
  • Any other host → https://
This means a local development setup on localhost:3000 produces http://localhost:3000/abc123, while a production domain like go.example.com always produces https://go.example.com/abc123. The full shape of a link returned by the API:
​
id
string (UUID)
Unique identifier for the link. UUIDv7, so it is time-sortable.
​
domain_id
string (UUID)
The domain this link belongs to. Set at create time and immutable.
​
domain_host
string
The host string of the domain, e.g. go.example.com. Joined into every response for convenience.
​
slug
string
Path segment. Immutable. Pattern: ^[A-Za-z0-9_-]{1,64}$.
​
short_url
string (URI)
Fully assembled short URL: https://<domain_host>/<slug> (or http:// for localhost).
​
destination
string (URI)
The long URL visitors are sent to when the link resolves.
​
name
string | null
Human-readable label. Auto-populated from the destination page’s <title> when LINQ_FETCH_LINK_METADATA is enabled, falling back to the destination host. Up to 200 characters.
​
description
string | null
Optional description. Auto-populated from the destination’s <meta name="description"> when metadata fetching is enabled. Up to 500 characters.
​
icon_url
string (URI) | null
Favicon or icon URL fetched from the destination page’s <head> when LINQ_FETCH_LINK_METADATA is enabled. null if not fetched or not found.
​
tags
string[]
Up to 20 free-form tags (each up to 50 chars). Used for filtering in GET /api/v1/links.
​
forward_query
boolean
When true, the caller’s incoming query string is merged into the destination URL at redirect time. Defaults to true. Also gates preset_params.
​
preset_params
object
Key–value pairs (up to 20, keys ≤ 64 chars, values ≤ 512 chars) applied to the destination at redirect time. When forward_query is true, preset params overwrite any colliding key from either the destination’s own query or the forwarded query. See Query Forwarding and Preset Params below.
​
status
"active" | "archived"
Current lifecycle state. See Link Lifecycle.
​
expires_at
string (ISO 8601) | null
When set, the link stops redirecting after this timestamp. null means the link never expires.
​
listed
boolean
Opt-in flag controlling whether this link appears in the domain’s GET /llms.txt catalogue for AI crawlers. Defaults to false.
​
rule_count
integer
The number of conditional rules attached to this link. When greater than zero, the Client UI marks the link as routing dynamically.
​
human_visits
integer
Cumulative visit count for requests that were not detected as bots or link-preview crawlers.
​
bot_visits
integer
Cumulative visit count for requests that were detected as bots or link-preview crawlers.

​
Query Forwarding and Preset Params

When forward_query is true (the default), linq merges the visitor’s own query string into the destination URL before redirecting. Preset params are then applied on top, winning any collision: 
Incoming request:  https://go.example.com/abc123?utm_medium=email&color=blue
Destination:       https://app.example.com/landing?color=red
preset_params:     { "utm_source": "linq", "color": "green" }

Final URL:         https://app.example.com/landing?color=green&utm_medium=email&utm_source=linq
In this example color=red (destination’s own query) is overridden by color=blue (forwarded), which is then overridden by color=green (preset param). Preset params always win on collision.
Setting forward_query: false disables both query forwarding and preset params in one step, since preset params are only applied when the link forwards its query.
Links move through a three-stage lifecycle. Only admins can archive or purge.
1

Active

The link resolves normally. Visits are recorded. The short URL works. This is the initial state after creation.
2

Archived

A soft delete triggered by DELETE /api/v1/links/{id}. The slug is still reserved — no other link can claim it. Existing visits are retained. An archived link never redirects: visitors land on the domain’s fallback URL or get a 404. Archiving is reversible by patching status back to "active".
3

Purged

Permanent destruction triggered by DELETE /api/v1/links/{id}/purge. The link row is deleted. The slug is released for reuse on the same domain. All visits for this link are destroyed (ON DELETE CASCADE). Irreversible. A link must be in archived status before it can be purged.
Purging is irreversible and destroys all visit history for the link. Archive first, then purge only when you are certain the data is no longer needed. Only API keys with the admin role can perform either operation.
The bulk endpoint DELETE /api/v1/links/purge destroys every archived link at once and is also admin-only. Setting expires_at to an ISO 8601 datetime makes the link behave as an orphan after that timestamp — the visitor is sent to the domain’s fallback URL or gets a 404. The link row is not automatically deleted; it stays in active status and can have its expiry extended by patching expires_at.
Because a cached redirect entry can outlive its expires_at timestamp without the cache knowing, linq intentionally treats expired links as orphans at read time rather than filtering them in SQL. The cache TTL (default 5 minutes, set via LINQ_CACHE_TTL) is the maximum extra time an expired link can still redirect.

​
OG Preview

When a link-preview crawler (Slack, iMessage, Twitter Cards, etc.) hits a short URL, linq detects the crawler’s User-Agent and returns a small HTML page carrying the link’s own Open Graph tags — og:title, og:description, and og:image — instead of a 302. This ensures social cards show your curated metadata, not the destination’s own tags, and avoids a live fetch to the destination on every crawler hit.
The listed field controls whether a link appears in GET /llms.txt — a plain-text catalogue read by AI crawlers and LLMs to discover the short links on a domain. It defaults to false. Set it to true only for links you want AI tools to know about publicly.

Build docs developers (and LLMs) love

Get started for freeTalk to us