Events

events.ingest writes one marketing event through Waypath identity resolution and records the resulting touchpoint in the customer timeline.

Use this for external-agent observations and actions that should become customer history: pages observed, emails sent, calls placed, signals fired, or imported activity from another system.

01Request

POST /api/v1/capabilities/events.ingest/invoke
Authorization: Bearer wp_live_...
Content-Type: application/json

{
  "mode": "execute",
  "source": "api",
  "input": {
    "event": "page_viewed",
    "email": "jane@acme.com",
    "properties": {
      "url": "/pricing"
    },
    "timestamp": "2026-06-28T18:14:32Z"
  }
}

At least one identity key is required: customer, customerId, email, phone, external_id, or externalId.

02Examples

CLI

wp events send \
  --type page_viewed \
  --customer jane@acme.com \
  --props '{"url":"/pricing"}'

JSONL batch import uses the same capability once per row:

wp events send --batch events.jsonl

curl

curl https://api.waypath.app/api/v1/capabilities/events.ingest/invoke \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "execute",
    "source": "api",
    "input": {
      "event": "page_viewed",
      "email": "jane@acme.com",
      "properties": { "url": "/pricing", "referrer": "https://google.com" },
      "timestamp": "2026-06-28T18:14:32Z"
    }
  }'

node-fetch

await fetch('https://api.waypath.app/api/v1/capabilities/events.ingest/invoke', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WAYPATH_API_KEY!}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mode: 'execute',
    source: 'api',
    input: {
      event: 'page_viewed',
      email: 'jane@acme.com',
      properties: { url: '/pricing' },
    },
  }),
})

MCP

await mcp.tools.ingest_event({
  event: 'page_viewed',
  email: 'jane@acme.com',
  properties: { url: '/pricing' },
  _mode: 'execute',
})

03Response

{
  "status": "committed",
  "result": {
    "customer_id": "cus_8af2",
    "touchpoint_id": "tp_91ab2c",
    "is_new": false,
    "nodes_mutated": 2,
    "received_at": "2026-06-28T18:14:32Z"
  },
  "action_credit_cost": 1,
  "request_id": "req_123",
  "quota": {
    "plan": "starter",
    "limit": 500,
    "used": 43,
    "remaining": 457
  },
  "receipt_url": "/api/v1/capabilities/actions/req_123"
}

04Identity resolution

Match priority is email, then phone, then external id. If nothing matches, the event creates a new customer node. When you already know the canonical customer id from context.get, pass customerId directly.

05Errors

06See also

• Capabilities
• Customer Context
• API Keys