LinkScale API (1.7.2)

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

LinkScale uses a secure, three-step upload process with Uploadcare CDN for optimal performance and security.

Quick Start Guide

Step 1: Get Upload Signature

PUT /api/v1/assets
Body: { "expiration_minutes": 10 }
→ Returns: upload_config with signature

Step 2: Upload to Uploadcare

POST upload_config.upload_url
FormData with: file, signature, public_key, metadata
→ Returns: { "file": "uuid-file-id" }

Step 3: Poll for Validation

GET /api/v1/assets/{file_id}
Poll every 2 seconds until 200 OK (usually 2-3 seconds)
→ Returns: Complete asset with CDN URL

Why This Approach?

• Security: Time-limited signatures prevent unauthorized uploads
• Performance: Direct CDN upload, no server bottleneck
• Scalability: Files never transit through your server
• Reliability: Automatic validation and metadata extraction
• Flexibility: Support for images, videos, documents, and more

Supported File Types

• Images: PNG, JPEG, GIF, WebP, SVG (with dimensions, format, DPI)
• Videos: MP4, WebM, MOV (with duration, bitrate, codecs)
• Audio: MP3, WAV, OGG, M4A (with duration, bitrate)
• Documents: PDF, JSON, XML, TXT, CSV

Complete Implementation

See the detailed documentation in the Assets endpoints for complete code examples in JavaScript/Node.js.

LinkScale provides powerful dynamic features that allow you to reuse templates and configurations while customizing specific elements per link.

Dynamic Informations

Override specific template properties (name and profile picture) while maintaining the template's design. This is particularly useful when using the same template (cs_template) for multiple links but with different profile information.

Use Case: You have a company template with standard branding, but want to create personalized links for different team members with their own names and profile pictures.

Key Features:

• Override template name with custom display name
• Override template profile picture with custom image
• Granular control over profile picture styling (size, borders, etc.)
• Master toggles to enable/disable overrides
• Only works when cs_template is specified

Example:

{
  "cs_template": "507f1f77bcf86cd799439011",
  "dynamic_informations": {
    "enabled": true,
    "pp_enabled": true,
    "n": "John Doe",
    "pp": {
      "url": "https://cdn.example.com/john.jpg",
      "enabled": true,
      "size": 150,
      "border": {
        "color": "#4A90E2",
        "style": "solid",
        "width": 3
      }
    }
  }
}

Dynamic Links

Dynamically manage and customize link arrays within your landing pages for flexible content management.

How the /api/v1/.../logs endpoints work, why they scale, and the caveats you should know before promising things to API consumers.

---

TL;DR — How the system works (for API consumers)

A LinkDM user creates an API key in their dashboard and ships it with every request. The key authenticates the call, scopes it to their project, and grants per-resource permissions. The endpoint returns visit logs from ClickHouse, paginated 100 at a time, newest-first, with raw IPs masked (12.**.**.78) and each visit's recent button clicks already merged in.

How a consumer integrates — 30 seconds

curl https://app.linkdm.me/api/v1/links/<LINK_ID>/logs?limit=100 \
  -H "Authorization: Bearer lk_xxxxxxxxxxxx"

{
  "success": true,
  "data": [
    {
      "_id": "65f1a2…",
      "timestamp": "2026-04-28T11:42:13.512Z",
      "country": "FR",
      "city": "Paris",
      "ip": "82.**.**.117",
      "userAgent": "Mozilla/5.0 …",
      "device_type": "mobile",
      "bot": 0,
      "host": "linkdm.me",
      "referer": "https://t.co/…",
      "clicks": [
        { "url": "https://example.com", "btn_id": "btn_a", "created_at": "…", "is_final": 1 }
      ]
    }
  ],
  "next_cursor": "2026-04-28T11:42:13.512Z",
  "has_more": true
}

To walk every page, loop with the next_cursor until has_more === false:

let cursor = null;
do {
  const url = `https://app.linkdm.me/api/v1/links/${linkId}/logs?limit=100${cursor ? `&last_timestamp=${encodeURIComponent(cursor)}` : ''}`;
  const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
  const { data, next_cursor, has_more } = await res.json();
  for (const visit of data) { /* process */ }
  cursor = next_cursor;
} while (cursor);

What the consumer must know

Limit	Value	Why
Max history window	30 days	ClickHouse perf guardrail; older data not retrievable through this endpoint
Page size	100 max (default 100)	Bounds memory + response size
Rate limit	2 req/s per API key	Backpressure on ClickHouse
from/to window	31 days max	Joi-enforced, returns 400 if exceeded
Clicks per visit	50 max in clicks[]	One hot visit can't blow up the response
IP format	always masked	Raw IPs never leave the server (IPv4: a.**.**.d, IPv6: aaaa:bbbb:****:…:zzzz)

HTTP status codes

Code	When
200	Success
400	Validation error (bad cursor, bad limit, bad date range)
401	Missing / malformed / unknown / inactive API key
403	API key lacks logs.read_link / logs.read_folder / logs.read_project permission
404	link_id / folder_id doesn't belong to the caller's project
429	Rate limit (2 rps) exceeded; Retry-After: 1
500	Unexpected server error (ClickHouse down, etc.)

The auth flow under the hood

1. Consumer sends Authorization: Bearer lk_xxxxx.
2. Server SHA-256-hashes the key and looks it up in projects_api_keys (Mongo). Raw keys are never stored.
3. The matched key's permissions object (e.g. { logs: { read_link: true } }) is loaded onto the request.
4. Per-scope permission is checked (logs.read_project for /logs, logs.read_link for /links/:id/logs, etc.). Scope-strict — read_project does not grant read_link.
5. The query is restricted to project_id = <caller's project> at the SQL level. A consumer cannot read another tenant's data even by guessing IDs.
6. Every request is recorded in projects_api_logs for audit.

---

Endpoints

Endpoint	Scope
GET /api/v1/logs	All visits across the project
GET /api/v1/links/:link_id/logs	One link's visits
GET /api/v1/folders/:folder_id/logs	All visits for links in one folder

All three share one controller (src/controllers/public-api/logs/getLogsController.js) and one ClickHouse helper (src/lib/helpers/stats/clickhouseLogs.js).

---

Authentication & rate limiting

• Authorization: Bearer lk_xxxxx (validated against api_keys in MongoDB).
• Per-scope permission required: logs.read_project, logs.read_folder, logs.read_link.
• Rate limit: 2 requests / second / API key (enforced in handleApiKeyRoute.js).
• All requests are written to projects_api_logs for audit.

At the rate limit, the practical ceiling is 200 visits/second per key — fine for almost any sane export job.

---

Query parameters

Param	Default	Notes
limit	100	Min 1, max 100.
last_timestamp	—	Cursor for the next page (see below).
from, to	—	ISO datetimes. Optional, but capped by the date-range limit middleware.
source	visits	visits (one row per visit, with embedded clicks[]) or clicks (one row per click event).
country	—	ISO country code. Only honored on source=visits.
visitor_type	all	humans / bots / all. Only honored on source=visits.

---

Response envelope

{
  "success": true,
  "data": [ /* up to `limit` rows, newest first */ ],
  "next_cursor": "2026-04-28T11:42:13.512Z",
  "has_more": true
}

• next_cursor = the timestamp of the last row, or null when the page is partial.
• has_more = true while a full page is returned. May produce one false-positive empty page on the boundary (no data is lost).

Row shape (source=visits)

Top-level visit fields: _id, timestamp, country, city, u, referer, bot, host, project_id, id (link_id), userAgent, device_type, ip (masked), prx, vpn, vpn_org, vpn_provider, blocked, spam, url_params, clicks[].

clicks[] carries up to 50 most recent clicks per visit, each with: url, btn_id, position, btn_v, action_type, is_final, created_at.

IP masking

• Raw IPs are stored in ClickHouse but never leave the server.
• IPv4: 12.34.56.78 → 12.**.**.78
• IPv6: 2a01:cb00:1234:5678:9abc:def0:1234:5678 → 2a01:cb00:****:****:****:****:****:5678
• IPs embedded in userAgent / referer strings are also masked by regex replacement.

---

Pagination — how to walk

GET /api/v1/links/<id>/logs?limit=100
Authorization: Bearer lk_xxx

Save next_cursor from the response, then:

GET /api/v1/links/<id>/logs?limit=100&last_timestamp=<next_cursor>

Stop when has_more === false (or data is empty).

The cursor is just the timestamp of the last row, opaque to the client. The server filters with WHERE timestamp < parseDateTime64BestEffort(<cursor>) and orders DESC — so each page is the next 100 rows older than the last one returned.

---

Why this is fast (the ClickHouse side)

stats table:

• Sort key: (project_id, timestamp, link_id, user_id)
• Partitioned monthly on timestamp
• Bloom-filter index on link_id and mongo_id

clicks_stats table:

• Sort key: (project_id, created_at, link_id, mongo_id)
• Bloom-filter index on stats_id and link_id
• ReplacingMergeTree

The cursor query

SELECT … FROM stats
WHERE timestamp >= now() - INTERVAL 30 DAY
  AND project_id = ?
  AND link_id = ?           -- when scoped to a link
  AND timestamp < <cursor>  -- when paginating
ORDER BY timestamp DESC
LIMIT 100

hits the sort-key prefix (project_id, timestamp, …), so ClickHouse only reads the relevant granules from one or two monthly partitions — not the table.

The follow-up clicks query

SELECT … FROM clicks_stats WHERE stats_id IN (<≤100 ids>)

uses the bloom-filter index on stats_id to skip granules that don't contain any of those IDs. One batched query for all 100 visits, never N+1. A ROW_NUMBER() OVER (PARTITION BY stats_id ORDER BY created_at DESC) window caps the result at 50 clicks per visit so a single hot visit can't blow up the response.

Bounds, in plain numbers

For a single page (limit=100):

• 1 ClickHouse scan over ≤2 monthly partitions of stats, returning ≤100 rows.
• 1 ClickHouse scan over clicks_stats with a bloom-filtered stats_id IN (…), returning ≤5,000 rows (100 × 50).
• Network: ~few hundred KB at most.
• Wall time: typically tens of ms; worst-case low hundreds.

ClickHouse is sized for this. The 30-day fence + sort-key prefix is what keeps the first query bounded.

---

What's solid

Auth & authorization

• API key delivered as Bearer lk_xxxxx. Header format is regex-validated (/^Bearer\s+lk_[A-Za-z0-9]+$/) and length-capped at 256 chars before any DB lookup, so malformed input never reaches Mongo (handleApiKeyRoute.js).
• Stored as sha256(api_key) in projects_api_keys (apiKeyAuth.js). Plaintext keys never logged, even in dev mode.
• Auth aggregation requires is_active: true, plus successful $lookup joins to both users and projects (preserveNullAndEmptyArrays: false). A deleted user or project = 401.
• Permissions are loaded into req.api_key_permissions at auth time; the controller then checks logs.read_project / read_folder / read_link per scope. Permissions are scope-strict — read_project does not grant read_link.
• Cross-tenant isolation: project_id = req.project.project_id is hardcoded into every WHERE clause. The link-scope endpoint additionally verifies the link belongs to the project via Mongo (links.findOne({ _id, project_id })) before issuing the ClickHouse query — a user can't read another tenant's link by guessing the ObjectId.

SQL safety

• Every user-supplied string is wrapped in esc() before substitution. esc() escapes both backslash and single-quote (via backslash, which ClickHouse accepts inside single-quoted literals). A trailing backslash in country or any other field cannot break out of the string literal.
• Joi validates types and lengths upstream of esc():
  • country — string().max(10)
  • last_timestamp — string().isoDate().max(64) (so the cursor can't be a 1MB string and can't be malformed datetime → returns 400, not 500)
  • limit — integer().min(1).max(100)
  • source / visitor_type — strict enum
  • from / to — ISO 8601, plus a 31-day window cap from withDateRangeLimit
• link_id and folder_id are validated with ObjectId.isValid before they touch SQL.
• Audit log writes (projects_api_logs) use the validated query object, so a malicious last_timestamp can't bloat Mongo storage.

Performance bounds

• Sort keys and bloom indexes line up with every WHERE clause the controller emits — no full scans on a healthy table.
• 30-day fence is unconditional (see Caveats §1).
• Clicks-per-visit cap of 50 (ROW_NUMBER window) prevents one hot visit from blowing up the response.
• One batched query for visits, one batched query for their clicks. Never N+1.
• Rate limit (2 rps/key) gives ClickHouse natural backpressure — burst is bounded.

Data privacy

• Raw IPs never leave the server. Masked at serialization (maskIp for direct-IP fields, maskIpAddresses for IPs embedded in userAgent/referer).
• Masking covers IPv4 (12.**.**.78), IPv6 (2a01:cb00:****:…:5678), and click-level ip fields when present.

Pagination correctness

• Cursor works on both source=visits (cursor column timestamp) and source=clicks (cursor column created_at, aliased back to timestamp in the response).
• Country/bot filters are correctly skipped for source=clicks because those columns don't exist on clicks_stats (instead of erroring).

---

Known caveats — read these before promising anything

1. 30-day hard ceiling

The ClickHouse query unconditionally adds timestamp >= now() - INTERVAL 30 DAY (in clickhouseLogs.js). Visits older than 30 days cannot be retrieved through this endpoint, even with explicit from/to parameters. This is a perf guardrail — removing it would let one bad query scan the whole table. If a longer window is needed, the right move is a separate "export job" path that runs async.

2. country / visitor_type only work on source=visits

Those columns don't exist on clicks_stats. The controller now silently ignores those filters when source=clicks rather than 500'ing — but the consumer needs to know. If you need country-filtered clicks, fetch with source=visits and reduce client-side.

3. Cursor tie-breaking

Cursor is timestamp only. timestamp is DateTime64(3) (millisecond precision). If two visits land in the exact same millisecond on the cursor boundary, one could be skipped by the next page. In real traffic this is essentially never observed, but it's not zero. If it ever matters, the fix is a (timestamp, mongo_id) tuple cursor — non-trivial change, not worth doing pre-emptively.

4. has_more=true boundary false-positive

If the very last page contains exactly limit rows, has_more will be true and the next call returns data: [] with has_more: false. No data is lost — clients just get one extra empty round-trip on the exact-multiple boundary.

5. Click cap per visit

A visit with >50 clicks will only show the 50 most recent in clicks[]. The total click count isn't separately surfaced; if a consumer needs the raw count, they have to use source=clicks and count.

6. Rate limit is a soft cap

The limiter is find over projects_api_logs with created_at >= now-1s. If MongoDB is unavailable, it fails open — the request proceeds. Acceptable because ClickHouse-side bounds protect the database, but worth knowing.

7. Permissions snapshot at auth time

Permissions are loaded once at auth and used for the lifetime of the request. If a permission is revoked between auth and the controller running, that single in-flight call still proceeds with the old permission. The next call sees the new permissions. Standard behavior.

8. Folder existence is not asserted

folder_id is validated as a syntactically valid ObjectId, but we don't check that the folder belongs to the project — instead we filter the links query by project_id. A folder from another project simply returns zero links → data: []. No data leak, but a caller can't distinguish "folder doesn't exist" from "folder is empty" or "folder belongs to another tenant". Acceptable trade-off, but document it for API consumers if needed.

---

What to do if it ever stops being fast

1. Run scripts/clickhouse/diagnostics/diagnose_clicks_stats_schema.js — confirms sort key + indexes are still in place.
2. Check system.query_log for the slow query: bloom-filter granule pruning ratio should be high. If not, the bloom index has degraded — OPTIMIZE TABLE clicks_stats FINAL can help (heavy operation, schedule it).
3. Verify the 30-day fence is still emitted (grep "INTERVAL 30 DAY" src/lib/helpers/stats/clickhouseLogs.js). Removing it is the most common cause of "why did logs get slow".

---

Audit log (defects found + fixed during the hardening pass)

#	Severity	Defect	Fix
1	Bug	?source=clicks silently ignored last_timestamp — pagination broken on the clicks branch	Cursor now applies to both sources, using created_at as the column for clicks
2	Bug	?country= and ?visitor_type= filters were injected into the clicks_stats query, which has no such columns → 500 on those param combos	Filters scoped to source=visits only; silently ignored for clicks
3	Soft DoS	esc() only escaped single quotes; a trailing \ could break out of the string literal and crash the SQL parser as a 500	esc() now escapes backslash first, then single quote (both via backslash, ClickHouse-accepted)
4	Hardening	last_timestamp was Joi.string().optional() — accepted any length, any content, only failed at ClickHouse parse time	Now Joi.string().isoDate().max(64).optional() — rejected as 400 with a clear message
5	Spec compliance	Default limit was 30, next_cursor / has_more not in response, IP was deleted instead of masked	Default 100; envelope now includes next_cursor + has_more; IP masked as 12.**.**.78

Looking for practical examples and ready-to-use scripts? Visit our GitHub organization for concrete implementations:

🔗 LinkScale GitHub - Code Examples

You'll find:

• Complete upload workflows with Node.js implementations
• Link management scripts for batch operations
• Integration examples for common use cases
• Real-world scenarios and best practices

These repositories provide production-ready code you can use as a foundation for your own implementations.