---
title: "Create a governed short link"
method: POST
path: "/api/v1/links"
tags: ["links"]
---

# Create a governed short link

`POST /api/v1/links`

## Request

- Base URL: `https://app.utmkit.co`
- URL: `https://app.utmkit.co/api/v1/links`
- Auth: HTTP bearer

Requires a token with the `links:write` permission.

## Request body

- LinkInput
  - `android_url` string, nullable: optional Android destination (spec 047): an app link or a Play page, https only; phones on Android are routed here, blank clears it
  - `campaign_id` integer, nullable
  - `destination` string, uri, nullable
  - `domain` string: optional; a verified custom domain name, else the shared domain
  - `expires_at` string, date-time, nullable
  - `ios_url` string, nullable: optional iOS destination (spec 047): an app link or an App Store page, https only; phones on iOS are routed here, blank clears it
  - `note` string, nullable: free text kept on the link; blank clears it
  - `short_code` string: optional; random when omitted
  - `tags` string[]: tag names (spec 039): an existing tag of the workspace by name, case-insensitive, else a new one; on update the list replaces the link's tags and [] clears them
  - `utm_campaign` string
  - `utm_content` string
  - `utm_medium` string
  - `utm_source` string
  - `utm_term` string
  - `whatsapp_message` string, nullable: the prefilled message, plain text, never URL-encoded
  - `whatsapp_number` string, nullable: a WhatsApp click-to-chat link (issue #202): the phone in international format (+, spaces and dashes are stripped). Given INSTEAD of destination — the wa.me URL is composed and the message encoded once, server-side

## Response `201`

Link

- LinkWithWarning
  - `android_url` string, nullable
  - `campaign_id` integer, nullable
  - `created_at` string, date-time
  - `created_by` object
    - `api_token_id` integer, nullable
    - `user_id` integer
  - `destination` string
  - `expires_at` string, date-time, nullable
  - `id` integer
  - `ios_url` string, nullable
  - `note` string, nullable
  - `qr_url` string, uri: the short URL with the scan marker
  - `short_code` string
  - `short_url` string, uri
  - `state` 'live' | 'pending' | 'blocked' | 'expired'
  - `tags` object[]: the link's tags, by name without regard to case
    - `color` 'gray' | 'red' | 'orange' | 'amber' | 'green' | 'teal' | 'blue' | 'purple'
    - `name` string
  - `utm_campaign` string, nullable
  - `utm_content` string, nullable
  - `utm_medium` string, nullable
  - `utm_source` string, nullable
  - `utm_term` string, nullable
  - `warning` string, nullable: governance warning when the convention warns rather than blocks

## Other responses

- `409`: Error
- `422`: Error
- `429`: Error

---

[API](https://skmtc.dev/utmkit/apis/utmkit-api.md) · [All operations](https://skmtc.dev/utmkit/apis/utmkit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/utmkit/apis/utmkit-api/revisions/74266a7b244a?raw)