---
title: "Create or update a link"
method: POST
path: "/api/v1/workspace/{workspace_id}/links"
tags: ["Links"]
---

# Create or update a link

`POST /api/v1/workspace/{workspace_id}/links`

## Request

- Base URL: `https://api.linklyhq.com`
- URL: `https://api.linklyhq.com/api/v1/workspace/{workspace_id}/links`
- Auth: API key in query parameter `api_key`
- TypeScript: <https://skmtc.dev/linklyhq/apis/linkly-url-shortener-api/docs/api/v1/workspace/:workspace_id/links/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new link or update an existing one. Include an 'id' field to update an existing link. Can also accept an array of links for batch operations.

## Path parameters

- `workspace_id` string, required

## Request body

- object: Request body for creating or updating a link
  - `fb_pixel_id` string, nullable: Facebook Pixel ID
  - `tiktok_pixel_id` string, nullable: TikTok Pixel ID
  - `hide_referrer` boolean: Hide referrer from destination
  - `expiry_datetime` string, date-time, nullable: Link expiration date/time
  - `expiry_destination` string, nullable: Redirect URL after expiry
  - `rules` Rule[]: Redirect rules
    - `matches` string, nullable
    - `percentage` integer, nullable
    - `url` string, nullable
    - `what` string, nullable
  - `domain_id` integer: Domain ID (alternative to domain name)
  - `cloaking` boolean: Enable link cloaking
  - `linkify_words` string, nullable: Words to linkify
  - `sticky_rotator` boolean: Rotator links only: send a returning visitor to the same destination as last time, remembered in a cookie for 30 days. Not available on privacy-mode links; turning privacy mode on switches it off.
  - `og_description` string, nullable: Open Graph description
  - `skip_social_crawler_tracking` boolean: Skip tracking social media crawlers
  - `body_tags` string, nullable: Custom HTML tags for body
  - `og_title` string, nullable: Open Graph title
  - `note` string, nullable: Private note about this link
  - `name` string, nullable: Nickname for the link
  - `id` integer: Link ID (include to update existing link)
  - `gtm_id` string, nullable: Google Tag Manager ID
  - `og_image` string, nullable: Open Graph image URL
  - `block_bots` boolean: Block bot traffic
  - `utm_content` string, nullable
  - `enabled` boolean: Whether the link is active
  - `privacy_mode` boolean: Record clicks without personal data (no IP, location, network, user agent, referrer or query parameters; click times kept to the hour). Turning it on also clears tracking pixels, custom scripts, conversion tracking, webhooks and click notifications on the link, and click webhooks stop firing for it. Paid plans only.
  - `url` string, uri, required: The destination URL
  - `replacements` string, nullable: URL parameter replacements
  - `qr_styles` object, nullable: QR code styling options
  - `webhooks` string[]: Webhook URLs
  - `expiry_clicks` integer, nullable: Expire link after this many clicks
  - `public_analytics` boolean: Make analytics publicly accessible
  - `utm_source` string, nullable
  - `slug` string, nullable: Custom slug (must start with /)
  - `domain` string, nullable: Custom domain (without trailing /)
  - `forward_params` boolean: Forward query parameters to destination
  - `utm_medium` string, nullable
  - `head_tags` string, nullable: Custom HTML tags for head
  - `ga4_tag_id` string, nullable: Google Analytics 4 Tag ID
  - `utm_term` string, nullable
  - `utm_campaign` string, nullable

## Response `200`

Link

- object: A link with click statistics, as returned by workspace link endpoints.
  - `fb_pixel_id` string, nullable
  - `human_clicks_total` integer: Lifetime clicks with no bot signal — the subset of `clicks_total` where neither a bot user-agent nor a verified-bot category was detected. Recorded from 2019 onward.
  - `sparkline` integer[]: Daily human clicks over the last 30 days, oldest first.
  - `clicks_thirty_days` integer: Clicks in the last 30 days, including bot traffic.
  - `tiktok_pixel_id` string, nullable
  - `hide_referrer` boolean, nullable
  - `rules` Rule[], nullable
    - `matches` string, nullable
    - `percentage` integer, nullable
    - `url` string, nullable
    - `what` string, nullable
  - `cloaking` boolean, nullable
  - `linkify_words` string, nullable
  - `full_url` string, uri
  - `clicks_today` integer: Clicks so far today (UTC), including bot traffic.
  - `og_description` string, nullable
  - `body_tags` string, nullable
  - `og_title` string, nullable
  - `note` string, nullable
  - `name` string, nullable
  - `id` integer, nullable
  - `gtm_id` string, nullable
  - `og_image` string, nullable
  - `block_bots` boolean, nullable
  - `clicks_total` integer: Lifetime clicks, including bot traffic.
  - `human_clicks_thirty_days` integer: Clicks in the last 30 days with no bot signal — the subset of `clicks_thirty_days`.
  - `utm_content` string, nullable
  - `human_clicks_today` integer: Clicks so far today (UTC) with no bot signal.
  - `enabled` boolean, nullable
  - `url` string, uri
  - `replacements` string, nullable
  - `deleted` boolean, nullable
  - `workspace_id` integer, nullable
  - `public_analytics` boolean, nullable
  - `utm_source` string, nullable
  - `slug` string, nullable
  - `domain` string, nullable
  - `forward_params` boolean, nullable
  - `utm_medium` string, nullable
  - `head_tags` string, nullable
  - `ga4_tag_id` string, nullable
  - `utm_term` string, nullable
  - `utm_campaign` string, nullable
  - `human_clicks_previous_day` integer: Clicks yesterday (UTC) with no bot signal.

## Other responses

- `403`: Forbidden
- `422`: Error

## Changes

- **2026-10-22** `968598ef7055`: 3 info
  - added the new optional request property `sticky_rotator` (media type: application/json)
  - added the new optional request property `sticky_rotator` (media type: application/x-www-form-urlencoded)
  - added the new optional request property `sticky_rotator` (media type: multipart/form-data)
- **2026-10-09** `0370e4bf1074`: 3 info
  - added the new optional request property `privacy_mode` (media type: application/json)
  - added the new optional request property `privacy_mode` (media type: application/x-www-form-urlencoded)
  - added the new optional request property `privacy_mode` (media type: multipart/form-data)

[Operation history](https://skmtc.dev/linklyhq/apis/linkly-url-shortener-api/changes/api/v1/workspace/:workspace_id/links/post.md)

---

[API](https://skmtc.dev/linklyhq/apis/linkly-url-shortener-api.md) - [All operations](https://skmtc.dev/linklyhq/apis/linkly-url-shortener-api/llms.txt) - [OpenAPI document](https://skmtc.dev/linklyhq/apis/linkly-url-shortener-api/revisions/968598ef7055?raw)