POST

Create Short Link

/api/v1/external/links/create-link

Creates a short link for the authenticated user. Only long_url is required; all other fields are optional.

When should you use this endpoint? Links created here are persistent: they are stored in your account, appear in the dashboard, and count against your creation quota.
If the link will be used infrequently or just once — e.g. a one-time download, a temporary access URL, or a single-use campaign — use Dynamic Links instead. Dynamic Links are generated entirely on the client: no API call is made, no rate limit applies, and no record is stored in your account.
Rate limit: 100 link creations per hour, per API key. Exceeding this limit returns 429 Too Many Requests.

Authentication

Authorization: Token YOUR_API_KEY

Request Body application/json

Field Type Required Description
long_url string Required Destination URL. Must start with https://. Max 2048 characters.
short_code string No Custom alias for the short link. 3–50 characters. Allowed characters: letters, digits, _, -. Stored as lowercase. If omitted, a unique code is generated automatically.
group_id string (UUID) No UUID of the group to assign this link to. Must belong to the authenticated user. If omitted or not found, the user's default group is used.
domain_id string (UUID) No UUID of the domain to host this link on. Must be an enabled platform domain or one of the user's active custom domains (see Enabled Domains). If omitted or not found, an available platform domain is selected automatically.

Response 201 Created 

{
  "id": "018e1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "short_code": "summer-sale",
  "short_url": "https://hozip.link/summer-sale",
  "group_id": "018e1b2c-0000-7f8a-9b0c-1d2e3f4a5b6c",
  "domain": "hozip.link",
  "domain_id": "018e0000-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}
Field Type Description
id string (UUID) Unique identifier for the created link.
short_code string The alias used in the short URL path.
short_url string The fully-qualified short URL, ready to share.
group_id string (UUID) UUID of the group the link was assigned to.
domain string Hostname the short link resolves on.
domain_id string (UUID) UUID of the domain.

Error Responses

Status error_code Description
400 validation_error A field failed validation — e.g. long_url does not start with https://, or short_code is too short, too long, or contains invalid characters.
400 short_code_exists The requested custom alias is already taken on the target domain. Choose a different short_code or omit it to auto-generate one.
400 platform_domain_unavailable No platform domain is currently available. Retry shortly, or pass a domain_id for one of your custom domains.
401 — Missing or invalid API key.
429 — Rate limit exceeded. Maximum 100 link creations per hour per API key.

Examples

cURL — minimal request (auto-generated code)

curl -X POST "https://hozip.com/api/v1/external/links/create-link" \
     -H "Authorization: Token YOUR_API_KEY" \
     -H "Content-Type: application/json" \
-d '{"long_url": "https://example.com/landing"}'

cURL — with custom alias and group

curl -X POST "https://hozip.com/api/v1/external/links/create-link" \
     -H "Authorization: Token YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "long_url": "https://example.com/landing",
       "short_code": "summer-sale",
       "group_id": "018e1b2c-0000-7f8a-9b0c-1d2e3f4a5b6c"
}'

Python (requests)

import requests
resp = requests.post(
    "https://hozip.com/api/v1/external/links/create-link",
    headers={
        "Authorization": "Token YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "long_url": "https://example.com/landing",
        "short_code": "summer-sale",
        "group_id": "018e1b2c-0000-7f8a-9b0c-1d2e3f4a5b6c",
    },
)

if resp.status_code == 201:
    link = resp.json()
    print(link["short_url"])  # https://hozip.link/summer-sale
elif resp.status_code == 400:
    error = resp.json()
    print(error["error_code"], error["detail"])
Documentation