How do I send events with the HTTP API?

Short answer

Send a POST to https://api.pathclue.com/api/v1/track with a key that has the Server track scope in the Authorization: Bearer header and a JSON body {"events": [ … ]} holding 1 to 1,000 events. Add ?debug=1 while integrating: the server validates every event and returns per-item results without storing anything.

Use the HTTP API when there is no server SDK for your language, or when you send from a gateway or a job runner. If an SDK exists for your stack (Node.js, Python, PHP, Java, Go), prefer it: it already batches, retries and flushes. See Send events from your server.

Before you start

• Create a project API key with the Server track (track:write) scope: Create and manage API keys.
• Keep the key on the server only, for example in TAPCUB_API_KEY.
• Keep pageviews on the website script. The HTTP API is for business events (orders, payments, sign-ups) and profile updates, not for page views.

Send your first event

curl -X POST "https://api.pathclue.com/api/v1/track?debug=1" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "track",
      "event": "purchase",
      "login_id": "u_1001",
      "insert_id": "ord_1001",
      "time": 1759363200123,
      "properties": { "revenue": 19.9, "currency": "USD" },
      "context": { "platform": "server" }
    }]
  }'

A debug response has debug: true and one entry in results per event, with any warnings. When it is clean, remove ?debug=1 and send again. The event appears in All-platform analytics › Data › Events & properties.

Event fields

Event types

Example: update a profile and bind an email in one request.

{ "events": [
  { "type": "profile_set", "login_id": "u_1001", "properties": { "plan": "pro", "$name": "Ada" } },
  { "type": "bind", "login_id": "u_1001", "identities": { "email": "ada@example.com" } }
] }

An email or mobile that is not already a 64-character hex hash is hashed by the server before storage, and the item returns the warning plaintext_identity_hashed. Hash it yourself (SHA-256) to avoid sending plaintext at all.

Read the response

A successful call returns received, accepted, rejected, events (rows queued) and results. Outside debug mode results lists only items that failed or produced a warning: index is the item's position in events, and ok: false means that item was not stored. Other items in the same request are still accepted.

Add validation_behavior=enforce to the query to reject any item that produces a warning, for example to make sure no plaintext email is ever accepted.

Errors, limits and retries

Retry rules: keep the same insert_id on every retry so nothing is counted twice, back off exponentially, cap the number of attempts, and batch events (up to 1,000 per request) instead of sending one request per event.

Related

• Send events from your server
• Create and manage API keys
• Server-side tracking