tinco.it

tinco.it API

REST API, JSON, version 1. Available on the Pro and Business plans.

My keys →

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).

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.

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" } }
HTTPcodeWhen
400invalid_jsonThe body isn't valid JSON or Content-Type: application/json is missing.
401unauthorizedMissing, wrong or revoked key.
403plan_required / insufficient_scope / forbidden / key_owner_removed / plan_limitThe plan, the key's permissions or the role don't allow the operation.
404not_foundThe link doesn't exist in the key's workspace.
422validation_failedInvalid data; field says which field.
429rate_limitedToo many requests; retry after Retry-After seconds.