Server API

Server API umožňuje vašemu backendu číst identifikační data, která už TRACIO pro váš workspace nasbíralo: historii návštěvníka, jednotlivé relace a čítače velocity za krátká okna.

Doplňuje Webhooky, nenahrazuje je:

Obě rozhraní jsou k dispozici od tarifu Pro výše.

Základní URL

https://api.tracio.ai/v1

Jde o jiný host než endpoint pro prohlížeč (edge.tracio.ai) a než dashboard (app.tracio.ai). Všechny tři jsou oddělené: prohlížeč mluví s edge pomocí vašeho veřejného klíče, váš backend mluví se Server API pomocí vašeho tajného klíče.

Autentizace

Každý požadavek nese váš tajný klíč jako bearer token:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Server API je výhradně server-to-server. Hlavičky CORS se záměrně nevracejí, takže ji prohlížeč nemůže zavolat — právě to drží váš tajný klíč mimo kód na straně klienta. Tajný klíč nikdy neposílejte do prohlížeče.

Získání tajného klíče

Vytvořte jej v dashboardu v sekci API Keys a zvolte typ secret.

• Celý klíč se zobrazí právě jednou, při vytvoření. Na naší straně je uložen jen hash, takže ztracený klíč nelze obnovit — místo toho jej rotujte.
• Tajný klíč vypadá jako tracio_sk_ následované 43 znaky, celkem 53. Dashboard jej vypisuje podle prvních několika znaků, abyste klíče od sebe rozeznali.
• Tajné klíče vyžadují tarif Pro nebo vyšší; veřejný klíč, který používá agent v prohlížeči, je samostatná, netajná hodnota o 40 znacích.

Rotace tajného klíče

Rotace vydá nový klíč a starý nechá funkční ještě 7 dní, takže jej můžete nasadit bez výpadku. Nasaďte nový klíč, ověřte, že se provoz přesunul, a nechte starý vypršet. Veřejné klíče rotovat nelze — nejsou to tajemství a ve zdroji vaší stránky jsou vidět záměrně.

Endpointy

Každá routa je GET. Ve Server API nejsou žádné zápisové operace: čte data, zatímco vaše konfigurace žije v dashboardu.

Koncové lomítko se přijímá a ignoruje. Neznámá cesta nebo špatná metoda vrací stejnou chybovou JSON obálku jako všechno ostatní, nikdy HTML stránku ani prostý text.

Časové okno

Každé čtení je ohraničeno časovým oknem, které řídí dva volitelné parametry dotazu:

• Samotné datum v to zahrnuje celý ten den.
• Cokoli jiného je odmítnuto s 400 invalid_request a zprávou time must be YYYY-MM-DD or RFC3339.
• Když nepředáte ani jeden, oknem je celá doba uchovávání vašeho tarifu, končící teď.
• Okno sahající dál do minulosti, než váš tarif dovoluje, se mlčky zkrátí, místo aby bylo odmítnuto. Skutečně použité okno se vždy vrací v meta, takže kontrolujte meta.from a meta.to, místo abyste předpokládali, že váš požadavek byl splněn doslova.

Vyhledání návštěvníka

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Odpověď nese agregovanou historii a vkládá do sebe poslední relaci, takže běžný případ potřebuje jeden požadavek místo dvou:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Návštěvník bez dat uvnitř okna uchovávání vrací 404 not_found se zprávou visitor not found in the retention window — to není chyba ve vaší integraci, znamená to, že návštěvník je nový nebo mu data stářím vypadla z okna.

Pole verdiktu

Relace nese dva verdikty a každý odpovídá na jinou otázku — zda byl klient automatizovaný a k čemu celkově dospěl rizikový engine:

bot.score i decision.riskScore běží na škále 0..100. Na Business a vyšších z nich guidance dělá doporučení pro jednotlivé scénáře na žebříčku allow → challenge → review → deny — význam jednotlivých příček najdete v části Guidance.

Výpis relací návštěvníka

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&minRiskScore=50"

Relace se vracejí od nejnovějších:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Stránkování

Stránkuje se pomocí kurzoru. Parametr page ani offset neexistuje: pošlete zpět nextCursor, který jste dostali, jako cursor, a pokračujte, dokud je hasMore true.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

Ke kurzoru se chovejte jako k neprůhlednému — jeho obsah je implementační detail a může se změnit. Upravený kurzor je odmítnut s 400 invalid_request a zprávou malformed cursor.

Načtení jedné relace

Té nejnovější:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Vrací holý objekt relace — ne pole a ne zabalený v obálce. Návštěvník bez relací v okně vrací 404 not_found s no sessions for this visitor in the retention window.

Nebo podle requestId, identifikátoru, který se objevuje i v payloadu webhooku:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitorId=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitorId je zde volitelné, ale když jej znáte, jeho předání vyhledávání výrazně zrychlí.

Velocity

Velocity odpovídá na otázku „kolik toho tento návštěvník poslední dobou dělá“ — tedy na tvar credential stuffingu, testování karet a hromadných registrací.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window přijímá 1h, 24h nebo 7d a výchozí hodnota je 24h. Jakákoli jiná hodnota je odmítnuta s 400 invalid_request a window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts počítá odlišné hodnoty linkedId, které jste pro toto zařízení poslali — viz Propojení účtů. botEvents je Business a vyšší.

Konvence odpovědí

Chybějící pole znamená „žádná data“, nikdy nulu. Pole bez hodnoty se zcela vynechávají, místo aby se posílala jako 0, "" nebo null: zbrusu nový návštěvník nemá matchConfidence, čistá návštěva nemá antidetectScore ani suspectScore. Jedinou záměrnou výjimkou je bot.score, které je přítomno vždy, i když je nulové. Pole čtěte obezřetně.

Payload závisí na vašem tarifu. Každý tarif s přístupem k API dostává základní relaci — identifikátory, časové razítko, URL, IP, user agent, prohlížeč, operační systém, zařízení, geo, síť, bot, identifikaci a rozhodnutí. Pro přidává identification.matchType, identification.matchConfidence a bot.antidetectScore. Business a Enterprise přidávají geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo a pole na úrovni osoby (personId, reputation, linkedAccountsCount, linkedVisitorsCount). Chybějící pole z tarifu Business na tarifu Pro není chyba.

Vnitřnosti na úrovni signálů se nevracejí nikdy, v žádném tarifu: názvy jednotlivých signálů, jejich váhy, prahy stojící za verdiktem, surové hodnoty signálů i rozpad skóre zůstávají na naší straně. Skóre, které lze zpětně rozložit na své vstupy, přestává být užitečné jako obrana.

Chyby

Každé selhání používá jednu obálku:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Toto requestId není identifikátor návštěvy. Stejné jméno nesou dvě různé hodnoty: uvnitř payloadu relace je requestId UUID návštěvy, totéž, které doručuje webhook; uvnitř chybové obálky jde o 24znakový identifikátor trasování, vytvořený pro každé HTTP volání. Identifikátor trasování se vrací i v hlavičce X-Request-Id u každé odpovědi, úspěšné i neúspěšné. Uveďte jej, když se obracíte na podporu — právě podle něj vaše konkrétní volání najdeme.

Kontroly probíhají v pevném pořadí — klíč, pak tarif, pak limity — takže požadavek se špatným klíčem hlásí vždy nejdřív klíč, nikdy problém s kvótou.

Dva případy 401 se čtou záměrně jinak: missing Authorization: Bearer <secret key> znamená, že hlavička nikdy nedorazila, zatímco invalid or revoked API key znamená, že dorazila a neodpovídala. 402 nese Data API requires the Pro plan or higher.

Limity rychlosti a kvóty

Každá autentizovaná odpověď nese váš aktuální stav:

• Krátké nárazy jsou povolené: limit za sekundu je token bucket, který snese až trojnásobek trvalé rychlosti, než začne odmítat.
• Požadavek odmítnutý za překročení rychlosti za sekundu nespotřebuje denní kvótu, takže náraz nemůže sníst rozpočet dne.
• Limity Server API se počítají odděleně od identifikačního provozu. Čtení vlastní historie nikdy neutratí identifikace, které platíte.

Další kroky

• Webhooky — přijímejte každou identifikaci ve chvíli, kdy nastane
• Propojení účtů — připojte vlastní id účtu k zařízení
• Detekce botů — jak vzniká verdikt o botovi
• Soukromí a GDPR — vyřizování žádostí subjektů údajů