Skip to main content
Create a new short link for URL shortening with integrated analytics tracking.

​
Endpoint

POST /api/links

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Request Body

​
name
string
required
Link name (max 100 characters)
​
url
string
required
Destination URL (max 500 characters)
​
slug
string
required
Unique URL slug (max 100 characters). Must be unique across all links.
​
teamId
string
Team UUID if creating a team link. Omit for personal link.
​
id
string
Optional custom UUID for the link. Generated automatically if not provided.

​
Response

​
id
string
Link UUID
​
name
string
Link name
​
url
string
Destination URL
​
slug
string
URL slug
​
userId
string
Owner user UUID (null for team links)
​
teamId
string
Team UUID (null for personal links)
​
createdAt
string
ISO 8601 timestamp of creation

​
Example Request

curl -X POST "https://your-umami-instance.com/api/links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch",
    "url": "https://example.com/product-launch",
    "slug": "launch2024"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Product Launch",
  "url": "https://example.com/product-launch",
  "slug": "launch2024",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "teamId": null,
  "createdAt": "2024-03-15T09:20:00.000Z"
}
To create a link owned by a team, include the teamId parameter:
curl
curl -X POST "https://your-umami-instance.com/api/links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Campaign",
    "url": "https://example.com/campaign",
    "slug": "campaign-q1",
    "teamId": "880e8400-e29b-41d4-a716-446655440003"
  }'
You must have permission to create websites for the team. The slug must be unique across all links in the system.

Build docs developers (and LLMs) love

Get started for freeTalk to us