BlogPricingDashboardGitHubGitHub★ 902
API Reference

Event Tracking

Track custom events programmatically using the Basket API. This is useful for server-side tracking, mobile apps, or custom integrations.

Base URL

https://basket.databuddy.cc

Authentication

You can authenticate requests using either:

  1. API Key (recommended for server-side) — Pass in the Authorization header
  2. Website ID — Pass as website_id query parameter or in the event body
http
# With API Key
POST /track
Authorization: Bearer your_api_key

# With Website ID
POST /track?website_id={website_id}

Track Events

The primary endpoint for sending custom events.

http
POST /track

Single Event

json
{
"name": "purchase",
"properties": {
  "value": 99.99,
  "currency": "USD",
  "product_id": "prod_123"
},
"anonymousId": "anon_user_123",
"sessionId": "session_456",
"timestamp": 1704067200000
}

Batch Events

Send an array of events in a single request:

json
[
{
  "name": "page_view",
  "properties": { "page": "/pricing" },
  "timestamp": 1704067200000
},
{
  "name": "purchase",
  "properties": { "value": 99.99 },
  "timestamp": 1704067260000
}
]

Response

json
{
"status": "success",
"type": "custom_event",
"count": 1
}

Event Fields

FieldTypeRequiredDescription
namestringYesEvent name (1-256 characters)
propertiesobjectNoCustom event properties
anonymousIdstringNoAnonymous user identifier (max 256 chars)
sessionIdstringNoSession identifier (max 256 chars)
timestampnumber | string | DateNoEvent timestamp (defaults to now)
namespacestringNoEvent namespace for grouping (max 64 chars)
sourcestringNoEvent source identifier (max 64 chars)
websiteIdstringNoWebsite ID (UUID, alternative to query param)

Server-Side Examples

Node.js / TypeScript

typescript
async function trackEvent(
name: string,
properties?: Record<string, unknown>
) {
const response = await fetch('https://basket.databuddy.cc/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_key'
  },
  body: JSON.stringify({
    name,
    properties,
    timestamp: Date.now()
  })
});
return response.json();
}

// Usage
await trackEvent('purchase', {
value: 99.99,
currency: 'USD',
product_id: 'prod_123'
});

Python

python
import requests
import time

def track_event(name: str, properties: dict = None):
  response = requests.post(
      "https://basket.databuddy.cc/track",
      headers={
          "Content-Type": "application/json",
          "Authorization": "Bearer your_api_key"
      },
      json={
          "name": name,
          "properties": properties or {},
          "timestamp": int(time.time() * 1000)
      }
  )
  return response.json()

# Usage
track_event("purchase", {
  "value": 99.99,
  "currency": "USD",
  "product_id": "prod_123"
})

cURL

bash
curl -X POST https://basket.databuddy.cc/track \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_key" \
-d '{
  "name": "purchase",
  "properties": {
    "value": 99.99,
    "currency": "USD"
  }
}'

Common Event Examples

E-commerce Purchase

json
{
"name": "purchase",
"properties": {
  "order_id": "order_123",
  "value": 149.99,
  "currency": "USD",
  "items": [
    {"sku": "SKU-001", "name": "Product A", "quantity": 2, "price": 49.99},
    {"sku": "SKU-002", "name": "Product B", "quantity": 1, "price": 50.01}
  ]
}
}

User Signup

json
{
"name": "signup",
"properties": {
  "method": "email",
  "plan": "free",
  "referrer": "google"
}
}

Feature Usage

json
{
"name": "feature_used",
"namespace": "dashboard",
"properties": {
  "feature": "export_csv",
  "format": "xlsx"
}
}

Subscription Event

json
{
"name": "subscription_started",
"properties": {
  "plan": "pro",
  "billing_cycle": "annual",
  "mrr": 99
}
}

Additional Endpoints

These endpoints are used by the JavaScript tracker SDK and are documented here for completeness.

Web Vitals

Track Core Web Vitals metrics.

http
POST /vitals?client_id={website_id}
json
[
{
  "timestamp": 1704067200000,
  "path": "https://example.com/page",
  "metricName": "LCP",
  "metricValue": 2500
}
]
FieldTypeRequiredDescription
timestampnumberYesUnix timestamp in milliseconds
pathstringYesPage URL
metricNamestringYesOne of: FCP, LCP, CLS, INP, TTFB, FPS
metricValuenumberYesMetric value
anonymousIdstringNoAnonymous user identifier
sessionIdstringNoSession identifier

Error Tracking

Track JavaScript errors.

http
POST /errors?client_id={website_id}
json
[
{
  "timestamp": 1704067200000,
  "path": "https://example.com/app",
  "message": "Cannot read property 'id' of undefined",
  "filename": "https://example.com/app.js",
  "lineno": 42,
  "colno": 15,
  "stack": "TypeError: ...",
  "errorType": "TypeError"
}
]
FieldTypeRequiredDescription
timestampnumberYesUnix timestamp in milliseconds
pathstringYesPage URL
messagestringYesError message
filenamestringNoSource file
linenonumberNoLine number
colnonumberNoColumn number
stackstringNoStack trace
errorTypestringNoError type (e.g. TypeError)
anonymousIdstringNoAnonymous user identifier
sessionIdstringNoSession identifier

Error Responses

json
{
"status": "error",
"message": "Description of the error"
}
StatusMessageDescription
400Invalid request bodyRequest body failed validation
400Website missing organizationWebsite not properly configured
401API key or website_id requiredNo authentication provided
403API key missing track:events scopeAPI key lacks required scope
404Website not foundInvalid website_id
500Internal server errorServer error

Best Practices

  1. Use consistent event names — Use snake_case and be descriptive (button_click not click)
  2. Use namespaces — Group related events with the namespace field
  3. Include context — Add properties that help segment and analyze later
  4. Batch when possible — Send arrays of events to reduce HTTP overhead
  5. Do not track PII — Avoid personally identifiable information in properties
  6. Use server-side for sensitive events — Track purchases and signups server-side with API keys

How is this guide?

Edit on GitHub