URL Shortener API Documentation

Overview

This API allows you to create, retrieve, delete, and list shortened URLs. Certain operations require authentication via an API token.

Base URL

All API endpoints are relative to the following base URL:

https://taila.cz/s

Authentication

Endpoints that modify data (create, delete) or list all data require an authentication token.

Pass your token in the X-Auth-Token HTTP header with each authenticated request.

X-Auth-Token: YOUR_SECRET_TOKEN

Important: Keep your token secure and do not expose it publicly. Replace YOUR_SECRET_TOKEN with your actual token when making requests.

Requests without a valid token to protected endpoints will receive a 403 Forbidden response.

Endpoints

Create a Shortened URL

POST /shorten

Creates a shortened URL for a given long URL. You may optionally provide a custom alias. If no custom alias is provided, a random one is generated. If a provided custom alias already exists, the API returns a 400 error.

Authentication Required: Yes

Request Headers

Content-Type: application/json
X-Auth-Token: YOUR_SECRET_TOKEN

Request Body

A JSON object containing the URL to shorten and an optional custom alias:

{
  "url": "https://example.com/this-is-a-very-long-url-that-needs-shortening",
  "custom_short_url": "my-custom-link"
}

url (string, required): The original long URL.
custom_short_url (string, optional): A desired alias. If omitted, a random alias is generated.

Responses

201 Created: Success. The response body contains the full short URL.
```
{
  "short_url": "https://taila.cz/s/my-custom-link"
}
```
400 Bad Request: Missing url in the request body, or the requested custom_short_url already exists.
403 Forbidden: Authentication token is missing or invalid.
500 Internal Server Error: An unexpected error occurred on the server (e.g., database issue).

Example (cURL)

curl -X POST https://taila.cz/s/shorten \
     -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_SECRET_TOKEN" \
     -d '{
       "url": "https://github.com/your-username/your-repo",
       "custom_short_url": "gh-repo"
     }'

Redirect to Long URL

GET /<short_alias>

Redirects the client (e.g., browser) to the original long URL associated with the provided short_alias.

Authentication Required: No

Parameters

short_alias (string, required): The short identifier (e.g., my-custom-link or aB3dEf) in the URL path.

Responses

302 Found: Success. Redirects to the long URL via the Location header.
404 Not Found: The provided short_alias does not exist in the database.

Example (Browser)

Simply navigate to:

https://taila.cz/s/my-custom-link

Delete a Shortened URL

DELETE /delete/<short_alias>

Deletes the shortened URL record identified by the short_alias.

Authentication Required: Yes

Parameters

short_alias (string, required): The short identifier to delete.

Request Headers

X-Auth-Token: YOUR_SECRET_TOKEN

Responses

200 OK: Success. The response body confirms deletion.

{
  "message": "Short URL my-custom-link deleted successfully"
}

403 Forbidden: Authentication token is missing or invalid.
404 Not Found: The provided short_alias does not exist.

Example (cURL)

curl -X DELETE https://taila.cz/s/delete/my-custom-link \
     -H "X-Auth-Token: YOUR_SECRET_TOKEN"

List All Shortened URLs

GET /list

Retrieves a list of all currently stored short URL mappings.

Authentication Required: Yes

Request Headers

X-Auth-Token: YOUR_SECRET_TOKEN

Responses

200 OK: Success. Returns a JSON array of URL mapping objects.

[
  {
    "short": "gh-repo",
    "short_full": "https://taila.cz/s/gh-repo",
    "long": "https://github.com/your-username/your-repo"
  },
  {
    "short": "aB3dEf",
    "short_full": "https://taila.cz/s/aB3dEf",
    "long": "https://another-example.com/some/path"
  }
  // ... more entries
]

short: The short alias part of the URL.
short_full: The complete, clickable short URL.
long: The original long URL.

403 Forbidden: Authentication token is missing or invalid.

Example (cURL)

curl -X GET https://taila.cz/s/list \
     -H "X-Auth-Token: YOUR_SECRET_TOKEN"