Links API

Create a link

POST /v1/links

Create a trackable short link with an optional deep link payload.

Request body

{
  "deepLinkPath": "/product/123",
  "deepLinkParams": {"color": "blue"},
  "campaignId": "summer_sale",
  "fallbackUrl": "https://myapp.com/product/123",
  "metadata": {"created_by": "api"},
  "expiresInDays": 30,
  "sandbox": false
}

Field	Type	Required	Description
`deepLinkPath`	string	yes	Path delivered to the app (e.g. `/product/123`)
`deepLinkParams`	object	no	Key-value pairs delivered alongside the path
`campaignId`	string	no	Campaign identifier for attribution grouping
`fallbackUrl`	string	no	URL for users on unsupported platforms
`metadata`	object	no	Arbitrary key-value metadata stored with the link
`expiresInDays`	int	no	Link expires after this many days
`sandbox`	boolean	no	If `true`, only debug builds can claim clicks from this link

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shortCode": "abc123",
  "shortUrl": "https://yourapp.traceclick.io/l/abc123",
  "deepLinkPath": "/product/123",
  "deepLinkParams": {"color": "blue"},
  "campaignId": "summer_sale",
  "fallbackUrl": "https://myapp.com/product/123",
  "metadata": {"created_by": "api"},
  "sandbox": false,
  "expiresAt": "2024-08-15T00:00:00Z",
  "createdAt": "2024-07-15T12:00:00Z",
  "updatedAt": "2024-07-15T12:00:00Z"
}

trace links create --deep-link-path /invite/summer \
  --campaign-id summer_sale \
  --fallback-url https://myapp.com

# With metadata and expiration
trace links create --deep-link-path /product/123 \
  --campaign-id summer_sale \
  --metadata color=blue \
  --metadata source=email \
  --expires-in-days 30

# Get full JSON response
trace links create --deep-link-path /invite/summer --json

curl -X POST https://api.traceclick.io/v1/links \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "deepLinkPath": "/invite/summer",
    "campaignId": "summer_sale",
    "fallbackUrl": "https://myapp.com"
  }'

List links

GET /v1/links

List all links for your app. Supports pagination and campaign filtering.

Query parameters

Parameter	Type	Default	Description
`campaignId`	string	—	Filter by campaign ID
`sandbox`	boolean	—	Filter by sandbox status
`limit`	int	50	Max results (1-100)
`offset`	int	0	Pagination offset

Response

{
  "links": [
    {
      "id": "...",
      "shortCode": "abc123",
      "shortUrl": "https://yourapp.traceclick.io/l/abc123",
      "deepLinkPath": "/invite/summer",
      "campaignId": "summer_sale",
      "createdAt": "2024-07-15T12:00:00Z"
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 50
}

Example

CLI
curl

# List all links
trace links list

# Filter by campaign with pagination
trace links list --campaign-id summer_sale --limit 10

# Show only sandbox links
trace links list --sandbox

curl "https://api.traceclick.io/v1/links?campaignId=summer_sale&limit=10" \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

Get a link

GET /v1/links/{shortCode}

Retrieve details of a specific link by its short code.

Example

CLI
curl

trace links get abc123

# Full JSON output
trace links get abc123 --json

curl https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

Update a link

PATCH /v1/links/{shortCode}

Update any field on an existing link. Only include the fields you want to change.

Request body

{
  "deepLinkPath": "/product/456",
  "campaignId": "winter_sale",
  "expiresInDays": 60
}

All fields from the create request are accepted. The shortCode cannot be changed.

Example

CLI
curl

trace links update abc123 --fallback-url https://myapp.com/new

trace links update abc123 \
  --campaign-id winter_sale \
  --expires-in-days 90

curl -X PATCH https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"campaignId": "winter_sale"}'

Delete a link

DELETE /v1/links/{shortCode}

Soft-delete a link. The short code becomes inactive and stops redirecting.

Example

CLI
curl

trace links delete abc123

curl -X DELETE https://api.traceclick.io/v1/links/abc123 \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

QR code

GET /qr/{shortCode}

Returns a PNG image of a QR code that points to the link’s short URL. This is a public endpoint — no API key required.

Query parameters

Parameter	Type	Default	Description
`size`	int	6	Pixels per QR module (2–40). Higher = larger image

Example

# Download QR code (compact, ~150px)
curl https://yourapp.traceclick.io/qr/abc123 -o qr.png

# Larger for print (~500px)
curl "https://yourapp.traceclick.io/qr/abc123?size=20" -o qr-large.png

The QR code URL is also returned in the qrCodeUrl field when you create a link.