Links

Short links are the core object of the API. A link points a slug on one of your domains at a destination URL, and can carry UTM parameters, tags, an expiry date, and retargeting pixels.

The link object

{
  "id": "9b1f4e2a-6c3d-4a17-9f2e-7c8d5a1b3e40",
  "title": "Summer Sale",
  "destination_url": "https://example.com/summer-sale?utm_source=newsletter",
  "short_url": "go.acme.com/summer",
  "slug": "summer",
  "hostname": "go.acme.com",
  "utm_params": { "utm_source": "newsletter" },
  "tags": ["q3", "email"],
  "expires_at": "2026-12-31T00:00:00.000000Z",
  "pixel_ids": ["3f9c8a71-2b4d-4e60-8a15-9d7c6b3e21f8"],
  "clicks": 128,
  "status": true,
  "created_at": "2026-08-28T10:14:02.000000Z",
  "updated_at": "2026-08-28T11:02:44.000000Z"
}

List links

GET /v1/links

Scope: links:read

Returns your links, newest first, in the standard paginated shape.

curl "https://app.linksqueeze.io/api/v1/links?per_page=50" \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Create a link

POST /v1/links

Scope: links:write

Returns 201 Created with the link object.

curl -X POST https://app.linksqueeze.io/api/v1/links \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "destination_url": "https://example.com/summer-sale",
    "slug": "summer",
    "hostname": "go.acme.com",
    "utm_params": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "summer-2026"
    },
    "tags": ["q3", "email"],
    "expires_at": "2026-12-31T00:00:00Z",
    "pixel_ids": ["3f9c8a71-2b4d-4e60-8a15-9d7c6b3e21f8"]
  }'

How domains are referenced

Links reference a domain by its hostname, not by its domain UUID, so you can create a link on go.acme.com without first looking up the domain’s id.

The hostname must be a domain registered to your account. One that is not — including a domain owned by another account — is rejected with 422:

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "errors": {
      "hostname": ["This hostname is not registered to your account."]
    }
  }
}

Omit hostname (or send null) to put the link on the shared Link Squeeze short domain. In that case hostname comes back as null in the response, and short_url shows the shared domain.

How UTM parameters are applied

UTM parameters are baked into the destination URL at write time. Creating a link with destination_url of https://example.com/product and utm_source of newsletter returns:

{
  "destination_url": "https://example.com/product/?utm_source=newsletter",
  "utm_params": { "utm_source": "newsletter" }
}

The utm_params object is also stored separately so you can read back what was applied, but there is no separate “clean” URL — destination_url is always the final URL a visitor lands on. This has consequences when updating a link, described below.

Retrieve a link

GET /v1/links/{id}

Scope: links:read

curl https://app.linksqueeze.io/api/v1/links/9b1f4e2a-6c3d-4a17-9f2e-7c8d5a1b3e40 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

A link belonging to another account returns 404 not_found, the same as a link that does not exist — the API does not disclose that an id exists on someone else’s account.

Update a link

PATCH /v1/links/{id}

Scope: links:write

Every field is optional. Fields you do not send are left untouched.

curl -X PATCH https://app.linksqueeze.io/api/v1/links/9b1f4e2a-6c3d-4a17-9f2e-7c8d5a1b3e40 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "tags": ["rebrand"] }'

Returns 200 OK with the updated link object.

Array fields are replaced, not merged

tags, pixel_ids, and utm_params are replaced wholesale by the value you send. To add one tag to a link that already has two, send all three.

Fields you omit entirely are preserved. Changing destination_url without mentioning pixel_ids, for example, keeps the link’s existing pixels attached.

Clearing a hostname

Send "hostname": null to move a link off a custom domain and back onto the shared Link Squeeze domain. The response returns hostname as null and short_url rewritten to the shared domain.

Delete a link

DELETE /v1/links/{id}

Scope: links:write

Returns 204 No Content with an empty body.

curl -X DELETE https://app.linksqueeze.io/api/v1/links/9b1f4e2a-6c3d-4a17-9f2e-7c8d5a1b3e40 \
  -H "Authorization: Bearer $LINKSQUEEZE_API_KEY" \
  -H "Accept: application/json"

Events

Creating a link through the API fires the link.created webhook event, exactly once, with the complete link record. See Webhooks.