Lnki.io API

Quickstart

Four steps from nothing to a working short link.

1. 1

   Create an API key

   In the dashboard open API Keys and choose Create New API Key. The key starts with lnki_live_ and is shown once, so copy it somewhere safe straight away. API keys are available on the Business plan.

2. 2

   Exchange the key for an access token

   Your key is only ever sent to the token endpoint. It answers with an access token that lasts one hour, and a refresh token for getting the next one.

   cURLJavaScriptPythonPHPGo

   curl -X POST https://lnki.io/api/v1/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "api_key",
       "api_key": "YOUR_API_KEY"
     }'

3. 3

   Send your first request

   Create a short link by posting the long URL, with the access token as a Bearer token.

   cURLJavaScriptPythonPHPGo

   curl -X POST https://lnki.io/api/v1/links \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "destination_url": "https://example.com/summer-sale"
     }'

4. 4

   Use the response

   You get back 201 Created and the new link object. Its short_host_path is the short link without the scheme. Prefix it with https:// and share it. Keep using the same access token until it expires, then refresh it.

Authentication

The API uses short-lived access tokens. You create a long-lived API key in the dashboard, exchange it for an access token, and send that token with every request. When it expires you use the refresh token that came with it to get a new pair, without sending the key again.

Sending the token

Put the access token in the Authorization header of every request.

Authorization: Bearer YOUR_ACCESS_TOKEN

Token lifecycle

1. Get a token once and keep it in memory or your secret store. Do not request one per API call: the token endpoint allows 30 requests a minute from one address, and a client needs one an hour.
2. Refresh before it runs out. Compare the clock with expires_at, or refresh when a request answers 401 with the code token_expired, then repeat that request.
3. Store the new refresh token each time. A refresh token works once; refreshing returns a new access token and a new refresh token, and the previous pair stops working.
4. Start again from the API key if the refresh token has expired or been revoked.

Authentication errors

A request that cannot be authenticated answers 401 Unauthorized. The code tells you what to do next.

Requests

All endpoints are relative to this base URL.

• Send request bodies as JSON with Content-Type: application/json.
• Responses are JSON, except a QR code's image. Timestamps are ISO 8601 in UTC, for example 2026-10-05T08:34:31.011Z.
• Updates are partial: PATCH changes the fields you send and leaves the rest. PUT is accepted and behaves the same way.
• The version is part of the path. Changes that would break an integration ship under a new version.

Rate limits

Limits are counted in one-minute windows that start on the minute. Every token issued from one API key shares that key's allowance.

Rate limit headers

Every response from a data endpoint tells you where you stand, so you can slow down before you are stopped.

Going over

A request over a limit answers 429 Too Many Requests. Wait for Retry-After seconds, then retry.

{
  "error": "Too many requests. Try again shortly.",
  "code": "rate_limited"
}

Errors

The API uses standard HTTP status codes. Every error body has an error message you can show or log and a code your program can branch on. Validation failures also include an errors array with one message per problem.

{
  "error": "Slug has already been taken",
  "code": "validation_failed",
  "errors": [
    "Slug has already been taken"
  ]
}

Status codes

Pagination

List endpoints return one page at a time, together with a meta object.

The link object

Every endpoint returns links in this shape.

{
  "id": 48291,
  "slug": "summer-sale",
  "domain": "lnki.io",
  "destination_url": "https://example.com/summer-sale",
  "title": "Summer sale landing page",
  "short_host_path": "lnki.io/summer-sale",
  "archived": false,
  "click_count": 0,
  "favorite": false,
  "folder_id": null,
  "utm_campaign_id": null,
  "utm_channel_id": null,
  "expires_at": null,
  "expired": false,
  "password_protected": false,
  "created_at": "2026-10-05T08:34:31.011Z",
  "unique_click_count": 0,
  "tag_ids": [],
  "tags": [],
  "tag_id": null
}

The QR code object

A QR code belongs to one short link and encodes that link's address, with a scan marker, so camera scans are counted apart from clicks on the link and the destination can change without reprinting. A link has at most one QR code.

{
  "id": 7315,
  "name": "Autumn menu",
  "link_id": 48306,
  "short_host_path": "lnki.io/ngczooh",
  "scan_url": "https://lnki.io/ngczooh?qr=1",
  "destination_url": "https://example.com/menu/autumn",
  "folder": "Print",
  "tag_ids": [],
  "tags": [],
  "scans": 0,
  "unique_scans": 0,
  "link_clicks": 0,
  "last_scanned_at": null,
  "favorite": false,
  "archived": false,
  "expires_at": null,
  "password_protected": false,
  "design": {
    "size": 600,
    "foreground_color": "#6D28D9",
    "eye_color": "#1F2A44",
    "background_color": "#FFFFFF",
    "pattern": "dots",
    "eyes": "rounded",
    "corners": "dot",
    "margin": 2,
    "error_correction": "Q",
    "logo": false,
    "label": {
      "text": "Scan for the menu",
      "font_size": 18
    }
  },
  "created_at": "2026-10-05T11:35:52.549Z",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"600\" height=\"684\" viewBox=\"0 0 600 684\">…</svg>"
}

Design options

Send design when creating or updating a QR code to control how it is drawn. Every field is optional; the ones you leave out take the default.

The import object

An import is one batch of links created together. It records what was asked for and what happened to every row.

{
  "id": 11,
  "status": "completed",
  "settings": {
    "domain": "lnki.io",
    "folder_id": null,
    "create_folders": true,
    "create_tags": true
  },
  "summary": {
    "total": 5,
    "created": 2,
    "skipped_invalid": 1,
    "skipped_duplicate": 1,
    "skipped_slug_taken": 1,
    "failed": 0
  },
  "error_message": null,
  "created_at": "2026-10-05T11:36:07.499Z",
  "updated_at": "2026-10-05T11:36:07.754Z"
}

Webhooks

A webhook sends an HTTP POST to your server when something happens in your workspace, so you do not have to poll the API. Add one under Webhooks in the dashboard: give it a name, your endpoint URL and the events you want.

• The endpoint must be a public https:// URL.
• Each webhook has its own signing secret, starting with whsec_. It is shown once, when the webhook is created.
• Choose Test webhook in the webhook's menu to receive a webhook.test event before going live.
• Answer with any 2xx status within 10 seconds. Do slow work after you have responded.

Events & payloads

Envelope

Every delivery has the same outer shape. event_id identifies the event; data depends on the event type.

{
  "event": "link.created",
  "event_id": "evt_8f2k9m3n4b7c1d5e",
  "created_at": "2026-10-05T08:34:31.120Z",
  "data": {
    "id": 48291,
    "slug": "summer-sale",
    "domain": "lnki.io",
    "destination_url": "https://example.com/summer-sale",
    "title": "Summer sale landing page",
    "short_host_path": "lnki.io/summer-sale",
    "archived": false,
    "click_count": 0,
    "favorite": false,
    "folder_id": null,
    "utm_campaign_id": null,
    "utm_channel_id": null,
    "expires_at": null,
    "expired": false,
    "password_protected": false,
    "created_at": "2026-10-05T08:34:31.011Z",
    "unique_click_count": 0,
    "tag_ids": [],
    "tags": [],
    "tag_id": null
  }
}

Click batches

Clicks can arrive quickly, so they are grouped: one delivery carries up to 50 clicks, and a batch is sent at least every 5 seconds while clicks are coming in. Subscribe to link.clicked; the deliveries you receive are named link.clicked.batch.

{
  "event": "link.clicked.batch",
  "event_id": "evt_1c7d9e2f6a4b8c3d",
  "created_at": "2026-10-05T10:30:05.412Z",
  "data": {
    "batch": true,
    "count": 1,
    "clicks": [
      {
        "link_id": 48291,
        "short_url": "lnki.io/summer-sale",
        "destination_url": "https://example.com/summer-sale",
        "clicked_at": "2026-10-05T10:30:00.000Z",
        "country_code": "US",
        "referrer_host": "twitter.com",
        "device": "mobile"
      }
    ]
  }
}

Verify signatures

Anyone who learns your endpoint URL could post to it, so check that each delivery really came from Lnki.io. Every request is signed with the webhook's secret and carries these headers:

Compute the same HMAC over the raw body bytes, before any JSON parsing, and compare it to the header with a constant-time comparison.

import crypto from "node:crypto"
import express from "express"

const app = express()

// Keep the raw body: the signature is computed over the exact bytes sent.
app.post("/webhooks/lnki", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.LNKI_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex")
  const received = req.get("X-Lnki-Signature") || ""

  const valid = expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  if (!valid) return res.sendStatus(401)

  const event = JSON.parse(req.body)
  // Handle event.event and event.data here.
  res.sendStatus(200)
})

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)


@app.post("/webhooks/lnki")
def lnki_webhook():
    # request.get_data() is the raw body: sign the exact bytes sent.
    expected = "sha256=" + hmac.new(
        os.environ["LNKI_WEBHOOK_SECRET"].encode(),
        request.get_data(),
        hashlib.sha256,
    ).hexdigest()
    received = request.headers.get("X-Lnki-Signature", "")

    if not hmac.compare_digest(expected, received):
        abort(401)

    event = request.get_json()
    # Handle event["event"] and event["data"] here.
    return "", 200

require "openssl"
require "json"
require "sinatra"

post "/webhooks/lnki" do
  # The raw body: sign the exact bytes sent.
  body = request.body.read
  expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("LNKI_WEBHOOK_SECRET"), body)
  received = request.env["HTTP_X_LNKI_SIGNATURE"].to_s

  halt 401 unless Rack::Utils.secure_compare(expected, received)

  event = JSON.parse(body)
  # Handle event["event"] and event["data"] here.
  status 200
end

<?php
// The raw body: sign the exact bytes sent.
$body = file_get_contents("php://input");
$expected = "sha256=" . hash_hmac("sha256", $body, getenv("LNKI_WEBHOOK_SECRET"));
$received = $_SERVER["HTTP_X_LNKI_SIGNATURE"] ?? "";

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Handle $event["event"] and $event["data"] here.
http_response_code(200);

Delivery & retries

A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds.

• Expect duplicates. A retry can arrive after your server already processed the event but answered too late. Store X-Lnki-Delivery-Key and skip keys you have seen.
• Do not rely on order. Events are sent as they happen, but retries can make them arrive out of order. Use created_at if order matters.
• Failing webhooks are stopped. After 5 events in a row fail every attempt, the webhook is marked Failed and receives nothing until you resume it in the dashboard. You get a notification when that happens.
• Every attempt, with its response code and duration, is listed in the webhook's delivery log.

Plans & limits

What each plan includes for developers. See Pricing for everything else.