Behavior events (orders, logins, profile updates) go to /api/v1/track. Bot traffic from gateway access logs goes to /api/v1/server/events. The two are not interchangeable. Keep human pageviews on the browser script so they are not double-counted; log-line import is Log import.
Behavior events
https://api.tapcub.com/api/v1/track Track server-side events
Bearer API key with scope track:write. Up to 1000 events. debug=1 or true validates and returns per-item results without writing. validation_behavior=enforce rejects an item that produced any warning. Identity binding runs before the event is queued. Rate limit: 600 requests per API key per minute (429 RATE_LIMIT). NestJS returns 201. Errors: 400 VALIDATION, 401 NO_API_KEY, 401 BAD_API_KEY.
Query parameters2
debugstringValidate only. Any other value writes.
1true
validation_behaviorstringenforce rejects an item that has any warning.
enforce
Request body application/jsonrequired
eventsTrackEvent[]requiredtypestringtracktrack_signupbindunbindprofile_setprofile_set_once
eventstringdevice_idstringlogin_idstringlogin_id_typestringloginemailmobileunionidopenidcustom
identitiesobjecttimeintegerUnix milliseconds. More than 72 hours from now is replaced with the server time and warned.
insert_idstringRequired for track_update and track_overwrite
session_idstringpropertiesobjectunsetstring[]incrementobjectappendobjectitem_typestringitem_idstringgroupstringtype:id, pattern ^[a-z][a-z0-9_]{0,23}:[A-Za-z0-9_@.-]{1,80}$
contextobjectResponses
- 201Accept counts, or debug results
- 400Body failed schema validation (VALIDATION)
- 401Missing or rejected API key (NO_API_KEY, BAD_API_KEY)
- 429Rate limit exceeded
Response fields 201
debugbooleanreceivedintegeracceptedintegerrejectedintegereventsintegerRows queued to the human buffer
resultsobject[]On write, only items that failed or warned. On debug, every item.
indexintegerokbooleanwarningsstring[]personIdstringBoth routes read only a project-bound key from Authorization. The project comes from the key; neither route reads site_id.
{
"events": [
{
"type": "track",
"event": "purchase",
"device_id": "web_cookie:00000000-0000-4000-8000-000000000001",
"time": 1759363200123,
"insert_id": "ord_1001",
"session_id": "sess_1001",
"properties": { "revenue": 19.9 },
"context": { "ip": "203.0.113.10", "user_agent": "ExampleApp/1", "url": "https://example.com/orders/1001", "platform": "server" }
}
]
}Per-item rules:
timeis milliseconds. More than 72 hours from the server clock is rewritten to now and warned astime_out_of_range.track_updateandtrack_overwriterequireinsert_id.- Events without
session_iddo not join session metrics. - An email or mobile that is not 64 hex characters is hashed first, and that item's
warningsincludeplaintext_identity_hashed. groupmust match the account key format and assigns the event to an organization.item_setanditem_deleteuseitem_typeanditem_id.- On profile operations, a property key that starts with
$but is not reserved is removed and warned asunknown_reserved_prop.
Source and acquisition attribution
When an event with login_id identifies a person for the first time, the platform records where that person came from (acquisition attribution) and keeps it:
context.campaign: withdata-attributionon the browser script,tapcub.getAttribution()returns the source of this landing. Send it to your backend with the sign-up form and pass it here unchanged. Fields:source,medium,name,term,content,ref(promo code),click_id(type:value, such asgclid:…),landing_url,referrer,touched_at(landing time in milliseconds). It takes precedence overcontext.urland is also written to the event'sutm_*.context.url: all fiveutm_*, ad click IDs and promo code parameters are parsed (refandaffby default;tc_refis always recognised).- When
context.ipandcontext.user_agentare both present and no other source exists, the platform looks for visits from the same network and browser within 7 days (same day only in strict mode), the same way the browser script identifies visitors. The result is marked as inferred and can be excluded in reports. The IP is used only for this lookup and is not stored. - Referrals: put the inviter's
login_idinproperties.$invited_by.
{ "type": "track_signup", "event": "signed_up", "login_id": "u_1001",
"properties": { "$invited_by": "u_0042" },
"context": { "ip": "203.0.113.10", "user_agent": "Mozilla/5.0 …",
"campaign": { "source": "google", "medium": "cpc", "name": "spring_sale", "ref": "zhangsan01", "touched_at": 1759363000000 } } }Success returns received, accepted, rejected, events (rows pushed to the buffer), and results. results lists only items that failed or warned. index is the item's position in events, and ok: false means it did not enter the buffer. Debug mode writes nothing but still runs identity checks and warnings, and returns debug: true with every results entry.
With enforce, the plaintext-identity warning is enough to reject an item. If production must accept plaintext email, do not turn on enforce, or hash to 64 hex characters yourself first.
Bot access records
https://api.tapcub.com/api/v1/server/events Ingest server access events
Bearer API key with scope events:write. Only requests classified as bots are stored; human traffic should use the browser collector. X-Api-Key is not read by this handler. NestJS returns 201. Errors: 400 VALIDATION, 401 NO_API_KEY, 401 BAD_API_KEY.
Request body application/jsonrequired
eventsobject[]requiredtsnumberipstringuastringrequiredurlstringrequiredmethodstringstatusintegerresponseTimenumberreferrerstringResponses
- 201Counts
- 400Body failed schema validation (VALIDATION)
- 401Missing or rejected API key (NO_API_KEY, BAD_API_KEY)
Response fields 201
receivedintegeracceptedintegerRows classified as bots and queued
skippedHumanintegerreceived − accepted
Only records classified as bots enter the buffer. skippedHuman counts records classified as human and skipped:
{ "received": 2, "accepted": 1, "skippedHuman": 1 }This route does not accept type or insert_id, so a behavior event sent here fails schema validation.