API Reference

Complete reference for the Pique REST API — tracking events, querying sessions, and reading decisions.

All API endpoints are under /api/v1 and require a Bearer token (your project API key) or the x-api-key header.

Authentication

Authorization: Bearer YOUR_API_KEY

Or alternatively:

x-api-key: YOUR_API_KEY

POST /api/v1/track

Track a single event.

Request body:

{
  "visitorId": "f8e7d6c5-...",
  "event": "product_viewed",
  "data": {
    "url": "https://store.com/products/summer-dress",
    "title": "Summer Dress",
    "price": "49.99"
  },
  "timestamp": 1705312320000
}

Response:

// 202 Accepted
{
  "queued": 1
}

visitorId and event are required. data is an optional key-value object. timestamp is an optional Unix millisecond timestamp (defaults to server time).

POST /api/v1/track/batch

Track multiple events in a single request (max 100).

Request body:

{
  "events": [
    {
      "visitorId": "f8e7d6c5-...",
      "event": "page_viewed",
      "data": { "url": "https://store.com/" },
      "timestamp": 1705312320000
    },
    {
      "visitorId": "f8e7d6c5-...",
      "event": "product_viewed",
      "data": { "title": "Summer Dress" },
      "timestamp": 1705312325000
    }
  ]
}

Response:

// 202 Accepted
{
  "queued": 2
}

POST /api/v1/identify

Associate a visitor ID with an email address.

Request body:

{
  "visitorId": "f8e7d6c5-...",
  "email": "customer@example.com",
  "name": "Jane Doe"
}

Response:

// 200 OK
{
  "ok": true
}

email and name are both optional, but at least one should be provided.

GET /api/v1/events

Query tracked events for your project.

Parameter	Description
visitor_id	Filter by visitor ID
event	Filter by event name (e.g., product_viewed)
since	ISO 8601 timestamp — only return events after this time
limit	Max results (default: 100)

Response:

{
  "events": [
    {
      "event_id": "...",
      "visitor_id": "f8e7d6c5-...",
      "event": "product_viewed",
      "data": { "title": "Summer Dress", "price": "49.99" },
      "timestamp": "2025-01-15 14:32:00",
      "received_at": "2025-01-15 14:32:01"
    }
  ]
}

GET /api/v1/decisions

Query decisions made for your project.

Parameter	Description
action	Filter by action (cart_abandonment, browse_abandonment, etc.)
limit	Max results (default: 50)
offset	Pagination offset (default: 0)

Response:

{
  "decisions": [
    {
      "decision_id": "...",
      "visitor_id": "f8e7d6c5-...",
      "action": "cart_abandonment",
      "reason": "Added \"Summer Dress\" to cart but left without purchasing.",
      "llm_reasoning": "This visitor spent 4 minutes browsing...",
      "session_summary": "{ ... }",
      "created_at": "2025-01-15 14:35:00"
    }
  ],
  "total": 1
}

GET /api/v1/sessions

List visitor sessions with aggregated stats.

Parameter	Description
limit	Max results (default: 50, max: 200)
offset	Pagination offset (default: 0)

Response:

{
  "sessions": [
    {
      "visitorId": "f8e7d6c5-...",
      "email": "customer@example.com",
      "name": "Jane Doe",
      "eventCount": 12,
      "productsViewed": 3,
      "addedToCart": 1,
      "firstSeen": "2025-01-15T14:30:00.000Z",
      "lastSeen": "2025-01-15T14:35:00.000Z"
    }
  ],
  "total": 42
}