Skip to content

API reference

API reference

Create, read and update short links and read their analytics over HTTPS with an API key.

The iShortn REST API lets you create short links from your own code, change where they point and pull their click analytics. Every endpoint lives under one base URL and speaks JSON.

https://ishortn.ink/api/v1
EndpointWhat it does
POST /api/v1/linksCreate a short link
GET /api/v1/links/{alias}Get a short link
PATCH /api/v1/links/{alias}Change a link's destination, alias, expiry or schedule
GET /api/v1/analytics/{alias}Get click analytics for a link
POST /api/v1/clicks/verifyConfirm a verified click (called by iShortn's redirect page)

These are the only endpoints. Listing and deleting links isn't available through the API yet; use the dashboard for those.

Authentication

Every request except Verify a click needs an API key in the x-api-key header.

curl https://ishortn.ink/api/v1/links/launch-day \
  -H "x-api-key: YOUR_API_KEY"

To create a key:

  1. Open Settings in the dashboard and scroll to API Keys.
  2. Click Create API Key.
  3. Copy the key from the dialog and store it somewhere safe, such as your secret manager or an environment variable.

The key is shown once. iShortn stores only a SHA-256 hash of it, so a lost key can't be recovered: delete it in Settings and create a new one. Treat the key like a password. Anyone who has it can create and change links on your account, so never put it in client-side code or a public repository.

A missing, unknown or revoked key returns 401 with the body Invalid or missing API key. Keys on accounts that are suspended or deleted stop working the same way.

An API key belongs to you, not to a team, so it works in your personal workspace:

  • Links created through the API are added to your personal workspace.
  • GET, PATCH and analytics requests only find links in your personal workspace. Links in a team workspace return 404.

Domains

A short link is identified by its alias and its domain: isht.app/launch-day and isht.ink/launch-day are different links. Each endpoint that takes an alias also accepts a domain:

  • When you leave domain out, the API uses the default domain from Settings → General. If you haven't picked one, it uses isht.app.
  • You can pass any platform domain (isht.app, isht.ink, ishortn.ink) or a custom domain that is active in your personal workspace.
  • Any other domain returns 403 with Domain not available for this API key.

Domains are matched case-insensitively and a trailing dot is ignored.

Plans and limits

Requests are checked against the plan of the key's owner, exactly as in the dashboard:

RuleFreeProUltra
New links per month (API and dashboard combined)301,000Unlimited
Shortest custom alias6 characters1 character1 character
Password protectionNoYesYes
Scheduled activation (activatesAt)NoYesYes
UTM parameters (utmParams)NoNoYes

The monthly link count resets on the first day of each calendar month. See Plans and limits for everything else.

Rate limits

Requests are limited per account, not per key: all of your API keys share one budget. Both windows apply, and each is a sliding window.

WindowFreeProUltra
Requests per minute603001,200
Requests per day1,00010,000100,000

Every response carries the current state of the window closest to its limit:

HeaderMeaning
X-RateLimit-LimitRequests allowed in that window.
X-RateLimit-RemainingRequests left in that window.
X-RateLimit-ResetUnix time (seconds) when that window rolls over.

A request over the limit returns 429 with a Retry-After header (seconds) and the body Rate limit exceeded. Retry in N seconds. Rejected requests don't count against the limit. Wait for Retry-After before retrying, and retry other failures with a backoff.

Responses and errors

Successful responses are JSON with Content-Type: application/json. Dates are ISO 8601 strings in UTC, or null when unset.

Error responses are plain text with an HTTP status code. The body is a human-readable message you can show to your users, for example Link not found. When a request body fails validation, the 400 body is a JSON-formatted list of the problems:

[
  {
    "code": "invalid_format",
    "format": "url",
    "path": ["url"],
    "message": "Invalid URL"
  }
]
StatusMeaning
200Success
201Link created
202Accepted (Verify a click)
400The request is invalid or a plan rule blocked it. The body says why.
401Missing or invalid API key
403Domain not available, a plan-only feature, or the monthly link limit
404No link with that alias on that domain in your personal workspace
409The new alias is already taken on that domain
429Rate limit exceeded. See Rate limits.
500Something went wrong on our side. Retry later.

Every destination URL is checked before a link is created or its destination changes. A URL that fails the check is rejected with 400 and one of the messages listed in Abuse and acceptable use.

Something missing or unclear? Email support@ishortn.ink.