GET

List Links

/api/v1/external/links

Returns the authenticated user's links, newest first, using offset/limit pagination. Supports optional filtering by destination URL.

Authentication

Authorization: Token YOUR_API_KEY

Query Parameters

Parameter Type Required Default Description
limit integer No 20 Number of results to return. Range: 1–100.
offset integer No 0 Zero-based pagination offset.
long_url string No — Filter results by destination URL. Max 2048 characters. Combine with match to control how the comparison is applied.
match string No exact Matching strategy for long_url. Allowed values: exact (full URL match) or startswith (prefix match, useful for filtering by domain).

Response 200 OK 

{
  "offset": 0,
  "limit": 20,
  "total": 42,
  "results": [
    {
      "id": "018e1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
      "short_code": "abc123",
      "long_url": "https://example.com/landing",
      "domain": "hozip.link",
      "group_id": "018e1b2c-0000-7f8a-9b0c-1d2e3f4a5b6c",
      "is_active": true,
      "created_at": "2025-12-01T10:23:00.000000Z"
    }
  ]
}
Field Type Description
offset integer The offset applied to this page.
limit integer The limit applied to this page.
total integer Total number of links matching the query (ignoring pagination).
results[].id string (UUID) Unique link identifier.
results[].short_code string The alias used in the short URL path.
results[].long_url string The destination URL the link redirects to.
results[].domain string The hostname the short link is served on.
results[].group_id string (UUID) UUID of the group this link belongs to.
results[].is_active boolean true if the link is active and will perform a redirect; false if it is paused.
results[].created_at string (ISO 8601) Creation timestamp in UTC.

Error Responses

Status Description
400 A query parameter has an invalid value — e.g. limit out of the 1–100 range, or an unrecognised match value. Returns { "detail": "...", "error_code": "..." }.
401 Missing or invalid API key.

Examples

cURL — basic paginated list

curl -G "https://hozip.com/api/v1/external/links" \
     -H "Authorization: Token YOUR_API_KEY" \
     --data-urlencode "limit=20" \
--data-urlencode "offset=0"

cURL — filter by destination URL prefix

curl -G "https://hozip.com/api/v1/external/links" \
     -H "Authorization: Token YOUR_API_KEY" \
     --data-urlencode "long_url=https://example.com/" \
--data-urlencode "match=startswith"

Python (requests) — iterate all pages

import requests
BASE = "https://hozip.com/api/v1/external/links"
HEADERS = {"Authorization": "Token YOUR_API_KEY"}
LIMIT = 100
offset = 0
all_links = []

while True:
    resp = requests.get(
        BASE, headers=HEADERS, params={"limit": LIMIT, "offset": offset}
    )
    resp.raise_for_status()
    data = resp.json()
    all_links.extend(data["results"])
    if offset + LIMIT >= data["total"]:
        break
    offset += LIMIT
Documentation