---
agentTools:
  projectIndex: https://urlhum.readme.io/llms.txt
---

# Create new Short URL

This endpoint allows to create a new Short URL.

**Endpoint**: /url
**Method**: POST

[block:api-header]
{
  "title": "Parameters"
}
[/block]

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Required",
    "h-2": "Default",
    "0-0": "url",
    "h-3": "Description",
    "0-3": "The URL to shorten.",
    "0-1": "yes",
    "1-0": "custom_url",
    "1-1": "no",
    "1-2": "Generated by UrlHum",
    "0-2": "-",
    "1-3": "The shortened URL.",
    "2-0": "is_private",
    "2-1": "no",
    "2-2": "no",
    "2-3": "If the URL must not be listed in the public URLs page.",
    "3-0": "hide_stats",
    "3-1": "no",
    "3-2": "no",
    "3-3": "If the URL statistics must be hidden to users who aren't owner of the URL.",
    "h-4": "Type",
    "2-4": "int (0/1)",
    "3-4": "int (0/1)",
    "1-4": "string",
    "0-4": "string"
  },
  "cols": 5,
  "rows": 4
}
[/block]

[block:api-header]
{
  "title": "Successful response"
}
[/block]

In case of success, you receive a **200** status code and the following JSON example response:

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"message\": \"Success! Short URL created.\",\n  \"short_url\": \"WOz1\"\n}",
      "language": "json"
    }
  ]
}
[/block]

If the long URL already exists, you will receive a response like this:

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"message\": \"The Short URL for this destination already exists.\",\n  \"short_url\": \"WOz1\",\n  \"long_url\": \"https:\\/\\/urlhum.com\"\n}",
      "language": "json"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Errors"
}
[/block]

In case of handled errors (not 500), you can receive a 409 error if there are problems (listed below) or 403 if you don't have permissions to create the Short URL.

[block:parameters]
{
  "data": {
    "h-0": "Message",
    "0-0": "Url parameter cannot be blank or null",
    "h-1": "Reason",
    "0-1": "You didn't include the required **url** parameter in the request, it is blank or null.",
    "1-0": "This short URL already exists.",
    "1-1": "You included the parmeter **custom_url**, but such custom url already exists on UrlHum. Choose another custom url."
  },
  "cols": 2,
  "rows": 2
}
[/block]