API

A project sends one address to iShare and receives a short link. The response is that link, https://isha.re/ plus a short code. There is no account and no API key. The first 100 new links each month are free. After that, the price is €1.45 per 1,000 links. Opening the short link sends the visitor to the original address.

Integration

Call POST https://isha.re/api/v1/links from the project that needs a short link. Put the long address in the request. Read link from the JSON body and store that string. It is the URL you show, share, or redirect to.

The same steps from a browser, a server, or a script:

1. Normalize nothing yourself. Send the address as you have it.
2. POST it to /api/v1/links.
3. On 200, use the returned link. On 400, the address was not a usable URL.

Browsers on other sites can call the API directly. Responses include Access-Control-Allow-Origin: *. A preflight OPTIONS request returns 204.

JavaScript

const response = await fetch("https://isha.re/api/v1/links", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/page" }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error);
}

const { link } = await response.json();

Python

import json
import urllib.request

body = json.dumps({"url": "https://example.com/page"}).encode()
request = urllib.request.Request(
    "https://isha.re/api/v1/links",
    data=body,
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    link = json.load(response)["link"]

curl

curl -X POST https://isha.re/api/v1/links \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/page"}'

That prints:

{"link":"https://isha.re/tk8c"}

Reference

One endpoint creates a short link. The link itself is a normal URL on this host. Both parts use the same address rules, the same stored code, and the same redirect.

Create a link

POST /api/v1/links

The body is the address to shorten. JSON is the usual form. A form field or a plain-text body works the same way. An address without a scheme is treated as HTTPS, so example.com/docs is https://example.com/docs.

POST /api/v1/links
Content-Type: application/json

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

POST /api/v1/links
Content-Type: application/x-www-form-urlencoded

url=https://example.com/page

POST /api/v1/links
Content-Type: text/plain

https://example.com/page

Response

A successful call returns 200 and the short link. JSON is the default. Ask for the bare link with Accept: text/plain or ?format=text. Force JSON with ?format=json.

HTTP/1.1 200 OK
Content-Type: application/json

{"link":"https://isha.re/tk8c"}

curl -X POST 'https://isha.re/api/v1/links?format=text' \
  -H 'Content-Type: text/plain' \
  --data 'https://example.com/page'

https://isha.re/tk8c

The host in link is the host you called. A request to isha.re returns https://isha.re/ and the code. Calling the API again with the same address returns that same link. iShare does not mint a second code for an address it already stores.

When the address is new, JSON also includes statsKey. A text response sends that same value in the X-Stats-Key header. Keep it. It is the key for this link’s open stats, and a later call for an address that already has a key does not return it again.

Links created through this API do not expire. If the address was first shortened on the website with an end date, this call returns that existing link, and the end date stays. A later call does not extend it. Once that link has ended, shortening the address again creates a new one.

Open a short link

GET /{code} and HEAD /{code} answer with 302 and a Location header set to the original address. The code is the last path segment of the link from the create call. A GET counts the open, including the source, country, and device. HEAD redirects without counting. An unknown code redirects to the home page. A code that does not match the short-link shape returns 404.

Addresses

• Only http and https are stored. Any other scheme is rejected.
• A missing scheme becomes https.
• Usernames and passwords in the URL are rejected.
• The host must contain a dot, or be localhost.
• The host is stored in lowercase. A fragment (#…) is removed.
• A trailing slash is removed, except when the path is only /.
• The address can be at most 4096 characters.

Pricing

The first 100 new links in a calendar month are free. Links after that cost €1.45 per 1,000. A repeated address does not count again. The pricing page has the examples. JSON includes a usage object with included, used, extra, and amount in euros.

Errors

Errors use the same shape as the success body you asked for. JSON requests get {"error":"…"}. Text requests get the message as plain text.

• 400 — the body was empty, not a URL, or broke one of the address rules. Message: Enter a valid URL, like https://example.com.
• 500 — the shortener could not store the link. Message: The shortener is temporarily unavailable.