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

POSThttps://app.tapcub.com/api/v1/track

API key required

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

debugstring

Validate only. Any other value writes.

1true

validation_behaviorstring

enforce rejects an item that has any warning.

enforce

Request body application/jsonrequired

eventsTrackEvent[]required

typestring

tracktrack_signupbindunbindprofile_setprofile_set_once

eventstring

device_idstring

login_idstring

login_id_typestring

loginemailmobileunionidopenidcustom

identitiesobject

timeinteger

Unix milliseconds. More than 72 hours from now is replaced with the server time and warned.

insert_idstring

Required for track_update and track_overwrite

session_idstring

propertiesobject

unsetstring[]

incrementobject

appendobject

item_typestring

item_idstring

groupstring

type:id, pattern ^[a-z][a-z0-9_]{0,23}:[A-Za-z0-9_@.-]{1,80}$

contextobject

Responses

• 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

debugboolean

receivedinteger

acceptedinteger

rejectedinteger

eventsinteger

Rows queued to the human buffer

resultsobject[]

On write, only items that failed or warned. On debug, every item.

indexinteger

okboolean

warningsstring[]

personIdstring

Request

curl -X POST "https://app.tapcub.com/api/v1/track" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "type": "track",
      "event": "purchase",
      "login_id": "user_42",
      "insert_id": "ord_1001",
      "time": 1759388400000,
      "properties": {
        "revenue": 19.9
      },
      "context": {
        "ip": "203.0.113.8",
        "platform": "server"
      }
    }
  ]
}'

Response

{
  "received": 1,
  "accepted": 1,
  "rejected": 0,
  "events": 1,
  "results": []
}

Both 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:

• time is milliseconds. More than 72 hours from the server clock is rewritten to now and warned as time_out_of_range.
• track_update and track_overwrite require insert_id.
• Events without session_id do not join session metrics.
• An email or mobile that is not 64 hex characters is hashed first, and that item's warnings include plaintext_identity_hashed.
• group must match the account key format and assigns the event to an organization. item_set and item_delete use item_type and item_id.
• On profile operations, a property key that starts with $ but is not reserved is removed and warned as unknown_reserved_prop.

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

POSThttps://app.tapcub.com/api/v1/server/events

API key required

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[]required

tsnumber

ipstring

uastringrequired

urlstringrequired

methodstring

statusinteger

responseTimenumber

referrerstring

Responses

• 201Counts
• 400Body failed schema validation (VALIDATION)
• 401Missing or rejected API key (NO_API_KEY, BAD_API_KEY)

Response fields 201

receivedinteger

acceptedinteger

Rows classified as bots and queued

skippedHumaninteger

received − accepted

Request

curl -X POST "https://app.tapcub.com/api/v1/server/events" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
      "url": "https://shop.example/pricing",
      "method": "GET",
      "status": 200
    }
  ]
}'

Response

{
  "received": 2,
  "accepted": 1,
  "skippedHuman": 1
}

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.