Links (v1)

API reference for the Links objects. Use this endpoints to create, edit and get details about your short links. For analytics, use the Analytics endpoints.
https://api.returnam.com/v1/links
Creates a short link with an optional custom slug. When creating a link, the long URL is verified against blacklists. If your link matches with a blacklist, it will be disabled and won't be usable again. If you believe it was blacklisted by mistake, please contact help@returnam.com.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key.
x-rtrn-secret
required
string
API Secret.
Body Parameters
domain
optional
string
Pick a domain for the short link. Must be one of our available domains: ["rtrn.am", "rtrn.io", "rtrn.link", "rtrn.xyz"]. Defaults to: "rtrn.am".
custom_slug
optional
string
Custom slug (ex. https://rtrn.am/<this-is-the-custom-slug>). String with URL safe characters (A-Z, a-z, 0-9, -, _). Between 5 and 22 characters long.
url
required
string
URL to shorten. Must include http or https. Max length: 1024 characters.
Response
201: Created
Returns an object with the unique slug of the created link and the full short URL.
{
"short_url": "https://rtrn.io/FJUOOyYdi",
"slug": "FJUOOyYdi"
}
400: Bad Request
Example error response
{
"name": "InvalidContentError",
"message": "Not a valid URL",
"code": 400
}
https://api.returnam.com/v1/links
List all created links. Results are paginated, see the query parameters to override the defaults.
Request
Response
Request
Headers
x-rtrn-key
required
string
API Key.
x-rtrn-secret
required
string
API Secret.
Query Parameters
results
optional
string
Number of results per page. Min: 1, max: 50. Defaults to 20.
order
optional
string
Order of the results. Allowed: 'asc', 'desc'. Defaults to 'desc'.
last_index
optional
string
Used for pagination. Key of the last item in the existing results array to get the next results after that key.
Response
200: OK
Returns an array of objects with information about your links.
[
{
"status": 1,
"url": "https://rtrn.io",
"slug": "6gen8a3uCr",
"created": "2019-08-30T00:28:56.000Z",
"updated": "2019-08-30T00:28:56.000Z"
},
{
"status": 1,
"url": "https://docs.rtrn.io",
"slug": "puGYAXvvFv",
"created": "2019-08-30T00:28:50.000Z",
"updated": "2019-08-30T00:28:50.000Z"
}
]
400: Bad Request
Example error response
{
"name": "InvalidContentError",
"message": "Parameter <order> must be a string with one of these values: [asc, desc]",
"code": 400
}
https://api.returnam.com/v1/links/<slug>
Gets details about a link. It includes a status code and blacklist information. If status code is 0 or less, link is deactivated. If status code is -10, link was blacklisted. You can find blacklist reason in field blacklist_status.
Request
Response
Request
Path Parameters
slug
required
string
Link slug.
Response
200: OK
Returns an object with information about the queried link. If status is 0 or less, the link is deactivated. A status of -10 means it was blacklisted. Field blacklist_status shows the reason of the blacklist.
{
"status": 1,
"url": "https://docs.rtrn.io",
"slug": "5U6k_GDbVy",
"short_url": "https://rtrn.io/5U6k_GDbVy",
"created": "2019-08-28T22:52:33.000Z",
"updated": "2019-08-28T22:52:33.000Z",
"blacklist_status": "cleared"
}
404: Not Found
Example error response
{
"name": "ResourceNotFoundError",
"message": "Link <5U6k_GDbV> not found",
"code": 404
}
https://api.returnam.com/v1/links/<slug>
Updates the destination URL for a short link you created. The new URL will be verified against blacklists.
Request
Response
Request
Path Parameters
slug
required
string
Link slug.
Headers
x-rtrn-key
required
string
API Key.
x-rtrn-secret
required
string
API Secret.
Body Parameters
url
required
string
New destination URL for the short link.
Response
200: OK
Returns an object with the slug and the full URL of the short link.
{
"short_url": "https://rtrn.io/FJUOOyYdi",
"slug": "FJUOOyYdi"
}
400: Bad Request
Example error response
{
"name": "InvalidContentError",
"message": "Not a valid URL",
"code": 400
}
https://api.returnam.com/v1/links/<slug>
Deletes a link. This will also delete all tracking information about hits (visits). This action is permanent.
Request
Response
Request
Path Parameters
slug
required
string
Link slug.
Headers
x-rtrn-key
required
string
API Key.
x-rtrn-secret
required
string
API Secret.
Response
200: OK
Field deleted_hits shows how many hits (visits) were deleted with the link.
{
"deleted_hits": 108,
"deleted_slug": "5U6k_GDbVy"
}
404: Not Found
Example error response
{
"name": "ResourceNotFoundError",
"message": "Link <5U6k_GDbVy> not found",
"code": 404
}