Customer Context

The read primitive. Returns a token-budgeted snapshot of a customer: who they are, where they are in the lifecycle, what signals they are firing, what loops are open, and what other agents have decided recently.

P50 latency 120ms. Backed by MCP tool get_customer_context.

Request

GET /v1/context/{id} or GET /v1/context?email={email}

Param	Type	Notes
`id`	path	Customer ID. Internal Waypath ID.
`email`	query	Alternative to `id`. Resolves through identity graph.
`budget`	query, optional	Token budget. Default 2048. Range 256 to 8192. The server prunes least-recent fields to fit.

Required scope: context:read.

Examples

curl


curl https://api.waypath.app/v1/context?email=jane@acme.com \
  -H "X-API-Key: wp_live_..."

node-fetch


const res = await fetch(
  `https://api.waypath.app/v1/context?email=${encodeURIComponent('jane@acme.com')}`,
  { headers: { 'X-API-Key': process.env.WAYPATH_API_KEY! } }
)
if (!res.ok) throw new Error(`waypath ${res.status}`)
const ctx = await res.json()

python


import os, requests
ctx = requests.get(
    'https://api.waypath.app/v1/context',
    params={'email': 'jane@acme.com', 'budget': 2048},
    headers={'X-API-Key': os.environ['WAYPATH_API_KEY']},
    timeout=5,
).json()

MCP


// from inside an agent loop
const ctx = await mcp.tools.get_customer_context({ email: 'jane@acme.com' })

Response


{
  "customer": "Jane Doe . Acme (250-1000)",
  "customer_id": "cus_8af2",
  "lifecycle_stage": "opportunity",
  "sentiment_trajectory": {
    "30d": "declining",
    "trigger": "support_ticket_unresolved"
  },
  "intent_signals": [
    "viewed_pricing_3x",
    "downloaded_whitepaper"
  ],
  "open_loops": [
    "awaiting_security_review",
    "pending_legal_review"
  ],
  "blockers": [
    "procurement_review_q2"
  ],
  "recent_decisions": [
    {
      "agent": "support_v2",
      "action": "escalate_to_human",
      "outcome": "ticket_resolved",
      "ts": "2026-04-12T14:22:11Z"
    }
  ]
}

Field reference

Field	Type	Notes
`customer`	string	Display label. Format `Name . Company (size)`.
`customer_id`	string	Internal Waypath ID. Use this for subsequent writes.
`lifecycle_stage`	string	Current stage in your funnel.
`sentiment_trajectory`	object	`30d` direction + `trigger` event that drove the latest shift.
`intent_signals`	string[]	Recent buying signals. Most-recent first.
`open_loops`	string[]	Things the customer is waiting on.
`blockers`	string[]	Things blocking forward motion.
`recent_decisions`	array	Decisions logged via `POST /v1/memory`. Most-recent first.

The shape is stable. New fields may be added; existing fields will not be removed without a major version bump.

Errors

Status	Code	Cause
400	invalid_payload	Missing both `id` and `email`.
401	unauthenticated	Missing or invalid X-API-Key.
403	forbidden_scope	Key lacks `context:read`.
404	not_found	Customer does not exist.
429	rate_limited	Per-key rate cap. Honor the `Retry-After` header.
500	internal	Internal error. Include `request_id` in support email.