Skip to main content
POST
/
create
Create Short URL
curl --request POST \
  --url https://api.example.com/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "url_code": "<string>",
  "url": "<string>",
  "url_pass": "<string>"
}
'
{
  "message": "<string>",
  "short_url": "<string>"
}
Create a new short URL with an optional password for protection. This endpoint allows you to map a custom URL code to a destination URL.

​
Request Body

​
url_code
string
required
Custom short code for the URL. Must be 3-20 characters long, containing only alphanumeric characters, hyphens, and underscores.Reserved keywords that cannot be used: docs, redoc, create, login, delete, pause, resume, details, refresh_token, change_password, reset_hits, change_url, validate_token, health
​
url
string
required
The destination URL to redirect to. If the URL doesn’t start with http:// or https://, it will be automatically prefixed with https://.
​
url_pass
string
default:""
Optional password to protect the short URL. If provided, must be 3-20 characters long. When set, users must authenticate via /login to manage this URL.

​
Validation Rules

URL Code Validation:
  • Length: 3-20 characters
  • Allowed characters: A-Z, a-z, 0-9, _, -
  • Cannot match reserved keywords
Password Validation:
  • Optional (can be empty string)
  • If provided: 3-20 characters
URL Blacklist:
  • URLs containing blacklisted domains will be rejected

​
Response

​
message
string
Confirmation message indicating the URL was created
​
short_url
string
The complete short URL that can be shared (format: {SURL_BASE}/{url_code})

​
Status Codes

  • 201 Created - URL successfully created
  • 400 Bad Request - Invalid URL code, blacklisted URL, or invalid password length
  • 409 Conflict - URL code already exists

​
Request Example

curl -X POST https://api.example.com/create \
  -H "Content-Type: application/json" \
  -d '{
    "url_code": "my-link",
    "url": "https://example.com/very/long/url",
    "url_pass": "secret123"
  }'

​
Response Examples

{
  "message": "URL created",
  "short_url": "https://surl.example.com/my-link"
}

​
URL Formatting

The API automatically formats URLs:
  • Strips leading/trailing whitespace
  • Adds https:// prefix if the URL doesn’t start with http:// or https://
URL codes are unique across the system. Once created, a URL code cannot be reused even after deletion until it’s available again.

​
Background Process

When a URL is successfully created:
  1. The URL mapping is stored in the URLMap collection
  2. A statistics entry is created in URLStats with:
    • Initial hit count: 0
    • Creation timestamp
    • Active state: true

Build docs developers (and LLMs) love

Get started for freeTalk to us