API documentation

Create and manage short links from your own code. The API is JSON over HTTPS, and every request acts on one workspace: the one your API key belongs to.

Base URL: https://api.innkie.com/api/v1

You do not need the API to use iNNkie: the free tools and the dashboard work without it.

Authentication

Create a key in the Developer Studio and send it in the x-api-key header. The full key is shown only once, when you create it, so copy it straight away; iNNkie stores only a hash and cannot show it again. A key is tied to a single workspace, can only see and change that workspace's links, and generating a new key revokes the old one. Only owners and admins can create keys. Keep it secret: anyone with the key can create and delete links in that workspace.

Try it
curl https://api.innkie.com/api/v1/links \
  -H "x-api-key: ik_YOUR_KEY"

Other parts of the web app (workspaces, members, webhook management) use your sign-in session and are not part of the API-key API.

Limits and errors

Requests are rate limited per client IP address: 60 reads and 20 writes (create, update, delete) per minute. Over the limit you get 429.

400Bad request
The body or a query parameter failed validation. The message says which one.
401Unauthorised
The x-api-key header is missing or the key is not valid.
404Not Found
No such link in your workspace. Links in other workspaces look exactly the same as missing links.
409Conflict
The custom alias is already taken.
429Too Many Requests
Rate limit exceeded. Wait a minute and retry.
Error body
{
  "statusCode": 400,
  "message": "Please enter a valid URL starting with http:// or https://",
  "error": "Bad Request"
}

Create a link

POST /links

Creates a short link in your workspace. If the same destination URL was already shortened in this workspace and you do not ask for a custom alias, password or expiry, that existing link is returned with alreadyExisted: true instead of a duplicate. Asking for any of those creates a new link.

urlstring, required
Destination. Must start with http:// or https://, at most 2048 characters.
customAliasstring
Letters, numbers, - and _ (max 64). Case-insensitive; stored in lower case. Some words are reserved.
tagsstring[]
Up to 30 tags of up to 50 characters.
passwordProtectedboolean
Require a password before redirecting.
passwordstring
At least 4 characters. Stored only as a salted hash and never returned.
expirationobject
See below.
campaignobject
Optional UTM values: utmSource, utmMedium, utmCampaign, utmTerm, utmContent. Added to the destination on redirect.

expiration takes a mode of never, date (with expiryDate as an ISO string), clicks or oneTime (with maxClicks), or duration (with durationValue and durationUnit of minutes, hours or days).

Request
curl -X POST https://api.innkie.com/api/v1/links \
  -H "x-api-key: ik_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/products/spring",
    "customAlias": "spring-sale",
    "tags": ["campaign", "email"],
    "expiration": { "mode": "date", "expiryDate": "2027-01-01T00:00:00Z" }
  }'
Response 201
{
  "shortCode": "spring-sale",
  "shortUrl": "https://innkie.com/spring-sale",
  "originalUrl": "https://example.com/products/spring",
  "customAlias": "spring-sale",
  "title": null,
  "description": null,
  "tags": ["campaign", "email"],
  "campaign": null,
  "isActive": true,
  "passwordProtected": false,
  "expiration": { "mode": "date", "expiryDate": "2027-01-01T00:00:00.000Z" },
  "clickCount": 0,
  "source": "api",
  "createdAt": "2026-11-12T10:15:00.000Z",
  "updatedAt": null,
  "alreadyExisted": false
}

List links

GET /links

Returns your workspace's links, newest first, one page at a time.

limitinteger
1 to 100. Default 25.
cursorstring
Pass the nextCursor from the previous page to get the next one.
Request
curl "https://api.innkie.com/api/v1/links?limit=2" -H "x-api-key: ik_YOUR_KEY"
Response 200
{
  "data": [ { "shortCode": "spring-sale", "...": "..." }, { "shortCode": "Xk2p9a", "...": "..." } ],
  "nextCursor": "Xk2p9a"
}

When nextCursor is null you have reached the end.

Get a link

GET /links/:code

Returns one link by its short code. clickCount is the running total.

Request
curl https://api.innkie.com/api/v1/links/spring-sale -H "x-api-key: ik_YOUR_KEY"

Update a link

PATCH /links/:code

Changes the fields you send and leaves the rest alone. The destination URL of an existing link is fixed: to point somewhere else, create a new link.

title, descriptionstring
Labels for your own use.
isActiveboolean
false switches the link off without deleting its history.
customAliasstring | null
Change the alias (must be free) or null to clear it.
tagsstring[]
Replaces the tag list.
campaignobject | null
UTM values, as when creating.
expirationobject
As when creating.
passwordProtected, passwordboolean, string
Turn protection on with a password, or off with passwordProtected: false.
qrConfigobject | null
A QR design saved with the link, as used by the dashboard. null clears it.
Request
curl -X PATCH https://api.innkie.com/api/v1/links/spring-sale \
  -H "x-api-key: ik_YOUR_KEY" -H "content-type: application/json" \
  -d '{ "isActive": false, "tags": ["campaign", "ended"] }'

Returns the updated link. Fields not listed above (owner, counters, destination) are ignored.

Delete a link

DELETE /links/:code

Permanently deletes the link. Its short URL stops working. This cannot be undone.

Request
curl -X DELETE https://api.innkie.com/api/v1/links/spring-sale -H "x-api-key: ik_YOUR_KEY"
Response 200
{ "deleted": true, "shortCode": "spring-sale" }

Click statistics

GET /links/:code/clicks

Daily click counts for one link.

daysinteger
1 to 30. Default 7.
Request
curl "https://api.innkie.com/api/v1/links/spring-sale/clicks?days=7" -H "x-api-key: ik_YOUR_KEY"
Response 200
{
  "shortCode": "spring-sale",
  "days": 7,
  "total": 5,
  "data": [ { "date": "2026-11-10", "clicks": 2 }, { "date": "2026-11-11", "clicks": 3 } ]
}

Country, device and referrer breakdowns are available in the dashboard.

Webhooks

Add an endpoint in the Developer Studio and choose events. We send a POST with a JSON body. Your endpoint should answer within 5 seconds; failed deliveries are not retried, so treat webhooks as a convenience and use the list endpoint to reconcile.

link.createdevent
A link was created, from the web app or the API. data is the link object.
link.clickedevent
A link was visited. data has shortCode, originalUrl, timestamp, country, city, referrer and deviceType. It does not include the visitor's IP address.
link.deletedevent
A link was deleted. data is the link object as it was.
Delivery
{
  "event": "link.clicked",
  "timestamp": "2026-11-12T10:20:00.000Z",
  "workspaceId": "your-workspace-id",
  "data": { "shortCode": "spring-sale", "country": "GH", "deviceType": "mobile", "...": "..." }
}

Webhook destinations must be public http(s) addresses; private and internal addresses are refused.

Verifying signatures

Every delivery carries an X-Innkie-Signature header: the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Compute it over the raw bytes you received, before parsing the JSON, and compare in constant time.

Node.js
const crypto = require('crypto');

function verify(rawBody, secret, signature) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}