Create Link

Create a new short link.


POST /api/v1/links

Authentication

Required. Pass your API key as a Bearer token.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The destination URL (must be a valid `http://` or `https://` URL)
`custom_alias`	string	No	Custom short code (3-50 chars, alphanumeric + hyphens)
`title`	string	No	Display title for the link. If omitted, auto-fetched from the URL
`password`	string	No	Password to protect the link
`expires_at`	string	No	ISO 8601 datetime when the link should expire

Custom Alias Rules

Must be 3-50 characters long
Only letters, numbers, and hyphens allowed
Cannot start or end with a hyphen
Cannot be a reserved word (e.g., api, dashboard, admin)
Must be unique across all Snip URL links

Response

Returns the created link object with a 201 Created status.

Link Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`short_code`	string	The short code (custom alias or auto-generated)
`short_url`	string	Full short URL (e.g., `https://snipurl.click/abc123`)
`original_url`	string	The destination URL
`title`	string	Display title
`is_active`	boolean	Whether the link is active
`has_password`	boolean	Whether a password is set
`expires_at`	string \| null	Expiration datetime (ISO 8601)
`clicks_count`	number	Total click count
`analytics_public`	boolean	Whether analytics are publicly visible
`created_at`	string	Creation datetime (ISO 8601)
`updated_at`	string	Last update datetime (ISO 8601)

Examples

Basic Link


curl -X POST https://snipurl.click/api/v1/links \
  -H "Authorization: Bearer snip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/my-awesome-article"
  }'


const response = await fetch('https://snipurl.click/api/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer snip_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/blog/my-awesome-article',
  }),
});
 
const { data } = await response.json();
console.log(data.short_url); // https://snipurl.click/a8Kx2m


import requests
 
response = requests.post(
    'https://snipurl.click/api/v1/links',
    headers={'Authorization': 'Bearer snip_live_your_key_here'},
    json={'url': 'https://example.com/blog/my-awesome-article'},
)
 
data = response.json()['data']
print(data['short_url'])  # https://snipurl.click/a8Kx2m

Response (201 Created):


{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "short_code": "a8Kx2m",
    "short_url": "https://snipurl.click/a8Kx2m",
    "original_url": "https://example.com/blog/my-awesome-article",
    "title": "My Awesome Article - Example Blog",
    "is_active": true,
    "has_password": false,
    "expires_at": null,
    "clicks_count": 0,
    "analytics_public": false,
    "created_at": "2025-06-24T10:00:00.000Z",
    "updated_at": "2025-06-24T10:00:00.000Z"
  }
}

Custom Alias with Password and Expiry


curl -X POST https://snipurl.click/api/v1/links \
  -H "Authorization: Bearer snip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.google.com/document/d/secret-doc",
    "custom_alias": "team-doc",
    "title": "Q3 Planning Document",
    "password": "team2025",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response (201 Created):


{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "short_code": "team-doc",
    "short_url": "https://snipurl.click/team-doc",
    "original_url": "https://docs.google.com/document/d/secret-doc",
    "title": "Q3 Planning Document",
    "is_active": true,
    "has_password": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "clicks_count": 0,
    "analytics_public": false,
    "created_at": "2025-06-24T10:00:00.000Z",
    "updated_at": "2025-06-24T10:00:00.000Z"
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid URL or request body
403	`FORBIDDEN`	Link limit reached
409	`CONFLICT`	Custom alias already taken

Alias Taken Example


{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "This custom alias is already taken."
  }
}

Link Limit Reached


{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Link limit reached (500). Delete existing links or upgrade your plan."
  }
}