URL Shortener API: JSON and Code Examples

1. Generate a key

Use the homepage to create your API key. Send it in the X-API-KEY request header.

2. Send your request

Use POST with Content-Type: application/json and a body containing the url field.

POST https://freetoolsweb.com/short-url/?api=create
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{"url": "https://example.com"}

3. Read the response

A successful response contains status and short_url. On failure, read the message field.

{"status": "success", "short_url": "https://gothis.link/Ab12"}

4. Integration example

Replace YOUR_API_KEY with your key. This minimal HTML + JavaScript example exposes the key to visitors. For a private integration, send requests from your own server and keep its credentials out of browser code.

<form id="short-url-form">
  <label for="long-url">Website URL</label>
  <input id="long-url" name="url" type="url" placeholder="https://example.com" required>
  <button type="submit">Shorten</button>
</form>
<div id="result" role="status"></div>

<script>
document.getElementById("short-url-form").addEventListener("submit", async function(event) {
  event.preventDefault();
  const button = this.querySelector("button");
  const result = document.getElementById("result");
  button.disabled = true; result.textContent = "Processing...";
  try {
    const response = await fetch("https://freetoolsweb.com/short-url/?api=create", {
      method: "POST",
      headers: {"Content-Type": "application/json", "X-API-KEY": "YOUR_API_KEY"},
      body: JSON.stringify({url: document.getElementById("long-url").value.trim()})
    });
    const data = await response.json();
    if (!response.ok || data.status !== "success") throw new Error(data.message || "Request failed.");
    const url = new URL(data.short_url);
    if (!["http:", "https:"].includes(url.protocol)) throw new Error("Invalid response.");
    const link = document.createElement("a");
    link.href = url.href; link.textContent = url.href;
    link.target = "_blank"; link.rel = "noopener noreferrer";
    result.replaceChildren(link);
  } catch (error) { result.textContent = error.message || "Connection failed."; }
  finally { button.disabled = false; }
});
</script>

Validation and limits

Invalid URLs, private destinations, blocked domains and excessive requests may be rejected. Repeated URLs return the existing short link.

Send one URL per request, up to 2,048 bytes. The creation endpoint allows up to 5 requests per 2 seconds per IP address. On HTTP 429, wait for Retry-After; do not retry in a tight loop.

Always check both the HTTP status and the JSON status. Legacy validation and key errors may return HTTP 200 with status=error. HTTP 405 requires POST; HTTP 503 indicates maintenance or a pending check. Retry only when instructed and keep the original URL if creation fails.

{"status": "error", "message": "Invalid URL"}
{"status": "error", "code": "rate_limited", "message": "Too many requests, please try again."}

cURL

curl -X POST 'https://freetoolsweb.com/short-url/?api=create' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  --data '{"url":"https://example.com"}'