ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
LinkSnap Docs
⌘K

Concepts

This page covers the building blocks of LinkSnap: what each object is, how they relate, and the lifecycle they go through. Read this before going deep on any specific feature — the rest of the docs assume you know what a short link is and how it differs from a QR code.

The data model

Workspace
  ├── ShortLinks
  │     ├── Tags (many-to-many)
  │     └── Clicks (telemetry)
  ├── QrCodes
  │     ├── (optional) ShortLink reference
  │     └── Scans (telemetry)
  ├── Domains (custom shortener domains)
  ├── ApiKeys
  └── Members

Everything is scoped to a workspace. Cross-workspace queries don't exist — if you operate two brands, you'll have two workspaces and treat them as fully separate.

Workspace

A workspace is the top-level tenant boundary. Each workspace has:

  • Its own short links and QR codes
  • Its own tag vocabulary
  • Its own custom domains
  • Its own API keys
  • Its own team members
  • Its own plan (FREE, PRO, or BUSINESS) and billing relationship with Plugipay

Workspaces are isolated. Data never crosses between them.

You can be a member of multiple workspaces. Switching is done via the top-left workspace switcher in the dashboard.

ShortLink

A short link is the central object in LinkSnap. It maps a slug under one of your shortener domains to a destination URL.

A short link has:

  • A slug (the path after the domain, e.g. promo)
  • A destination URL (where visitors are redirected)
  • An optional domain reference (defaults to lksn.app)
  • An optional title and description
  • A list of tags
  • An optional expiry timestamp — after which the link returns a 410 Gone
  • An optional maxClicks — after which the link returns a 410 Gone
  • A status: active, expired, or archived
  • A createdAt and lastClickAt

Identifier: short links use the slug as their natural ID within a domain. The API accepts both the database ID and the slug for lookups.

Slugs are scoped per domain. lksn.app/promo and go.acme.com/promo are two different links, even in the same workspace.

QrCode

A QR code is a generated PNG or SVG image that encodes a URL. It can wrap a LinkSnap short link (recommended — you get analytics) or any arbitrary URL.

A QR code has:

  • A target URL (or a reference to a short link)
  • A label for your own organization
  • Styling: foreground color, background color, optional logo
  • A format: PNG (default) or SVG (PRO and BUSINESS)
  • A download token for time-bounded direct downloads
  • Scan telemetry, same shape as link clicks

Identifier: qr_<id>.

When a QR code points at a short link, scans count both toward the link's click stats and the QR code's scan stats — they share the same redirect path.

Plan caveats:

  • FREE: 2 QR codes per month, watermarked, PNG only.
  • PRO: 500 QR codes per month, no watermark, optional logo, SVG export.
  • BUSINESS: unlimited.

Tag

A tag is a free-form label attached to one or more short links. Tags are workspace-scoped.

Use cases:

  • Group by campaign (black-friday-2026)
  • Group by channel (twitter, email-newsletter)
  • Group by status (needs-review)

Tags are created implicitly when you add one to a link. The Tags page in the portal lists every tag with its link count and lets you rename or delete them.

Domain

A domain is a custom shortener domain you've connected to LinkSnap. Once verified, you can issue short links under it.

A domain has:

  • A hostname (e.g. go.acme.com)
  • A status: pending, verifying, active, failed
  • A TLS state (managed by us via Let's Encrypt)
  • A DNS verification record you add to your DNS provider

Domain provisioning is a four-step flow: add → verify DNS → await TLS → activate. See Portal → Custom domains for the full walkthrough.

Plan caveats:

  • FREE: no custom domains (use the default lksn.app).
  • PRO: one custom domain.
  • BUSINESS: unlimited.

Click and scan telemetry

Every redirect — whether from a short link visit or a QR code scan — produces a telemetry record. Each record captures:

  • Timestamp
  • Country (resolved from IP, never the raw IP)
  • Device type (desktop, mobile, tablet)
  • Browser and OS family
  • Referrer host (when present and non-empty)
  • The short link or QR code that served the redirect

Telemetry powers the per-link stats page, the workspace dashboard, and the analytics API. We retain records indefinitely on PRO and BUSINESS; FREE retains 30 days.

ApiKey

An API key authenticates server-to-server calls. Keys are workspace-scoped.

A key has:

  • A label (your name for it)
  • A secret (lk_live_xxx — shown once at creation)
  • A createdAt and lastUsedAt

Keys authenticate as a Bearer token in the Authorization header. See API → Authentication.

Why this matters

The model isn't ornamental — it shapes how you build integrations:

  • Bulk operations dispatch on link IDs; you don't loop one-at-a-time.
  • Tag filters are first-class query params on every list endpoint.
  • Stats queries take a link slug or QR code ID and a date range — identical shape.
  • Custom domain routing happens at the edge, so adding one doesn't require any code change on your side.

Once you have this mental model, the rest of the docs are linear — each portal page, each API endpoint, each SDK method maps cleanly to one of these objects.

Next