---
title: "Create or update a link"
method: POST
path: "/api/v1/link"
tags: ["Links"]
---

# Create or update a link

`POST /api/v1/link`

Create a new shortened link or update an existing one. To create: provide `url` and `workspace_id`. To update: provide `id` and any fields to change. Supports custom slugs, UTM parameters, retargeting pixels, Open Graph metadata, and redirect rules.

## Request body

- object — POST body for creating or updating an link
  - `block_bots` boolean — block_bots
  - `body_tags` string — body_tags
  - `cloaking` boolean — cloaking
  - `deleted` boolean — deleted
  - `domain` string — domain
  - `enabled` boolean — enabled
  - `fb_pixel_id` string — fb_pixel_id
  - `forward_params` boolean — forward_params
  - `ga4_tag_id` string — ga4_tag_id
  - `gtm_id` string — gtm_id
  - `head_tags` string — head_tags
  - `hide_referrer` boolean — hide_referrer
  - `id` integer — Link ID. Required to update an existing link
  - `linkify_words` string — linkify_words
  - `name` string — name
  - `note` string — note
  - `og_description` string — og_description
  - `og_image` string — og_image
  - `og_title` string — og_title
  - `replacements` string — replacements
  - `rules` object[]
    - `matches` string
    - `percentage` string
    - `rule_url` string
    - `url` string
    - `what` string
  - `slug` string — slug
  - `spam` boolean — spam
  - `tiktok_pixel_id` string — tiktok_pixel_id
  - `url` string, uri — URL. Required to create a new link.
  - `utm_campaign` string — utm_campaign
  - `utm_content` string — utm_content
  - `utm_medium` string — utm_medium
  - `utm_source` string — utm_source
  - `utm_term` string — utm_term
  - `workspace_id` integer — Workspace ID

## Response `200`

Link

- Link — Response schema for a link
  - `fb_pixel_id` string, nullable
  - `linkedin_partner_id` string, nullable
  - `microsoft_uet_tag_id` string, nullable
  - `reddit_pixel_id` string, nullable
  - `tiktok_pixel_id` string, nullable
  - `hide_referrer` boolean, nullable
  - `expiry_datetime` string, nullable
  - `expiry_destination` string, uri, nullable
  - `rules` Rule[], nullable
    - `matches` string, nullable
    - `percentage` integer, nullable
    - `url` string, nullable
    - `what` string, nullable
  - `twitter_pixel_id` string, nullable
  - `cloaking` boolean, nullable
  - `linkify_words` string, nullable
  - `full_url` string, uri
  - `og_description` string, nullable
  - `skip_social_crawler_tracking` boolean, 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
  - `snapchat_pixel_id` string, nullable
  - `utm_content` string, nullable
  - `enabled` boolean, nullable
  - `url` string, uri
  - `replacements` string, nullable
  - `deleted` boolean, nullable
  - `qr_styles` object, nullable
  - `webhooks` string[], nullable
  - `created_by_user_id` integer, nullable
  - `expiry_clicks` integer, nullable
  - `notify_slack` boolean, nullable
  - `notify_user_ids` integer[], nullable
  - `workspace_id` integer, nullable
  - `public_analytics` boolean, nullable
  - `pinterest_tag_id` string, nullable
  - `password` string, 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

## Other responses

- `400` — Error
- `403` — Forbidden
- `404` — Not Found

---

[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)