Skip to main content

Pulse API Reference

All Pulse endpoints are served under the /api/v1/pulse prefix via the gateway.

Endpoints​

MethodPathDescription
GET/api/v1/pulse/eventsList tracked events
POST/api/v1/pulse/eventsTrack single event
POST/api/v1/pulse/events/batchBatch ingest events
GET/api/v1/pulse/reports/top-eventsTop events report

Examples​

Track a Single Event​

curl -X POST http://localhost:3000/api/v1/pulse/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "page.viewed",
    "properties": {"page": "/dashboard", "referrer": "/home"},
    "userId": "user-abc",
    "sessionId": "sess-xyz"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "e1f2g3h4",
    "name": "page.viewed",
    "properties": {"page": "/dashboard", "referrer": "/home"},
    "userId": "user-abc",
    "sessionId": "sess-xyz",
    "timestamp": "2026-03-05T12:00:00.000Z"
  }
}

Batch Ingest Events​

curl -X POST http://localhost:3000/api/v1/pulse/events/batch \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "name": "page.viewed",
        "properties": {"page": "/dashboard"},
        "userId": "user-abc"
      },
      {
        "name": "button.clicked",
        "properties": {"button": "deploy"},
        "userId": "user-abc"
      },
      {
        "name": "api.called",
        "properties": {"endpoint": "/api/v1/catalog/services"},
        "userId": "user-def"
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "ingested": 3
  }
}

List Tracked Events​

curl http://localhost:3000/api/v1/pulse/events

Response:

{
  "success": true,
  "data": [
    {
      "id": "e1f2g3h4",
      "name": "page.viewed",
      "properties": {"page": "/dashboard", "referrer": "/home"},
      "userId": "user-abc",
      "sessionId": "sess-xyz",
      "timestamp": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Top Events Report​

curl http://localhost:3000/api/v1/pulse/reports/top-events

Response:

{
  "success": true,
  "data": [
    {
      "name": "page.viewed",
      "count": 142
    },
    {
      "name": "button.clicked",
      "count": 87
    },
    {
      "name": "api.called",
      "count": 53
    }
  ]
}

Response Envelope​

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Event name is required"
  }
}