tinco.it API
REST API, JSON, version 1. Available on the Pro and Business plans.
Authentication
Create a key in Dashboard → API and send it in theAuthorization header. The key works in the workspace where it was created, with the role of the person who created it. Don't put it in code that runs in the browser.
curl https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…"Limits: 60 requests per minute per key (Pro), 300 (Business). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining andX-RateLimit-Reset (Unix timestamp).
Links
POST/links
Create a link. Only url is required; without alias, a code is generated. The destination goes through the same anti-abuse checks as in the dashboard.
curl -X POST https://www.tinco.it/api/v1/links \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/offer","alias":"offer","tags":["newsletter"]}'Response 201:
{
"id": "5c1f…",
"short_url": "https://tinco.it/offer",
"domain": "tinco.it",
"key": "offer",
"url": "https://example.com/offer",
"title": null,
"tags": ["newsletter"],
"archived": false,
"clicks": 0,
"status": "active",
"created_at": "2026-11-16T10:00:00.000Z"
}status: active, pending_check (the safety check is in progress; the link works) or disabled.
GET/links
List of links, newest first, 20 per page. Optional parameters: q (searches address, destination, title), tag, archived=true, page.
{ "data": [ … ], "page": 1, "pages": 3, "total": 52, "per_page": 20 }GET/links/{id}
A single link.
PATCH/links/{id}
Changes only the fields you send: url, alias, title, tags (replaces the list), archived. The change applies to the redirect immediately.
curl -X PATCH https://www.tinco.it/api/v1/links/5c1f… \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/new-offer"}'DELETE/links/{id}
Deletes the link permanently (204 response). Requires an admin role; the short address stays reserved and can't be used again. To just stop it, use PATCH with {"archived": true}.
GET/links/{id}/stats
Analytics without bots. interval: 7z (7 days), 30z (default), 90z, 12l (12 months). timezone: an IANA time zone (e.g. Europe/London), default Europe/Bucharest; days and hours (hourly: 0–23, summed over the period) use it.
{
"interval": { "id": "30z", "from": "2026-10-18", "to": "2026-11-16", "timezone": "Europe/Bucharest" },
"clicks": 1250, "clicks_previous_period": 980, "unique_visitors": 1032,
"daily": [ { "day": "2026-10-18", "clicks": 31, "unique_visitors": 27 }, … ],
"hourly": [ { "hour": 0, "clicks": 12 }, … { "hour": 23, "clicks": 40 } ],
"breakdowns": {
"country": { "top": [ { "value": "RO", "clicks": 1100 }, … ], "other": 12 },
"device": …, "os": …, "browser": …, "referrer": …, "region": …, "city": …, "via": …,
"utmSource": …, "utmMedium": …, "utmCampaign": …, "variant": …
}
}GET/links/{id}/qr
The link's QR code, as SVG, with the design saved in the dashboard. Scans are counted separately in analytics.
Webhooks
Available on the Business plan, from Dashboard → API. For every event we send a JSON POST. Events: link.created, link.updated, link.deleted, link.clicked (real visitors only, no bots) and ping (the “Test” button).
POST /webhooks/tinco
Content-Type: application/json
Tinco-Event: link.clicked
Tinco-Delivery: 7d0c… (unique per event; stays the same on retries)
Tinco-Signature: t=1794835200,v1=5f2b…
{
"id": "evt_9a1e…",
"type": "link.clicked",
"created_at": "2026-11-16T10:00:00.000Z",
"workspace_id": "…",
"data": {
"link": { "id": "…", "short_url": "https://tinco.it/offer", "url": "https://example.com/offer" },
"click": { "timestamp": "…", "country": "RO", "city": "Bucharest", "device": "mobile", "os": "iOS",
"browser": "Mobile Safari", "referrer": "facebook.com", "qr": false, "variant": null, "utm": {} }
}
}Verify the signature
Compute HMAC-SHA256 with the webhook secret over `${t}.${raw body}` and compare with v1. Reject requests whose t is older than 5 minutes (replay protection).
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Respond with a 2xx code within 5 seconds. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Redirects aren't followed. After 50 consecutive failures the webhook stops automatically; restart it from the dashboard. Delivery order isn't guaranteed: use Tinco-Delivery to ignore duplicates.
Errors
Error messages are in English. code is stable (for your logic); reason gives the exact cause (e.g. aliasTaken) and field the field in question.
{ "error": { "code": "validation_failed", "message": "This alias is already taken. Pick another one.", "reason": "aliasTaken", "field": "alias" } }| HTTP | code | When |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON or Content-Type: application/json is missing. |
| 401 | unauthorized | Missing, wrong or revoked key. |
| 403 | plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limit | The plan, the key's permissions or the role don't allow the operation. |
| 404 | not_found | The link doesn't exist in the key's workspace. |
| 422 | validation_failed | Invalid data; field says which field. |
| 429 | rate_limited | Too many requests; retry after Retry-After seconds. |