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.
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.
| Name | Type | Description |
|---|---|---|
| 400 | Bad request | The body or a query parameter failed validation. The message says which one. |
| 401 | Unauthorised | The x-api-key header is missing or the key is not valid. |
| 404 | Not Found | No such link in your workspace. Links in other workspaces look exactly the same as missing links. |
| 409 | Conflict | The custom alias is already taken. |
| 429 | Too Many Requests | Rate limit exceeded. Wait a minute and retry. |
{
"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.
| Name | Type | Description |
|---|---|---|
| url | string, required | Destination. Must start with http:// or https://, at most 2048 characters. |
| customAlias | string | Letters, numbers, - and _ (max 64). Case-insensitive; stored in lower case. Some words are reserved. |
| tags | string[] | Up to 30 tags of up to 50 characters. |
| passwordProtected | boolean | Require a password before redirecting. |
| password | string | At least 4 characters. Stored only as a salted hash and never returned. |
| expiration | object | See below. |
| campaign | object | 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).
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" }
}'{
"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.
| Name | Type | Description |
|---|---|---|
| limit | integer | 1 to 100. Default 25. |
| cursor | string | Pass the nextCursor from the previous page to get the next one. |
curl "https://api.innkie.com/api/v1/links?limit=2" -H "x-api-key: ik_YOUR_KEY"
{
"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.
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.
| Name | Type | Description |
|---|---|---|
| title, description | string | Labels for your own use. |
| isActive | boolean | false switches the link off without deleting its history. |
| customAlias | string | null | Change the alias (must be free) or null to clear it. |
| tags | string[] | Replaces the tag list. |
| campaign | object | null | UTM values, as when creating. |
| expiration | object | As when creating. |
| passwordProtected, password | boolean, string | Turn protection on with a password, or off with passwordProtected: false. |
| qrConfig | object | null | A QR design saved with the link, as used by the dashboard. null clears it. |
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.
curl -X DELETE https://api.innkie.com/api/v1/links/spring-sale -H "x-api-key: ik_YOUR_KEY"
{ "deleted": true, "shortCode": "spring-sale" }Click statistics
GET /links/:code/clicks
Daily click counts for one link.
- daysinteger
- 1 to 30. Default 7.
| Name | Type | Description |
|---|---|---|
| days | integer | 1 to 30. Default 7. |
curl "https://api.innkie.com/api/v1/links/spring-sale/clicks?days=7" -H "x-api-key: ik_YOUR_KEY"
{
"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.
The link object
Every endpoint returns links in this shape. Password hashes and account identifiers are never included.
{
"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": null,
"clickCount": 0,
"source": "api",
"createdAt": "2026-11-12T10:15:00.000Z",
"updatedAt": null
}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.
| Name | Type | Description |
|---|---|---|
| link.created | event | A link was created, from the web app or the API. data is the link object. |
| link.clicked | event | A link was visited. data has shortCode, originalUrl, timestamp, country, city, referrer and deviceType. It does not include the visitor's IP address. |
| link.deleted | event | A link was deleted. data is the link object as it was. |
{
"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.
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);
}