Links API: Create, Update, Archive, and Purge Short Links

Links are the core resource in linq. Each link pairs a slug on a domain with a destination URL, and optionally a set of routing rules, OG metadata, preset query parameters, and an expiry time. All link endpoints require a valid API key sent as Authorization: Bearer <key> or X-Api-Key: <key>. Roles are ordered viewer < editor < admin; each operation below states the minimum it requires.

Archiving vs. purging. DELETE /api/v1/links/{id} archives a link — it stops redirecting but its row, visit history, and slug reservation all remain intact. The only way to permanently destroy a link and release its slug is to purge it via DELETE /api/v1/links/{id}/purge (single) or DELETE /api/v1/links/purge (bulk). Archiving is reversible with PATCH { "status": "active" }; purging is not.

GET /api/v1/links

List links, paginated and filterable. Every role may call this endpoint. Minimum role: viewer

Query parameters

limit

integer

Maximum records to return per page. Defaults to the server’s configured page size.

offset

integer

Zero-based offset into the result set for pagination.

string

Substring match (case-insensitive) across slug, name, and destination. Minimum 1 character, maximum 200.

tags

string

Comma-separated tag list. A link matches when it carries any of the provided tags. Example: launch,press.

domain_id

string

Comma-separated UUID(s). Filters links to one or more domains.

status

string

default:"active"

One of active, archived, or all.

sort

string

default:"created_at"

Sort column: created_at, updated_at, or visits.

order

string

default:"desc"

Sort direction: asc or desc.

expiry

string

default:"any"

Filter by expiry state relative to now: any, live (never-expiring or future expiry), or expired.

Response — 200

data

Link[]

Array of link objects matching the query.

total

integer

Total count of matching records across all pages.

limit

integer

Page size used for this response.

offset

integer

Offset used for this response.

curl https://links.example.com/api/v1/links \
  -H "Authorization: Bearer linq_xxxx" \
  -G \
  --data-urlencode "status=active" \
  --data-urlencode "sort=visits" \
  --data-urlencode "order=desc" \
  --data-urlencode "limit=20"

POST /api/v1/links

Create a new short link. Omit slug to have one generated automatically. A custom slug that is already taken on that domain — even by an archived link — returns 409 Conflict. Minimum role: editor

Request body

domain_id

string

required

UUID of the domain this link belongs to. The domain must be active.

destination

string

required

The long URL visitors are sent to. Must be a valid URL.

slug

string

Custom slug (1–64 characters, [A-Za-z0-9_-]). Omit for a server-generated slug. Immutable after creation.

name

string

Human-readable label (max 200 chars). When absent, the server attempts to fetch the destination page’s <title>, falling back to the destination host.

description

string

Optional description (max 500 chars). When absent, the server attempts to fetch the destination page’s meta description.

tags

string[]

default:"[]"

Up to 20 tag strings (each up to 50 chars). Used for filtering; tags are derived from active links — there is no separate tag table.

forward_query

boolean

default:"true"

When true, the incoming query string is merged onto the destination URL. Also gates preset_params: when false, neither forwarded query nor preset params are applied.

preset_params

object

default:"{}"

Key-value pairs (up to 20 entries; keys max 64 chars, values max 512 chars) set on the destination at redirect time. They override both the destination’s own query and any forwarded query on collision. Applied only when forward_query is true.

expires_at

string | null

ISO-8601 datetime. After this moment the link resolves like an unknown slug. null or absent means it never expires.

listed

boolean

default:"false"

When true, the link appears in the domain’s public /llms.txt catalogue.

rules

RuleInput[]

default:"[]"

Initial routing rules. An ordered array of rule objects (up to 50). See the Rules API for the rule input shape. Positions are assigned from array order.

Response — 201

Returns the created Link object.

curl -X POST https://links.example.com/api/v1/links \
  -H "Authorization: Bearer linq_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "018f1e2a-0001-7000-8000-000000000001",
    "destination": "https://example.com/product/launch-2025",
    "slug": "launch25",
    "name": "Product Launch 2025",
    "tags": ["launch", "marketing"],
    "forward_query": true
  }'

GET /api/v1/links/count

Return only the total count of links matching a status filter, without fetching any link rows. Useful for sidebar badges and counters that have no need for full link data. Minimum role: viewer

Query parameters

status

string

default:"active"

One of active, archived, or all.

Response — 200

total

integer

Number of links matching the given status filter.

curl https://links.example.com/api/v1/links/count \
  -H "Authorization: Bearer linq_xxxx" \
  -G --data-urlencode "status=archived"

GET /api/v1/links/

Fetch a single link by its UUID. Includes denormalized domain_host, short_url, visit totals, and rule_count. Minimum role: viewer

Path parameters

string

required

UUID of the link.

Response — 200

Returns the Link object.

curl https://links.example.com/api/v1/links/018f1e2a-0001-7000-8000-000000000042 \
  -H "Authorization: Bearer linq_xxxx"

PATCH /api/v1/links/

Update one or more mutable fields on a link. The request body is strict: slug and domain_id are immutable and sending either returns 400. Status changes (archiving or restoring) require admin; all other field updates require editor. Minimum role: editor (or admin for status changes)

Path parameters

string

required

UUID of the link to update.

Request body

All fields are optional. Send only the fields you want to change.

destination

string

New destination URL. Triggers a fresh metadata fetch for name, description, and icon_url if the caller does not also supply them.

name

string | null

New label (max 200 chars). null clears it (the server will re-derive it on the next metadata fetch).

description

string | null

New description (max 500 chars). null clears it.

tags

string[]

Replaces the full tag list (up to 20 entries).

forward_query

boolean

Toggle query forwarding and preset-params application.

preset_params

object

Replaces the full preset-params map (up to 20 key-value pairs).

status

string

active or archived. Admin only. Restoring an archived link does not reclaim any visits that occurred while it was archived.

expires_at

string | null

ISO-8601 datetime, or null to remove the expiry.

listed

boolean

Toggle /llms.txt visibility.

rules

RuleInput[]

Replaces the full rules list atomically. Send [] to clear all rules.

Response — 200

Returns the updated Link object.

curl -X PATCH https://links.example.com/api/v1/links/018f1e2a-0001-7000-8000-000000000042 \
  -H "Authorization: Bearer linq_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/product/v2",
    "tags": ["launch", "v2"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

DELETE /api/v1/links/

Archive a link (soft delete). The link stops redirecting — its slug becomes an orphan — but its row, visit history, and slug reservation are preserved. Reversible via PATCH { "status": "active" }. Minimum role: admin

Path parameters

string

required

UUID of the link to archive.

Response — 200

Returns the updated Link object with status: "archived".

curl -X DELETE https://links.example.com/api/v1/links/018f1e2a-0001-7000-8000-000000000042 \
  -H "Authorization: Bearer linq_xxxx"

DELETE /api/v1/links//purge

Permanently destroy an archived link. Its rules are deleted with it (ON DELETE CASCADE). Its visits survive as orphan visits — their analytics history is preserved but attribution to this link is removed. This operation releases the slug for reuse on that domain.

Purging is irreversible. The link row, its rules, and its slug reservation are all destroyed. Visit records become orphaned (history kept, attribution lost). You must archive the link before you can purge it — calling purge on an active link returns 409 Conflict.

Minimum role: admin

Path parameters

string

required

UUID of the archived link to purge.

Response — 204

No content on success.

curl -X DELETE https://links.example.com/api/v1/links/018f1e2a-0001-7000-8000-000000000042/purge \
  -H "Authorization: Bearer linq_xxxx"

DELETE /api/v1/links/purge

Bulk-purge every archived link in one call — the “Empty archive” operation. Equivalent to calling DELETE /api/v1/links/{id}/purge for every archived link, but done server-side in a single query. Each link’s rules go with it. Takes no filters: this always means every archived link.

This is a bulk irreversible operation. All currently archived links are permanently destroyed along with their rules. Visit records become orphaned. There is no undo.

Minimum role: admin

Response — 200

purged

integer

Number of links that were permanently destroyed.

curl -X DELETE https://links.example.com/api/v1/links/purge \
  -H "Authorization: Bearer linq_xxxx"

Link object

The full Link response shape returned by all link endpoints.

string

UUID (v7) of the link.

domain_id

string

UUID of the domain this link belongs to.

domain_host

string

Denormalized hostname (e.g. links.example.com). Included so list rows render without a second request.

slug

string

The path segment after the host. Pattern [A-Za-z0-9_-]{1,64}. Immutable.

short_url

string

The full short URL, assembled from domain_host and slug at read time. Uses https:// for non-localhost hosts.

destination

string

The long URL this link redirects to by default.

name

string | null

Human-readable label (max 200 chars). Auto-derived from the destination page title when not supplied.

description

string | null

Optional description (max 500 chars).

icon_url

string | null

Favicon or OG image URL fetched from the destination page.

tags

string[]

Up to 20 tag strings.

forward_query

boolean

Whether the incoming query string is merged onto the destination. Also gates preset_params.

preset_params

object

Show preset_params

Key-value map of query parameters set on the destination at redirect time. Up to 20 entries. Keys: max 64 chars. Values: max 512 chars. Applied only when forward_query is true; they override both the destination’s own query and any forwarded query on collision.

status

string

active or archived.

human_visits

integer

Count of non-bot visits. Sourced from the visit_counts materialized counter kept in sync by a database trigger.

bot_visits

integer

Count of bot visits.

expires_at

string | null

ISO-8601 datetime after which the link resolves like an unknown slug. null means it never expires.

listed

boolean

Whether this link appears in the domain’s public /llms.txt catalogue.

rule_count

integer

Number of routing rules attached to this link. When greater than zero, the link uses dynamic routing; see the Rules API.

created_at

string

ISO-8601 creation timestamp.

updated_at

string

ISO-8601 last-updated timestamp.

Overview

Resources

Links API: Create, Update, Archive, and Purge Short Links

GET /api/v1/links

Query parameters

Response — 200

POST /api/v1/links

Request body

Response — 201

GET /api/v1/links/count

Query parameters

Response — 200

GET /api/v1/links/

Path parameters

Response — 200

PATCH /api/v1/links/

Path parameters

Request body

Response — 200

DELETE /api/v1/links/

Path parameters

Response — 200

DELETE /api/v1/links//purge

Path parameters

Response — 204

DELETE /api/v1/links/purge

Response — 200

Link object

Build docs developers (and LLMs) love

Overview

Resources

Documentation Index

​GET /api/v1/links

​Query parameters

​Response — 200

​POST /api/v1/links

​Request body

​Response — 201

​GET /api/v1/links/count

​Query parameters

​Response — 200

​GET /api/v1/links/

​Path parameters

​Response — 200

​PATCH /api/v1/links/

​Path parameters

​Request body

​Response — 200

​DELETE /api/v1/links/

​Path parameters

​Response — 200

​DELETE /api/v1/links//purge

​Path parameters

​Response — 204

​DELETE /api/v1/links/purge

​Response — 200

​Link object

Build docs developers (and LLMs) love

GET /api/v1/links

Query parameters

Response — 200

POST /api/v1/links

Request body

Response — 201

GET /api/v1/links/count

Query parameters

Response — 200

GET /api/v1/links/

Path parameters

Response — 200

PATCH /api/v1/links/

Path parameters

Request body

Response — 200

DELETE /api/v1/links/

Path parameters

Response — 200

DELETE /api/v1/links//purge

Path parameters

Response — 204

DELETE /api/v1/links/purge

Response — 200

Link object