API Reference

The ingestion API receives events from the SDK and writes them to BigQuery. It runs as a Node.js Express service. Vendo’s managed deployment runs on Hetzner behind a Caddy reverse proxy; the public endpoints are https://track.vendodata.com (production) and https://track-staging.vendodata.com (staging).

Base URL

The API runs on the host configured for your workspace (e.g., https://track.vendodata.com, or your own domain when self-hosting). All endpoints are relative to this base.

Endpoints

POST /collect

The primary endpoint. Accepts a single event or a batch of events.

Authentication

Include the write key in one of these locations (checked in order):

The SDK sends the write key in the request body automatically.

Request: Single Event

{
  "writeKey": "your-write-key",
  "type": "track",
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-08T12:00:00.000Z",
  "anonymousId": "anon-abc-123",
  "event": "Product Viewed",
  "properties": {
    "sku": "SKU-1",
    "price": 29.99
  },
  "context": {
    "source": "web",
    "session": { "id": "session-123" },
    "page": { "url": "https://example.com/products/sku-1" },
    "campaign": { "utm_source": "google" },
    "clickId": { "gclid": "..." }
  }
}

Request: Batch

{
  "writeKey": "your-write-key",
  "sentAt": "2026-02-08T12:00:05.000Z",
  "batch": [
    {
      "type": "page",
      "messageId": "msg-1",
      "timestamp": "2026-02-08T12:00:00.000Z",
      "anonymousId": "anon-abc-123",
      "properties": { "page_url": "https://example.com/pricing" }
    },
    {
      "type": "track",
      "messageId": "msg-2",
      "timestamp": "2026-02-08T12:00:03.000Z",
      "anonymousId": "anon-abc-123",
      "event": "Button Clicked",
      "properties": { "label": "signup" }
    }
  ]
}

Maximum batch size: 100 events per request. This is the server-side hard limit — a request with more than 100 events is rejected with 413 batch_too_large. It is independent of, and larger than, the SDK’s default batchSize of 20 events per batch; the SDK flushes well below the API limit, and you can raise its batchSize up to 100.

Response: Success

{
  "ok": true,
  "received": 2,
  "inserted": {
    "events": {
      "bigquery": { "inserted": 2, "errors": 0 }
    }
  },
  "invalid": 0,
  "errors": []
}

Response: Partial Success

If some events are invalid, valid events are still processed:

{
  "ok": true,
  "received": 1,
  "inserted": { ... },
  "invalid": 1,
  "errors": [
    { "index": 1, "errors": [{ "message": "must have required property 'type'" }] }
  ]
}

Event Schema

Required Fields (All Events)

Conditional Fields

Optional Fields

The context Envelope

Every event carries a structured context object. The SDK populates it automatically; you can merge additional keys via the context argument on track(), page(), etc. The API normalizes these keys into typed warehouse columns.

The key names are camelCase (campaign, clickId, userAgent, consent) as emitted by the SDK.

Table Routing

Server-Added Fields

The ingestion API enriches each event with:

POST /admin/simulate

Dry-run an event payload through validation, normalization, and destination preview without writing rows or sending events to downstream destinations.

This endpoint is intended for demos, setup flows, and internal support tooling. It only works when DEMO_MODE=true, ADMIN_SETUP_ENABLED is enabled, and a matching ADMIN_SETUP_TOKEN is sent in the X-Admin-Token header.

curl -X POST https://track.yourdomain.com/admin/simulate \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: $ADMIN_SETUP_TOKEN" \
  -d '{
    "writeKey": "YOUR_WRITE_KEY",
    "batch": [
      {
        "type": "track",
        "messageId": "debug-1",
        "timestamp": "2026-04-30T00:00:00.000Z",
        "anonymousId": "anon-123",
        "event": "Product Viewed",
        "properties": { "sku": "SKU-1" },
        "context": {
          "page": { "url": "https://example.com/products/sku-1" },
          "campaign": { "utm_source": "google" }
        }
      }
    ]
  }'

The response includes:

No BigQuery inserts, live event publishes, schema discovery, rules engine execution, or destination sends happen during simulation.

Error Responses

All error responses follow this format:

{
  "ok": false,
  "error": "error_code",
  "details": []
}

GET /health

Returns { "ok": true }. Use for load balancer health checks.

GET /v1/sdk.js

Serves the compiled JavaScript SDK as application/javascript with a 1-hour cache header. The SDK file is loaded into memory at API startup.

Note: The SDK is also available via Vendo’s CDN at https://cdn.vendodata.com/sdk/v1/vendo.js. The CDN-hosted version is identical to the one served by the ingestion API. Use the CDN for the fastest setup, or serve from your own domain for maximum first-party control.

Set the SDK_JS_PATH environment variable to override the default SDK file location.

GET /v1/snippet

Returns a ready-to-paste HTML <script> block with the write key and host pre-filled.

Example: GET /v1/snippet?writeKey=my-key

Authentication Modes

The API has exactly two auth modes:

In static mode, the write key in the request must match the WRITE_KEY environment variable.

In Supabase mode, the write key is resolved through Supabase — the sole write-key control plane. The resolved tenant record carries the merchant’s destination configuration (Mixpanel, Segment, Customer.io, OneSignal, BigQuery). The former firebase and dual modes were retired; Firestore is no longer consulted.

Rate Limits

The API does not enforce rate limits by default. For production deployments, configure rate limiting at the load balancer or CDN level. Recommended limits:

Related

• JavaScript SDK — Client-side SDK reference
• Self-Hosting — Deploy the ingestion API