Shorten URLs

POST /urls

Input params:

{
"urls": [
	{
		"custom_hash": "mytiny",
		"long_url": "http://example.com",
		"note": "lots of notes...",
		"email_stats": false,
		"expiration_date": "2016-01-02",
		"tags":["group1"]
		}
	]
}

All fields are optional except "long_url". Default values:

"custom_hash" - autogenerated
"note" - ""
"email_stats" - false
"ping" - false
"protected" - false
"archived" - false
"expiration_date" - null
"max_clicks" - 0
"tags" - []
"favorite" - false
"no_stats" - true

Maximum length of "long_url" limited to 2048. Maximum length of "custom_hash" limited to 25. Maximum length of "note" is 255 characters.

Example of successful response:

{
  "error": {
    "code": 0,
    "message": ""
  },
  "urls": [
    {
		"hash": "mytiny",
		"long_url": "http://example.com",
		"short_url": "johndoe.com/mytiny",
		"short_url_with_protocol": "http://johndoe.com/mytiny",
		"total_clicks": 0,
		"unique_clicks": 0,
		"note": "lots of notes...",
		"email_stats": false,
		"expiration_date": "2016-01-02",
		"max_clicks": 0,
		"tags":["group1"],
		"links":{
			"qr_small": ...,
			"qr_big": ...
		},
		"error": {
			"code": 0,
			"message": "",
			"details": ""
		}
    }
  ]
}

Example of shortening errors:

{
  "error": {
    "code": 0,
    "message": ""
  },
  "urls": [
    {
		"long_url": "http://google.com",
		"custom_hash": "h",
		"error": {
			"code": 1215,
			"message": "Short URL is not correct or existed.",
			"details": "That Custom hash is already in use"
		}
    }
  ]
}

In both cases (successful shortening or shortening errors) HTTP status code - 200 OK and top-level "error" block indicates no errors.

But inside "urls" array, some URLs may have individual error message. In above example, one URL was successfully shortened. And other URL was not shortened.

Normally our system allows creation of multiple different short links containing exactly the same long or destination URL. But it is also possible to avoid making any new, unique short hashes if the long url had been previously submitted.
When your API call doesn't specify a custom_hash it is possible to avoid duplication of long URLs by passing the optional parameter "disable_long_url_duplicates":

POST /urls?disable_long_url_duplicates=account

In this case, new records won't be created for existing long URLs. Records from previously created links will be returned instead.

If you specify custom_hash together with "disable_long_url_duplicates" parameter, three scenarios are possible:

If custom_hash does not exist, new record will be created
If custom_hash exists with same long URL, existing records will be returned
If custom_hash exists with different long URL, error 1215 will be indicated

If you are using several domains for shortening, you may check for existing long URL only in your working domain controlled by "domain" parameter. To do so, use disable_long_url_duplicates=domain. Otherwise, check will be performed among all domains in your account.