Create Link

Creates a new short link that redirects to the given destination URL. Optionally specify a custom slug, labels, routing rules, and an expiration date.

POST /v1/links

links:write

Request Body

Parameter	Type	Required	Description
url	string	Yes	Destination URL. Must be a valid HTTP or HTTPS URL.
custom_slug	string	No	Custom short code (3 – 64 characters, alphanumeric and hyphens). If omitted, a random 7-character code is generated.
labels	string[]	No	Array of labels for organizing links (max 10).
routing_rules	object[]	No	Conditional routing rules (e.g. geo-based redirects). See Smart Routing for schema details.
expires_at	string	No	ISO 8601 datetime after which the link returns 410 Gone.

Tip

Custom slugs are unique per workspace. If the slug is already taken, the API returns 409 Conflict.

Request Examples

curl

curl -X POST https://xqr.co/api/v1/links \
  -H "Authorization: Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/summer-sale?utm_source=qr",
    "custom_slug": "summer24",
    "labels": ["campaign", "summer"],
    "expires_at": "2026-09-30T23:59:59Z"
  }'

TypeScript

const response = await fetch("https://xqr.co/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/summer-sale?utm_source=qr",
    custom_slug: "summer24",
    labels: ["campaign", "summer"],
    expires_at: "2026-09-30T23:59:59Z",
  }),
});

const { data } = await response.json();
console.log(data.short_url); // https://xqr.co/summer24

Python

import httpx

response = httpx.post(
    "https://xqr.co/api/v1/links",
    headers={
        "Authorization": "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    },
    json={
        "url": "https://example.com/summer-sale?utm_source=qr",
        "custom_slug": "summer24",
        "labels": ["campaign", "summer"],
        "expires_at": "2026-09-30T23:59:59Z",
    },
)

data = response.json()["data"]
print(data["short_url"])  # https://xqr.co/summer24

Response

201 Created

{
  "data": {
    "id": "d47f2e1a-8c3b-4a5d-9e6f-1234567890ab",
    "short_url": "https://xqr.co/summer24",
    "short_code": "summer24",
    "destination": "https://example.com/summer-sale?utm_source=qr",
    "enabled": true,
    "labels": ["campaign", "summer"],
    "routing_rules": [],
    "scan_count": 0,
    "last_scan_at": null,
    "expires_at": "2026-09-30T23:59:59Z",
    "created_at": "2026-03-21T14:30:00Z",
    "updated_at": "2026-03-21T14:30:00Z"
  },
  "meta": {
    "request_id": "req_8f3a2b1c4d5e6f70",
    "rate_limit": {
      "limit": 600,
      "remaining": 599,
      "reset": 1742572800
    }
  }
}