Skip to main content

​
Overview

The URLEntry model is used when creating a new short URL via the API. It defines the required and optional fields for URL creation, including the short code, optional password protection, and the destination URL.

​
When to Use

This model is used in:
  • POST /create - Create a new short URL

​
Schema Definition

​
url_code
string
required
The custom short code for the URL. This will be used in the shortened URL path.Validation Rules:
  • Must be 3-20 characters long
  • Only alphanumeric characters, dashes (-), and underscores (_) allowed
  • Cannot be a reserved keyword (docs, redoc, create, login, delete, pause, resume, details, refresh_token, change_password, reset_hits, change_url, validate_token, health)
  • Case-insensitive validation
Choose a memorable code that’s easy to share and type
​
url_pass
string
default:""
Optional password to protect the short URL. When set, users must provide this password to access the destination URL.Validation Rules:
  • Either empty (no password) or 3-20 characters long
  • If set, must be at least 3 characters
Default: Empty string (no password protection)
Password protection adds an extra layer of security for sensitive links
​
url
string
required
The destination URL where users will be redirected. The API automatically formats this field.Automatic Formatting:
  • Leading/trailing whitespace is trimmed
  • If the URL doesn’t start with http:// or https://, the API automatically prepends https://
Ensure the destination URL is valid and accessible before creating the short URL

​
Example JSON

{
  "url_code": "my-link",
  "url_pass": "secret123",
  "url": "https://example.com/very/long/path/to/resource"
}
In the minimal example, url_pass defaults to an empty string (no password), and the url will be automatically formatted to https://example.com

​
Validation Examples

  • my-link (valid)
  • blog_2024 (valid)
  • API-v2 (valid)
  • short123 (valid)
  • ab (too short - minimum 3 characters)
  • this-is-a-very-long-code-name (too long - maximum 20 characters)
  • create (reserved keyword)
  • my link (contains space)
  • link@home (contains invalid character @)
  • Empty string "" - Valid (no password)
  • "abc" - Valid (exactly 3 characters)
  • "my-secure-password" - Valid (within range)
  • "ab" - Invalid (less than 3 characters when not empty)
  • "this-password-is-way-too-long" - Invalid (exceeds 20 characters)

Build docs developers (and LLMs) love

Get started for freeTalk to us