---
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`

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
  - `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
  - `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

---

[API](https://skmtc.net/linklyhq/apis/linkly-url-shortener-api.md) · [All operations](https://skmtc.net/linklyhq/apis/linkly-url-shortener-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/linklyhq/linkly-url-shortener-api/revisions/351c1f004617/schema)