Data API

Data API (जिसे यहाँ पहले Server API के नाम से प्रलेखित किया जाता था) आपके बैकएंड को वह पहचान डेटा पढ़ने देता है जो TRACIO आपके वर्कस्पेस के लिए पहले ही एकत्र कर चुका है: किसी विज़िटर का इतिहास, अलग-अलग सेशन, और छोटी विंडो वाले वेलोसिटी काउंटर। कुछ रूट लिखते भी हैं — अकाउंट रिकॉर्ड, कस्टम फ़ील्ड और सूची प्रविष्टियाँ — ताकि आपका बैकएंड TRACIO की जानकारी को समृद्ध कर सके।

यह Webhooks की जगह नहीं लेता, बल्कि उनका पूरक है:

दोनों सतहें Pro प्लान और उससे ऊपर उपलब्ध हैं।

बेस URL

https://api.tracio.ai/v2

यह ब्राउज़र एंडपॉइंट (edge.tracio.ai) और डैशबोर्ड (app.tracio.ai) से अलग होस्ट है। तीनों अलग-अलग हैं: ब्राउज़र आपकी पब्लिक कुंजी के साथ edge से बात करता है, और आपका बैकएंड आपकी सीक्रेट कुंजी के साथ Data API से।

v1 से माइग्रेशन

/v1 रूट हटा दिए गए हैं। /v2 उपयोग करें: रूट वही हैं, और हर JSON कुंजी तथा क्वेरी पैरामीटर snake_case में है (visitor_id, risk_score, min_risk_score)। आपके अपने fields और labels शब्दकोशों के भीतर की कुंजियाँ आपका डेटा हैं और अपनी मूल वर्तनी बनाए रखती हैं। JavaScript SDK अपना camelCase इंटरफ़ेस बनाए रखता है।

प्रमाणीकरण

हर अनुरोध आपकी सीक्रेट कुंजी को bearer token के रूप में साथ ले जाता है:

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

Data API केवल सर्वर-टू-सर्वर है। CORS हेडर जान-बूझकर नहीं लौटाए जाते, इसलिए कोई ब्राउज़र इसे कॉल नहीं कर सकता — यही आपकी सीक्रेट कुंजी को क्लाइंट-साइड कोड से बाहर रखता है। सीक्रेट कुंजी को ब्राउज़र तक कभी न भेजें।

सीक्रेट कुंजी प्राप्त करना

इसे डैशबोर्ड में API Keys के अंतर्गत बनाएं, secret प्रकार चुनकर।

• पूरी कुंजी ठीक एक बार दिखाई जाती है, बनाते समय। हमारी ओर केवल एक हैश संग्रहीत होता है, इसलिए खोई हुई कुंजी वापस नहीं पाई जा सकती — उसकी जगह उसे रोटेट करें।
• सीक्रेट कुंजी tracio_sk_ और उसके बाद 43 वर्णों जैसी दिखती है, कुल 53। डैशबोर्ड इसे इसके पहले कुछ वर्णों से सूचीबद्ध करता है, ताकि आप कुंजियों में फ़र्क कर सकें।
• सीक्रेट कुंजियों के लिए Pro प्लान या उससे ऊपर आवश्यक है; ब्राउज़र एजेंट द्वारा उपयोग की जाने वाली पब्लिक कुंजी एक अलग, गैर-गुप्त 40-वर्ण मान है।
• कुंजी एक एनवायरनमेंट से बंधी होती है: प्रोडक्शन कुंजी staging के विज़िटर को नहीं देखती — उत्तर 404 होता है, ठीक वैसे ही जैसे मौजूद न होने वाले डेटा के लिए।

सीक्रेट कुंजी रोटेट करना

रोटेशन एक नई कुंजी जारी करता है और पुरानी को 7 दिन तक काम करने देता है, ताकि आप उसे बिना डाउनटाइम रोल आउट कर सकें। नई कुंजी डिप्लॉय करें, पुष्टि करें कि ट्रैफ़िक उस पर चला गया है, और पुरानी को समाप्त होने दें। पब्लिक कुंजियाँ रोटेट नहीं की जा सकतीं — वे गुप्त नहीं हैं और डिज़ाइन के अनुसार आपके पेज सोर्स में दिखती हैं।

एंडपॉइंट

वही कुंजी और होस्ट निर्णय API भी परोसते हैं, सभी snake_case में:

इनके परिणाम आप तक webhook इवेंट के रूप में भी पहुँचते हैं: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked और affiliate_threshold_crossed।

अंत में स्लैश स्वीकार किया जाता है और अनदेखा कर दिया जाता है। अज्ञात पथ या गलत मेथड वही JSON त्रुटि एनवेलप लौटाता है जो बाकी सब कुछ लौटाता है, कभी HTML या सादा-टेक्स्ट पेज नहीं।

समय विंडो

हर रीड एक समय विंडो से बंधा होता है, जिसे दो वैकल्पिक क्वेरी पैरामीटर नियंत्रित करते हैं:

• to के रूप में केवल तारीख देने पर वह पूरा दिन शामिल होता है।
• इसके अलावा कुछ भी 400 invalid_request और संदेश time must be YYYY-MM-DD or RFC3339 के साथ अस्वीकार कर दिया जाता है।
• जब आप दोनों में से कुछ नहीं भेजते, तो विंडो आपके प्लान की पूरी अवधारण अवधि होती है, जो इस क्षण पर समाप्त होती है।
• आपके प्लान की अनुमति से अधिक पीछे तक जाने वाली विंडो अस्वीकार नहीं की जाती, बल्कि चुपचाप सीमित कर दी जाती है। वास्तव में उपयोग की गई विंडो हमेशा meta में वापस बताई जाती है, इसलिए यह मान लेने के बजाय कि आपका अनुरोध अक्षरशः माना गया, meta.from और meta.to जांचें।

किसी विज़िटर को देखना

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

उत्तर समेकित इतिहास लाता है और नवीनतम सेशन को भी उसी में समाहित कर देता है, इसलिए सामान्य स्थिति में दो के बजाय एक ही अनुरोध चाहिए:

{
  "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "first_seen_at": "2026-05-02T10:11:12Z",
  "last_seen_at": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognito_visits": 3,
  "unique_ips": 5,
  "unique_countries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "max_risk_score": 63,
    "avg_bot_score": 12.5,
    "bot_sessions": 7,
    "last_decision": "real"
  },
  "network": {
    "vpn_seen": false,
    "proxy_seen": false,
    "tor_seen": false,
    "datacenter_seen": true,
    "proxy_detected_seen": true,
    "last_isp": "Deutsche Telekom",
    "last_real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  "last_session": {
    "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "account_id": "user_8842",
    "account": { "id": "user_8842", "email": "ann@example.com", "display_name": "Ann Lee" },
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "fields": { "order_ref": "A-1029" },
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "user_agent": "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",
    "gpu": "Apple M2",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "connection_type": "residential",
      "proxy_detected": true,
      "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "store_url": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetect_score": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "match_type": "exact",
      "match_confidence": 0.99
    },
    "device_info": {
      "device_id": "d_4f9c2e",
      "cross_browser": true,
      "confidence": 0.88,
      "linked_browsers": 2
    },
    "decision": { "action": "real", "risk_score": 12, "suspect_score": 3 }
  },
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

अवधारण विंडो के भीतर बिना किसी डेटा वाला विज़िटर 404 not_found और संदेश visitor not found in the retention window लौटाता है — यह आपके इंटीग्रेशन की त्रुटि नहीं है, इसका अर्थ है कि विज़िटर नया है या समय के साथ बाहर हो चुका है।

वर्डिक्ट फ़ील्ड

सेशन दो वर्डिक्ट लाता है, और वे अलग-अलग प्रश्नों का उत्तर देते हैं — क्या क्लाइंट स्वचालित था, और जोखिम इंजन ने कुल मिलाकर क्या निष्कर्ष निकाला:

bot.score और decision.risk_score दोनों 0..100 पर चलते हैं। Business और उससे ऊपर guidance इन्हें सीढ़ी allow → challenge → review → deny पर प्रति-परिदृश्य सलाह में बदल देता है — हर पायदान का अर्थ जानने के लिए देखें Guidance। मान और स्केल उसी विज़िट के v3 webhook बॉडी से मेल खाते हैं, और guidance उन्हीं नियमों से गणना किया जाता है।

किसी विज़िटर के सेशनों की सूची

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

सेशन नवीनतम पहले के क्रम में लौटते हैं:

{
  "items": [
    {
      "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "next_cursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "has_more": true,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

पेजिनेशन

पेजिंग कर्सर-आधारित है। कोई page या offset पैरामीटर नहीं है: आपको जो next_cursor मिला उसे cursor के रूप में वापस भेजें, और जब तक has_more सही है तब तक चलते रहें। अंतिम पेज में next_cursor शायद बिल्कुल न हो, इसलिए उस फ़ील्ड को अनिवार्य न बनाएं।

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

  do {
    const url = new URL(`https://api.tracio.ai/v2/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(`Data API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.has_more ? page.next_cursor : undefined
  } while (cursor)

  return sessions
}

कर्सर को अपारदर्शी मानें — उसकी सामग्री एक कार्यान्वयन विवरण है और बदल सकती है। संपादित किया गया कर्सर 400 invalid_request और संदेश malformed cursor के साथ अस्वीकार कर दिया जाता है।

डिवाइस के तथ्य

User-Agent से लिए गए ब्राउज़र और OS के साथ-साथ, एक सेशन वह भी रखता है जो विज़िटर का ब्राउज़र मशीन के बारे में बताता है, हमारी ओर से साफ़ किया हुआ। विज़िट ऐसा डेटा न लाए तो हर फ़ील्ड अनुपस्थित रहता है, इसलिए हर एक को वैकल्पिक मानें।

ब्राउज़र एक्सटेंशन

extensions उन ब्राउज़र एक्सटेंशनों को सूचीबद्ध करता है जो विज़िट के दौरान पकड़े गए — Pro और उससे ऊपर। हर प्रविष्टि एक ऑब्जेक्ट है:

कोई निष्कर्ष तभी बताया जाता है जब वह हमारी भरोसे की जाँचों में खरा उतरे — जो परिवेश हर जाँच पर "इंस्टॉल है" उत्तर देता है, या जो बैच बारह नामों से लंबा होता है, उसे अविश्वसनीय मानकर हटा दिया जाता है। इसलिए खाली या अनुपस्थित सूची का अर्थ है "ऐसा कुछ नहीं जिसकी हम पुष्टि कर सकें", न कि "कोई एक्सटेंशन इंस्टॉल नहीं है"। इसे प्रमाण की तरह पढ़ें, इन्वेंटरी की तरह नहीं।

कस्टम फ़ील्ड

fields में वे कस्टम की-वैल्यू जोड़े होते हैं जिन्हें आपके इंटीग्रेशन ने विज़िट के साथ जोड़ा है — जैसे ऑर्डर का रेफ़रेंस, प्लान का नाम, भुगतान का नतीजा। कुंजियाँ और मान हमेशा स्ट्रिंग होते हैं: जोड़ी गई संख्या या बूलियन मान टेक्स्ट रूप में लौटता है। सेशन के बाकी हिस्से की तरह यह API एक्सेस वाले हर प्लान (Pro और उससे ऊपर) में उपलब्ध है, और जब विज़िट में कोई फ़ील्ड नहीं होता तो यह मौजूद नहीं रहता।

fields हर अनुरोध पर लाइव पढ़ा जाता है, विज़िट के समय कॉपी नहीं किया जाता। विज़िट के बाद जोड़े गए फ़ील्ड (देखें विज़िट के बाद फ़ील्ड जोड़ना) भी यहाँ दिखते हैं, इसलिए उसी विज़िट के लिए fields में webhook द्वारा पहुँचाए गए से ज़्यादा हो सकता है।

कस्टम फ़ील्ड में नाम, ईमेल पते या फ़ोन नंबर जैसा व्यक्तिगत डेटा न डालें — इसके बजाय ऐसा रेफ़रेंस जोड़ें जिसे आपके अपने सिस्टम पहचान सकें, और अकाउंट कौन है, यह अकाउंट रिकॉर्ड के रूप में भेजें (नीचे)।

अकाउंट रिकॉर्ड

account विज़िट के पीछे के अकाउंट के लिए आपका रिकॉर्ड है — वह जो आपने उस account_id के लिए POST /v2/accounts/metadata के ज़रिए आख़िरी बार भेजा:

{
  "account": { "id": "user-42", "email": "ann@example.com", "display_name": "Ann Lee" }
}

रिकॉर्ड हर अनुरोध पर लाइव पढ़ा जाता है, इसलिए नाम बदलना पुरानी विज़िट पर भी दिखता है: ब्लॉक अकाउंट को वैसा बताता है जैसा वह अभी है, न कि जैसा वह विज़िट के समय था। यह API एक्सेस वाले हर प्लान (Pro और उससे ऊपर) में उपलब्ध है। रिकॉर्ड के साथ भेजे गए लेबल नहीं लौटाए जाते।

ब्लॉक तब अनुपस्थित होता है जब विज़िट का कोई लिंक्ड अकाउंट नहीं है, जब उसके लिए कोई रिकॉर्ड नहीं है (या आपने खाली मान भेजकर उसे साफ़ कर दिया), और — कभी-कभार — जब रिकॉर्ड पढ़ा नहीं जा सका: अनुरोध विफल करने के बजाय सेशन फिर भी पूरा लौटाया जाता है, इसलिए अनुपस्थित ब्लॉक को "अज्ञात" मानें, "इस अकाउंट का कोई ईमेल नहीं" नहीं। Webhooks यह ब्लॉक नहीं लाते।

एक सेशन प्राप्त करना

सबसे हालिया वाला:

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

यह एक सादा सेशन ऑब्जेक्ट लौटाता है — न कोई ऐरे, और न ही किसी एनवेलप में लिपटा हुआ। विंडो में बिना किसी सेशन वाला विज़िटर 404 not_found और no sessions for this visitor in the retention window लौटाता है।

या request_id से, वह पहचानकर्ता जो webhook पेलोड में भी आता है:

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

यहाँ visitor_id वैकल्पिक है, पर जब वह आपको पता हो तब उसे भेजना लुकअप को उल्लेखनीय रूप से तेज़ बना देता है।

identification.drift_score — वह स्मूद किया गया व्यवहार स्कोर जिस पर अकाउंट-टेकओवर वर्डिक्ट दिया गया, Business और उससे ऊपर — केवल इसी एकल-सेशन रीड से लौटाया जाता है। व्यवहार ड्रिफ़्ट विज़िट के दौरान, प्रारंभिक पहचान के बाद मापा जाता है, इसलिए सूची और नवीनतम-सेशन रूट इसे छोड़ देते हैं। जिस विज़िट के व्यवहार का कभी आकलन नहीं हुआ, उसमें drift_score नहीं होता। वही मान आप तक account_takeover webhook के ज़रिए भी पहुँचता है।

सुधारी गई विज़िट के लिए आपको कौन-सा उत्तर मिलता है

कोई विज़िट webhook द्वारा एक से अधिक बार डिलीवर हो सकती है: पहले primary, फिर late या correction, जैसे-जैसे धीमे सिग्नल और व्यवहारिक प्रमाण आते हैं — और बाद वाला फ़ेज़ पहले के वर्डिक्ट को पलट सकता है। Data API primary रिकॉर्ड से उत्तर देता है। बाद के फ़ेज़ उसमें वापस नहीं मिलाए जाते, इसलिए सुधारी गई विज़िट के लिए आख़िरी webhook नया उत्तर है। यदि आप विज़िट के कुछ मिनट बाद कार्रवाई करते हैं, तो यहाँ नए रीड के बजाय आख़िरी बार प्राप्त फ़ेज़ को प्राथमिकता दें।

एक बात उल्टी दिशा में चलती है: जब किसी विज़िट के लिए अकाउंट-टेकओवर डिटेक्टर ट्रिगर हो चुका हो, तो यहाँ guidance उसे दर्शाता है, जबकि उसी विज़िट के identification webhook बॉडी उस अक्ष को नहीं लाते — वह समर्पित account_takeover डिलीवरी के साथ आता है।

वेलोसिटी

वेलोसिटी इस प्रश्न का उत्तर देती है कि "यह विज़िटर हाल में कितना कुछ कर रहा है" — यही क्रेडेंशियल स्टफ़िंग, कार्ड टेस्टिंग और थोक साइनअप का आकार है।

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

window 1h, 24h या 7d स्वीकार करता है और डिफ़ॉल्ट रूप से 24h है। कोई भी अन्य मान 400 invalid_request और window must be one of: 1h, 24h, 7d के साथ अस्वीकार कर दिया जाता है।

{
  "window": "1h",
  "events": 37,
  "unique_ips": 9,
  "unique_countries": 3,
  "unique_accounts": 12,
  "bot_events": 4,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

unique_accounts उन अलग-अलग linkedId मानों की गिनती करता है जो आपने इस डिवाइस के लिए भेजे — देखें अकाउंट लिंकिंग। bot_events Business और उससे ऊपर है; Pro पर यह कुंजी अनुपस्थित होती है।

अकाउंट मेटाडेटा

TRACIO आपके अकाउंट को केवल उस ID से जानता है जो आपकी साइट linkedId के रूप में भेजती है — usr_8412 जैसी एक अपारदर्शी स्ट्रिंग। मानव-पठनीय लेबल एक बार भेजें, और उस अकाउंट को दिखाने वाली हर डैशबोर्ड स्क्रीन कच्चे ID के बजाय नाम या ईमेल दिखाती है, और सेशन ऑब्जेक्ट उन्हें अपने account ब्लॉक में लौटाता है। यहाँ कुछ भी डिटेक्शन या स्कोरिंग को प्रभावित नहीं करता; यह एक प्रदर्शन परत है।

curl -s -X POST "https://api.tracio.ai/v2/accounts/metadata" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[
        {"account_id":"usr_8412","email":"ann@example.com","display_name":"Ann Lee","labels":{"tier":"vip"}},
        {"account_id":"usr_9130","display_name":"Bob Ray"}
      ]}'

{ "updated": 2 }

• किसी अकाउंट के व्यक्तिगत डेटा की जगह यही है — fields नहीं। यहाँ भेजा गया ईमेल या नाम केवल आपके वर्कस्पेस के अकाउंट रिकॉर्ड में रहता है: यह प्रति विज़िट संग्रहीत नहीं होता, पेज में नहीं लिखा जाता, और एक बार भेजना उस अकाउंट की हर विज़िट को अपडेट कर देता है।
• दायरा कुंजी का वर्कस्पेस और एनवायरनमेंट है। staging कुंजी कभी उसे ओवरराइट नहीं करती जो प्रोडक्शन कुंजी ने उसी अकाउंट ID के लिए लिखा।
• हर बार भेजना पूर्ण ओवरराइट है, पैच नहीं। जो फ़ील्ड आप छोड़ देते हैं वे खाली संग्रहीत होते हैं — हर बार पूरा रिकॉर्ड भेजें। किसी मान को साफ़ करने का तरीका भी यही है।
• अज्ञात फ़ील्ड अस्वीकार किए जाते हैं 400 invalid_request के साथ, और एक ख़राब प्रविष्टि पूरा बैच अस्वीकार कर देती है — त्रुटि उसकी स्थिति बताती है। एक बैच में डुप्लिकेट अकाउंट ID ठीक हैं: आख़िरी वाला जीतता है।

सीमाएँ: प्रति अनुरोध 1000 अकाउंट, 1 MiB बॉडी, account_id ≤ 256 वर्ण, email ≤ 320, display_name ≤ 256, अधिकतम 16 लेबल, कुंजियाँ ≤ 64 और मान ≤ 256 वर्ण।

विज़िट के बाद फ़ील्ड जोड़ना

ब्राउज़र केवल वही भेज सकता है जो पेज रेंडर के समय जानता है — एक ऑर्डर ID, पर भुगतान जाँच का नतीजा या बाद में तय होने वाली कोई और चीज़ कभी नहीं। यह रूट वह कमी भरता है: विज़िट को उसके पास पहले से मौजूद किसी फ़ील्ड से खोजें, और सर्वर-साइड उसमें और फ़ील्ड जोड़ें।

curl -s -X POST "https://api.tracio.ai/v2/events/fields" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"},"fields":{"amount":"120.00"}}'

{ "updated": 1 }

• match विज़िट को उसके पास पहले से मौजूद किसी फ़ील्ड से खोजता है, request_id से नहीं, आपकी कुंजी के वर्कस्पेस और एनवायरनमेंट के भीतर।
• खोज की विंडो 24 घंटे है। पुरानी विज़िट 404 not_found लौटाती है — नतीजा तय होने के तुरंत बाद फ़ील्ड लिखें।
• updated अलग-अलग विज़िट गिनता है। यह 1 से ऊपर तभी जाता है जब आपका match एक से अधिक विज़िट पर लगता है — ऐसा की/वैल्यू जोड़ा जो किसी एक ऑर्डर या कार्ट के लिए अद्वितीय नहीं है। 100 से अधिक इवेंट पर लगने वाला match किसी मनमाने उपसमूह पर लागू करने के बजाय 400 invalid_request के साथ अस्वीकार कर दिया जाता है।
• यहाँ लिखे गए फ़ील्ड डैशबोर्ड में server टैग के साथ दिखते हैं, और ब्राउज़र द्वारा लिखे गए उसी कुंजी वाले मान पर प्राथमिकता लेते हैं।
• कोई मेल न होना 404 not_found है, खाली 200 नहीं।

सीमाएँ ब्राउज़र चैनल जैसी ही हैं: प्रति कॉल 50 फ़ील्ड, कुंजियाँ ≤ 40 बाइट, मान ≤ 500 बाइट — बाइट, वर्ण नहीं — कुंजी के वर्ण A-Za-z0-9_.:-, 1 MiB बॉडी।

फ़ील्ड हटाना

कस्टम फ़ील्ड मिटाता है — विज़िट स्वयं कभी नहीं। इसका उपयोग उन मानों के लिए करें जिन्हें अब विज़िट से जुड़ा रखने की ज़रूरत नहीं, जैसे ऑर्डर का कुल योग। पहले से भेजे गए webhooks और पहले से लिए गए एक्सपोर्ट नहीं बदलते।

# by request_id — clears every field on this one visit
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31"}'

# by match — clears "order_ref" from every visit currently holding "A-1029"
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"}}'

{ "deleted": 1 }

• request_id और match परस्पर अनन्य हैं — दोनों भेजना, या कोई भी नहीं, 400 invalid_request है। match जोड़ने वाली ही 24-घंटे की विंडो और वही 100-इवेंट की ऊपरी सीमा उपयोग करता है।
• deleted गिनता है विज़िट से हटाए गए फ़ील्ड (request_id से) या वे विज़िट जिनसे फ़ील्ड हटाया गया (match से)।
• दोबारा कॉल करने पर, जब कुछ बचा न हो, 404 not_found लौटता है।

वर्कस्पेस सूचियाँ

वही सूचियाँ जिन्हें आपके ऑपरेटर डैशबोर्ड में संभालते हैं, आपके अपने बैक ऑफ़िस से पहुँच योग्य। किसी सूची का प्रकार मेल खाने वाली विज़िट पर उसकी क्रिया है — block, manual_review, challenge, allow — और उसका मोड तय करता है कि क्रिया लागू होगी या नहीं: observe केवल मेल गिनता है, enforce इसे guidance पर लागू करता है (list अक्ष)। सूचियाँ और उनका मोड डैशबोर्ड में बनाए जाते हैं; Data API सूचियाँ पढ़ता है और प्रविष्टियाँ जोड़ता व हटाता है।

curl -s "https://api.tracio.ai/v2/lists" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

[
  {
    "id": "7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60",
    "name": "Chargeback accounts",
    "type": "block",
    "mode": "enforce",
    "entries_count": 128
  }
]

# ban an account for 30 days
curl -s -X POST "https://api.tracio.ai/v2/lists/7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60/entries" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"value":"usr_8412","value_type":"linked_id","ttl_minutes":43200}'

{
  "id": "02b4c8d1-6e7f-4a90-b1c2-d3e4f5a6b7c8",
  "value": "usr_8412",
  "value_type": "linked_id",
  "expires_at": "2026-10-19T12:00:00Z",
  "propagation": "immediate"
}

उसी बॉडी के साथ POST /v2/lists/{list_id}/entries/delete पर प्रविष्टि हटाएं; उत्तर { "removed": true, "propagation": "immediate" } होता है।

• value_type वह है जिससे मान का मिलान होता है: linked_id, visitor_id, device_id, ip, cidr या country। जो मान अपने प्रकार के लिए पार्स नहीं होता, वह 400 invalid_request है।
• जब कई सूचियाँ मेल खाती हैं, तो सबसे विशिष्ट प्रकार तय करता है — linked_id → visitor_id → device_id → ip → cidr → country — और उसके भीतर सबसे सख़्त क्रिया जीतती है।
• ttl_minutes वैकल्पिक है। छोड़ने पर सूची का डिफ़ॉल्ट TTL लागू होता है; वह भी न हो तो प्रविष्टि कभी समाप्त नहीं होती (expires_at null है)। प्रविष्टि दोबारा जोड़ने पर वह नवीनीकृत होती है।
• propagation बताता है कि बदलाव कब लाइव है: immediate, या ttl — लगभग पाँच मिनट के भीतर।
• जो मान मौजूद नहीं, उसे हटाना removed: false के साथ 200 है; 404 अज्ञात सूची के लिए आरक्षित है।

रिस्पॉन्स की परिपाटियाँ

अनुपस्थित फ़ील्ड का अर्थ है "कोई डेटा नहीं", कभी शून्य नहीं। बिना मान वाले फ़ील्ड 0, "" या null के रूप में भेजे जाने के बजाय पूरी तरह हटा दिए जाते हैं: बिलकुल नए विज़िटर के पास कोई match_confidence नहीं होता, साफ़-सुथरी विज़िट के पास कोई antidetect_score या suspect_score नहीं होता। एकमात्र जान-बूझकर रखा गया अपवाद है bot.score, जो शून्य होने पर भी हमेशा मौजूद रहता है। फ़ील्ड सावधानी से पढ़ें।

पेलोड आपके प्लान पर निर्भर करता है। API पहुँच Pro से शुरू होती है, और Pro को बेस सेशन मिलता है — पहचानकर्ता, टाइमस्टैम्प, URL, IP, user agent, ब्राउज़र, OS, डिवाइस, geo, network, bot, identification और decision — साथ में identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields और account। Business और Enterprise geo.isp, network.asn, network.real_ip, decision.suspect_score, identification.drift_score, reasons, behavior, guidance, device_info, spoofing, os_environment, screen, locale, client_hints और environment जोड़ते हैं। व्यक्ति-स्तर के फ़ील्ड (person_id, reputation, linked_accounts_count, linked_visitors_count) Business और Enterprise के लिए आरक्षित हैं और व्यक्ति परत सक्षम होते ही दिखाई देंगे — आज यह ऑब्ज़र्वेशन मोड में चलती है और ये फ़ील्ड नहीं भेजे जाते। Pro प्लान पर किसी Business फ़ील्ड की अनुपस्थिति कोई त्रुटि नहीं है।

सिग्नल-स्तर की आंतरिक बातें कभी नहीं लौटाई जातीं, किसी भी प्लान पर: अलग-अलग सिग्नल के नाम, उनके वज़न, किसी वर्डिक्ट के पीछे की थ्रेशोल्ड, कच्चे सिग्नल मान और स्कोर का विश्लेषण हमारी ओर ही रहते हैं। जिस स्कोर की उसके इनपुट में रिवर्स इंजीनियरिंग हो सके, वह बचाव के रूप में उपयोगी नहीं रह जाता।

त्रुटियाँ

हर विफलता एक ही एनवेलप का उपयोग करती है:

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

यह request_id विज़िट पहचानकर्ता नहीं है। दो अलग-अलग मान एक ही नाम साझा करते हैं: सेशन पेलोड के भीतर request_id विज़िट का UUID है, वही जो webhook पहुँचाता है; त्रुटि एनवेलप के भीतर यह प्रति HTTP कॉल बनाया गया 24-वर्ण का ट्रेस पहचानकर्ता है। यह ट्रेस पहचानकर्ता हर उत्तर पर X-Request-Id हेडर में भी वापस आता है, चाहे उत्तर सफल हो या न हो। सपोर्ट से संपर्क करते समय इसे साथ दें — इसी से हम आपकी ठीक वही कॉल ढूँढ़ते हैं।

जांचें एक निश्चित क्रम में चलती हैं — पहले कुंजी, फिर प्लान, फिर सीमाएँ — इसलिए गलत कुंजी वाला अनुरोध हमेशा पहले कुंजी की ही रिपोर्ट करता है, कभी कोटा की समस्या नहीं। किसी दूसरे वर्कस्पेस का डेटा मौजूद न होने वाले डेटा से अलग नहीं पहचाना जा सकता: वह 404 देता है, 403 नहीं।

दो 401 स्थितियाँ जान-बूझकर अलग-अलग पढ़ी जाती हैं: missing Authorization: Bearer <secret key> का अर्थ है कि हेडर आया ही नहीं, जबकि invalid or revoked API key का अर्थ है कि वह आया और मेल नहीं खाया। 402 के साथ आता है Data API requires the Pro plan or higher।

429 और 503 को बढ़ते अंतराल के साथ दोबारा आज़माएँ; अन्य 4xx को दोबारा आज़माना बेकार है — उनका अर्थ है कि अनुरोध को ही ठीक करने की ज़रूरत है।

रेट लिमिट और कोटा

जिन उत्तरों के लिए कुंजी पहचान ली गई है, वे आपकी वर्तमान स्थिति साथ लाते हैं (401 और 402 उत्तर नहीं लाते, और Enterprise, जिसका कोई दैनिक कोटा नहीं है, कोटा हेडर नहीं पाता):

• छोटे बर्स्ट की अनुमति है: प्रति-सेकंड सीमा एक टोकन बकेट है जो मना करना शुरू करने से पहले सतत दर से तीन गुना तक सह लेती है।
• प्रति-सेकंड दर पार करने के कारण अस्वीकार किया गया अनुरोध दैनिक कोटा नहीं खर्च करता, इसलिए कोई बर्स्ट दिन भर का बजट नहीं खा सकता।
• Data API की सीमाएँ पहचान ट्रैफ़िक से अलग गिनी जाती हैं। अपना ही इतिहास पढ़ने पर वे पहचानें कभी खर्च नहीं होतीं जिनके लिए आप भुगतान कर रहे हैं।

अगले कदम

• Webhooks — हर पहचान को घटित होते ही प्राप्त करें
• अकाउंट लिंकिंग — अपना अकाउंट id किसी डिवाइस से जोड़ें
• बॉट डिटेक्शन — बॉट वर्डिक्ट कैसे बनता है
• गोपनीयता और GDPR — डेटा-विषय अनुरोधों को संभालना