Skip to content

API reference

Create a link

Shorten a URL, optionally with your own alias, domain, expiry, password, schedule or UTM parameters.

POSThttps://ishortn.ink/api/v1/links

Creates a short link in your personal workspace and counts it toward your monthly link limit.

Request

Send a JSON body with Content-Type: application/json and your key in x-api-key.

FieldTypeRequiredDescription
urlstringYesThe destination. Must be a valid absolute URL, such as https://example.com/page.
aliasstringNoThe path after the domain. Letters, numbers, - and _, up to 20 characters, and at least 6 characters on the Free plan. Must not already exist on the domain (checked case-insensitively). Defaults to a random 9-character alias.
domainstringNoThe domain for the link. Defaults to your default domain, or isht.app. See Domains.
expiresAtstringNoDate and time after which the link stops redirecting, as an ISO 8601 string such as 2026-12-31T23:59:59Z.
expiresAfternumberNoNumber of clicks after which the link stops redirecting.
activatesAtstringNoDate and time the link starts redirecting, as an ISO 8601 string with a time zone (Z or an offset such as +01:00). Pro and Ultra only.
passwordstringNoVisitors must enter this password before they're redirected. Requires an active Pro or Ultra subscription. Stored as a bcrypt hash.
utmParamsobjectNoUTM parameters added to the destination when the link is visited. Ultra only. See below.

utmParams accepts these optional string fields, each up to 255 characters: utm_source, utm_medium, utm_campaign, utm_term and utm_content.

Fields not in this table are ignored. Folders, tags, notes, targeting rules and the other dashboard settings can't be set through the API yet.

curl https://ishortn.ink/api/v1/links \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/launch-day",
    "alias": "launch-day",
    "expiresAfter": 1000
  }'

Response

201 Created with the new link.

FieldTypeDescription
shortLinkstringThe full short URL, https://<domain>/<alias>.
urlstringThe destination URL.
aliasstringThe alias, either yours or the generated one.
expiresAtstring | nullWhen the link expires, or null.
activatesAtstring | nullWhen the link starts redirecting, or null.
expiresAfternumber | nullClick limit, or null.
isProtectedbooleantrue when the link has a password.
{
  "shortLink": "https://isht.app/launch-day",
  "url": "https://example.com/blog/launch-day",
  "alias": "launch-day",
  "expiresAt": null,
  "activatesAt": null,
  "expiresAfter": 1000,
  "isProtected": false
}

Errors

Error bodies are plain text.

StatusBodyCause
400JSON list of validation issuesA field has the wrong type, or url isn't a valid URL, or activatesAt isn't an ISO 8601 date with a time zone.
400Alias can only contain alphanumeric characters, dashes, and underscoresThe alias has other characters.
400Custom aliases must be at least 6 characters on the free plan. Upgrade to Pro for shorter aliases.Free plan with a short alias.
400Alias already existsThe alias is taken on that domain.
400A database error messageThe alias is longer than 20 characters.
400You need to upgrade to a pro plan to use password protectionpassword without an active Pro or Ultra subscription.
400UTM parameters are only available on the Ultra plan. Please upgrade to use this feature.utmParams on Free or Pro.
400A link safety messageThe destination failed the safety check.
401Invalid or missing API keySee Authentication.
403Domain not available for this API keydomain isn't a platform domain or an active custom domain in your personal workspace.
403Scheduled links are only available on Pro and Ultra plansactivatesAt on the Free plan.
403You've reached your monthly limit of 30 links. Upgrade to Pro for more.Free plan monthly limit. On Pro the message names the 1,000-link limit and suggests Ultra.
500The body wasn't valid JSON, or an unexpected server error.
429Rate limit exceeded. Retry in N seconds.See Rate limits.

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