Developers & REST API

Base URLhttps://hi4.in/api/v1

AuthenticationX-API-Key

FormatJSON in, JSON out

StatusLive Pro and Business plans

Quick start

Your first short link in three steps

Create an account

Sign up free and open your dashboard.

Create free account

Create an API key

Dashboard → API keys. Copy the key straight away: it is shown only once.

How to create a key

Call the API

Send the key in the X-API-Key header. Start with GET /test, then create a link.

Request

curl -X POST https://hi4.in/api/v1/links \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/diwali-sale",
    "title": "Diwali sale",
    "custom_slug": "diwali-sale"
  }'

Response

{
    "success": true,
    "data": {
        "id": "1234",
        "slug": "diwali-sale",
        "short_url": "https://hi4.in/u/diwali-sale",
        "long_url": "https://example.com/diwali-sale",
        "title": "Diwali sale",
        "expires_at": null,
        "created_at": "2026-10-22 16:05:10"
    }
}

Read slug from the response. If custom_slug is invalid or already taken, the API uses a random slug instead of failing.

Authentication

One key in one header

Send your key in the X-API-Key header on every call. Only /test, /health and /docs work without one.
A key is shown once. We store only a fingerprint (hash) of it, so we cannot show it again — create a new key if you lose it.
You can give a key an expiry date when you create it, and delete keys at any time.
Keep keys on your server. Never put them in a website, mobile app or public code.
Every call counts towards your account’s hourly limit. Check it with GET /stats.

Sign up to create a key Guide: create an API key

Example

# Every request carries your key
curl https://hi4.in/api/v1/links \
  -H "X-API-Key: YOUR_API_KEY"

# No key or a wrong key: HTTP 401
{
    "error": "API key required"
}

# No key needed: check you can reach the API
curl https://hi4.in/api/v1/test

{
    "success": true,
    "message": "API is working",
    "timestamp": "2026-10-22T16:04:52+05:30"
}

Reference

Endpoints

All paths are relative to https://hi4.in/api/v1. Requests and responses are JSON.

POST /links Create a short link API key
GET /links List your links, newest first (page, limit up to 100) API key
GET /links/{id} One link with its click analytics API key
PUT /links/{id} Change the title, destination, expiry or visibility API key
DELETE /links/{id} Delete a link API key
GET /links/{id}/analytics Click summary, top locations and devices API key
GET /domains Your custom domains Coming soonAPI key
POST /domains Add a custom domain to your account Coming soonAPI key
GET /stats Your hourly request limit and what is left API key
GET /test Check the API is reachable No key
GET /health Service health check No key
GET /docs Machine-readable list of these endpoints No key

Examples

Newest first. limit is capped at 100; use pagination.pages to loop.

Request

curl "https://hi4.in/api/v1/links?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
    "success": true,
    "data": [
        {
            "id": 1234,
            "slug": "diwali-sale",
            "long_url": "https://example.com/diwali-sale",
            "title": "Diwali sale",
            "total_clicks": 42,
            "last_click": "2026-10-21 18:30:12",
            "short_url": "https://hi4.in/u/diwali-sale"
        }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 57, "pages": 3 }
}

Returns the stored link plus an analytics object (same shape as /analytics below).

Request

curl https://hi4.in/api/v1/links/1234 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
    "success": true,
    "data": {
        "id": 1234,
        "slug": "diwali-sale",
        "long_url": "https://example.com/diwali-sale",
        "short_url": "https://hi4.in/u/diwali-sale",
        "analytics": { "summary": {}, "geographic": [], "devices": [] }
    }
}

Send only the fields you want to change. The response is the full, updated link.

Request

curl -X PUT https://hi4.in/api/v1/links/1234 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/new-offer",
    "expires_at": "2026-12-31T23:59:59+05:30"
  }'

Response

{
    "success": true,
    "data": {
        "id": 1234,
        "slug": "diwali-sale",
        "long_url": "https://example.com/new-offer",
        "expires_at": "2026-12-31 23:59:59",
        "short_url": "https://hi4.in/u/diwali-sale"
    }
}

Permanent: the short link stops working, including on printed QR codes.

Request

curl -X DELETE https://hi4.in/api/v1/links/1234 \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
    "success": true,
    "message": "Link deleted successfully"
}

unique_clicks counts distinct visitors by network address. geographic and devices list the top 10 rows.

Request

curl https://hi4.in/api/v1/links/1234/analytics \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
    "success": true,
    "data": {
        "summary": {
            "total_clicks": 42,
            "unique_clicks": 31,
            "active_days": 6,
            "first_click": "2026-10-15 10:02:41",
            "last_click": "2026-10-21 18:30:12"
        },
        "geographic": [
            { "country": "India", "city": "Pune", "clicks": 12 }
        ],
        "devices": [
            { "device_type": "mobile", "browser": "Chrome", "clicks": 30 }
        ]
    }
}

Coming soon: you can add a domain to your account, but connecting it (DNS and SSL) is not automated yet, so short_url stays on hi4.in until a domain is verified.

Request

curl https://hi4.in/api/v1/domains \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST https://hi4.in/api/v1/domains \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "go.yourbrand.in"}'

Response

{
    "success": true,
    "data": {
        "id": 7,
        "domain_name": "go.yourbrand.in",
        "verification_token": "…",
        "verified": 0
    }
}

rate_limit is your hourly limit; hourly_requests counts calls in the last hour.

Request

curl https://hi4.in/api/v1/stats \
  -H "X-API-Key: YOUR_API_KEY"

Response

// example values
{
    "success": true,
    "data": {
        "rate_limit": 1000,
        "hourly_requests": 12,
        "remaining_requests": 988
    }
}

Fields

What to send and what you get back

Create a link — `POST /links`

Field	Type	Required	What it does
`long_url`	string (URL)	Required	The destination. A full address including https://.
`title`	string	Optional	A label for your dashboard and reports.
`custom_slug`	string	Optional	3–50 letters, numbers or hyphens. If it is invalid, reserved or already taken, a random slug is used instead — always read slug from the response.
`password`	string	Optional	Visitors must type this password before they are sent on.
`expires_at`	string (ISO 8601)	Optional	After this time the link stops working. Include a time zone, e.g. 2026-12-31T23:59:59+05:30.
`domain_id`	integer	Optional	One of your own domains from GET /domains. Until a domain is verified, short_url stays on hi4.in.

Update a link — `PUT /links/{id}`

Field	Type	What it does
`title`	string	New label.
`long_url`	string (URL)	New destination. The short link and any printed QR code keep working.
`expires_at`	string (ISO 8601)	New expiry. Send an empty string "" to remove the expiry.
`is_public`	boolean	Marks the link as public (true) or private (false).

Link object in responses

Field	Type	Notes
`id`	integer	Use it with /links/{id}. In the create response it arrives as a string.
`slug`	string	The part after the domain. May differ from custom_slug (see above).
`short_url`	string	Ready-to-share link, e.g. https://hi4.in/u/diwali-sale. hi4.in/diwali-sale opens the same link.
`long_url`	string	Where the link sends visitors.
`title`	string	Your label.
`expires_at`	string or null	When the link stops working.
`created_at`	string	When the link was made.
`total_clicks, last_click`	integer, string	Added in GET /links results.
`analytics`	object	Added in GET /links/{id}: summary, geographic and devices.

GET /links returns every stored field of each link, plus total_clicks, last_click and short_url. List responses also include pagination: page, limit, total and pages.

Errors and limits

When something goes wrong

Errors use normal HTTP status codes and a JSON body with a single error message.

{
    "error": "message"
}

Each account has an hourly request limit, and calls made with your key count towards it. GET /stats shows your limit and how many calls are left.

HTTP	Meaning	Example body
400	Bad request The body is not valid JSON, long_url is missing, or a URL or domain name is malformed.	`{"error": "long_url is required"}`
401	Unauthorised The X-API-Key header is missing, wrong or the key has expired.	`{"error": "Invalid API key"}`
403	Forbidden domain_id belongs to someone else or does not exist.	`{"error": "Invalid domain or access denied"}`
404	Not found The link ID does not exist or is not yours. Unknown paths also return 404.	`{"error": "Link not found"}`
409	Conflict That custom domain is already registered.	`{"error": "Domain is already taken"}`
429	Too many requests You reached your hourly request limit. Wait, then retry with back-off.	`{"error": "Rate limit exceeded"}`
500	Server error Something failed on our side. Retry later; tell us if it keeps happening.	`{"error": "Failed to create link"}`

Bulk links

Hundreds of links without writing an app

Making links for a whole campaign, catalogue or SMS list? Use the bulk tool in your dashboard, or loop over a file with the API.

Live

Bulk tool in the dashboard

Paste up to 100 links, one per line, or upload a .txt file
Optional name prefix and expiry for the whole batch
Download the new short links as a CSV file

Sign up to use bulk links

Live

Bulk with the API

Call POST /links once per row. Stay inside your hourly limit and save the slug from every response.

Shell

# links.csv has two columns: url,title (no header row)
while IFS=, read -r url title; do
  curl -s -X POST https://hi4.in/api/v1/links \
    -H "X-API-Key: $HI4_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"long_url\": \"$url\", \"title\": \"$title\"}"
  echo
done < links.csv

For real projects, build the JSON with a proper library so titles with quotes or commas are handled safely.

Coming soon

Integrations we are working towards

None of these are available yet. Tell us which one you need and we will let you know when it is ready.

See the roadmap

Coming soon

Webhooks Your server is told when a link is clicked or a link-health alert fires.

Coming soon

Zapier and Make Create links from forms, sheets and CRMs without writing code.

Coming soon

Shopify and WooCommerce plugins Short, trackable links for products and campaigns from inside your store.

Coming soon

Public API v2 A larger, versioned API planned to cover more of hi4.in, such as QR codes and pages.

Coming soon

SMS Sender-ID link API Create hi4.in/SENDERID/offer links for DLT-registered SMS in bulk.

Get told when your integration is ready

One email when it launches. No newsletter unless you ask for it.

Building something for SMS? See SMS links

No code needed

Just need a few links? The free tools need no API

All free tools

Free URL shortener Clean redirect, no ads, QR included. UTM builder Tag campaign links for Google Analytics, then shorten them. New Bulk QR codes Paste a list, download a ZIP of print-ready QR codes.

Developer questions

Which plans include the API?

Per our plan comparison, the REST API and bulk tools are part of the Pro and Business plans. See the pricing page for everything each plan includes.

How do I authenticate?

Send your API key in the X-API-Key header with every request. There is no OAuth or login flow in the API today, so keep the key on your server.

Why did my link get a different slug from the one I asked for?

If custom_slug is shorter than 3 characters, uses anything other than letters, numbers and hyphens, is a reserved word or is already taken, the API quietly uses a random slug. Always read slug and short_url from the response.

What do short links from the API look like?

Responses return links as https://hi4.in/u/{slug}. The shorter https://hi4.in/{slug} opens the same link, so you can use either.

Are there rate limits?

Yes. Each account has an hourly request limit. GET /stats shows your limit and how many calls are left; above the limit the API answers with HTTP 429.

Is there a sandbox or test mode?

Not yet. Use GET /test to check your connection, give test links a title like "test", and delete them afterwards.

Do you have webhooks, SDKs or Zapier?

Not yet — they are on the roadmap. The API is plain JSON over HTTPS, so the HTTP client in any language works.

Do I need the API to make a few links?

No. The free tools on hi4.in make short links, WhatsApp links and QR codes in the browser without any key or code.

Stuck? Write to us from the contact page with the request you sent and the response you got (remove your key first).

Build on hi4.in

Free account, no card needed. Create your API key from the dashboard and make your first link in minutes.

Developers & REST API

Your first short link in three steps

Create an account

Create an API key

Call the API

One key in one header

Endpoints

Examples

What to send and what you get back

Create a link — POST /links

Update a link — PUT /links/{id}

Link object in responses

When something goes wrong

Hundreds of links without writing an app

Bulk tool in the dashboard

Bulk with the API

Integrations we are working towards

Get told when your integration is ready

Just need a few links? The free tools need no API

Developer questions

Build on hi4.in

Create a link — `POST /links`

Update a link — `PUT /links/{id}`