For developers

Ship link features without building a shortener.

Q: Can I call the API from front-end code?

Yes. CORS is open (Access-Control-Allow-Origin: *), so any web page can call it. Limits apply per IP address, so each visitor’s requests count against their own quota.

Q: How do I know how much of my quota is left?

Read the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers on any response. Go over and you get a 429 with the rate_limited code and a Retry-After header.

Q: Is there an OpenAPI spec?

Yes: OpenAPI 3.1, at /openapi.json and at https://api.blinkhop.com/v1/openapi.json. Import it into your API client or code generator.

The Blinkhop URL shortener API turns any URL into a zou.sh link with one POST request. Codes, redirects, QR codes and safety checks are handled for you, and you can start without a key.

Read the quickstart API reference

The problem

What building your own shortener involves

01
A small feature, a forever service

Code generation, collision checks, a redirect path that can’t go down and a database that can’t lose a mapping. A side feature becomes infrastructure you run.
02
Abuse lands on your domain

Let users create links and someone will point one at a phishing page. Without a blocklist and a way to report links, your domain takes the reputational hit.
03
Opaque APIs slow you down

HTML error pages, unpublished limits and a key you must request before the first test call make a simple integration drag on.

How it fits

From first request to production

The endpoint you test with cURL is the one you ship.

Step 1
Try it from the terminal

POST a URL to https://api.blinkhop.com/v1/links with no key. A 201 means a new link; a 200 means that URL already had one and you got it back.
Step 2
Read the JSON response

short_url is your link. qr_url and preview_url arrive in the same response, so your UI can show a QR code and a preview link without another call.
Step 3
Branch on error codes

Errors are JSON with a stable code, such as invalid_url, alias_taken or unsafe_destination, and, when relevant, a field that names the input to fix.
Step 4
Stay within the limits

Read X-RateLimit-Remaining on each create response and honor Retry-After on a 429. For many URLs, send up to 100 per call to POST /links/bulk.

Use cases

What you can build on the API

Share buttons

CORS is open, so a share button can call the API straight from the browser and copy a zou.sh link, with no backend code of your own.
Links on publish

A CMS hook shortens each article’s URL when it goes live and stores the result. If the hook runs again, it gets the same link back, not a duplicate.
Product catalogs

Shorten a whole catalog 100 URLs at a time with POST /links/bulk. Each URL gets its own result, so one bad entry doesn’t sink the batch.
Labels and signage

Print the QR code from qr_url on packaging, shelf labels or event signs. It’s an SVG, so it stays sharp at any size.
Scripts and chat commands

Add ?format=text and the API returns only the short URL, ready for a shell variable in a deploy script or a reply from a chat command.
Moderating user links

Before showing short links that users submit, call GET /expand to see the final destination and its safety verdict.

Get started

Call the URL shortener API from any language

Send a JSON body with a url field to https://api.blinkhop.com/v1/links and read short_url from the response. No key and no SDK needed. The cURL example uses jq to print the link.

Read the quickstart API reference

terminal

curl -s https://api.blinkhop.com/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/products/linen-shirt?color=sand&size=m"}' \
  | jq -r .short_url

shorten.mjs

const res = await fetch("https://api.blinkhop.com/v1/links", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/products/linen-shirt?color=sand&size=m" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.code);
console.log(data.short_url);

shorten.py

import requests

r = requests.post(
    "https://api.blinkhop.com/v1/links",
    json={"url": "https://example.com/products/linen-shirt?color=sand&size=m"},
    timeout=10,
)
data = r.json()
print(data["short_url"] if r.ok else data["error"]["code"])

201 Created output

https://zou.sh/Tq4mZ

Features you’ll use

The parts of Blinkhop that matter here.

Link shortener
Turn any long URL into a clean zou.sh link in a second.
Custom endings
Readable short links like zou.sh/launch that people trust.
Bulk shortening
Up to 100 links in one API call, CSV upload with an account.
QR codes
A print-ready SVG QR code for every short link.
Link safety
Every destination is checked against 390,000 known bad domains.
Analytics
Clicks by day, country, referrer and device. No cookies.

FAQ

Questions, answered.

Visit the help center

Do I need an API key?

Not to start. Without a key, each IP address can create 20 links per minute and 300 per day. Keys with higher limits come with accounts (early access), from 1,000 links a day on a free account to 250,000 a month on Team.

What happens if I send the same URL twice?

Unless you asked for a custom ending, you get the existing link back with HTTP 200 instead of 201. Retries and re-run jobs can’t create duplicates.

Can I call the API from front-end code?

Yes. CORS is open (Access-Control-Allow-Origin: *), so any web page can call it. Limits apply per IP address, so each visitor’s requests count against their own quota.

How do I know how much of my quota is left?

Read the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers on any response. Go over and you get a 429 with the rate_limited code and a Retry-After header.

Is there an OpenAPI spec?

Yes: OpenAPI 3.1, at /openapi.json and at https://api.blinkhop.com/v1/openapi.json. Import it into your API client or code generator.

Can I shorten URLs that contain tokens or personal data?

Avoid it. A short link is public by design, and anyone who has or guesses its code can read the destination on its + preview page. Keep secrets out of the URLs you send.

Developers
Code samples
Copy-paste examples in JavaScript, Python, Go, PHP and the shell.
Guide
URL shortener API: shorten links from code, no key required
Use the Blinkhop URL shortener API without a key: create zou.sh links with curl, Python or JavaScript, shorten 100 URLs at once, and handle errors and rate limits.
Help
What are the API rate limits?
Without a key, each IP address can create 20 links per minute and 300 per day. The MCP server allows 120 calls per minute and 5,000 per day.
Solutions
Blinkhop for AI agents
Short links your agents create and check on their own.