Intelligence API
Insights, funnel analysis, and recommendation engine — served by PBCP API (merged from G-019)
Base: https://pbcp-api.pcampus.co
Intelligence API reads from Context/Story only — it does not send LINE messages, emails, or push notifications. Execution is handled by the customer app.
GET /v1/recommendations/stub
Stub recommendation for dev/demo mode — use to verify contract shape before real Intelligence scoring is ready.
Headers: x-tenant-id (required)
Response 200
{
"recommendationId": "rec-stub-pharmacy-demo",
"tenantId": "pharmacy-demo",
"type": "campaign.offer",
"audience": {
"segmentId": "segment-a",
"estimatedSize": 1200
},
"action": {
"offerType": "coupon",
"discountPercent": 10
},
"rationale": {
"summary": "Stub recommendation — bootstrap only",
"confidence": 0.82
},
"validUntil": "2026-07-31T00:00:00.000Z"
}GET /v1/intelligence/story/{entityType}/{entityId}
Enriches a Story with Intelligence outputs — insights[] (why it happened) and recommendations[] (what to do next)
Supported entityType: customer | order | product | session
Headers: x-tenant-id (required)
Response 200
{
"entityType": "customer",
"entityId": "CUST-1",
"storyComposedAt": "2026-06-28T10:30:00.000Z",
"insights": [
{
"insightId": "insight:abandoned_cart:cart-1",
"pattern": "abandoned_cart",
"label": "Cart was left without purchase",
"severity": "medium",
"storyStepIds": ["cart-1"],
"evidence": "Cart activity exists without a later completed order.",
"confidence": 0.8
}
],
"recommendations": [
{
"decisionId": "decision:send_coupon:cart-1",
"action": "send_coupon",
"label": "Send a recovery coupon",
"rationale": "A cart was left without purchase; a coupon can reduce friction.",
"insightIds": ["insight:abandoned_cart:cart-1"],
"rank": 1,
"confidence": 0.8
}
]
}No patterns found: 200 with insights: [] and recommendations: []
Insight patterns
| Pattern | Label | Severity |
|---|---|---|
abandoned_cart | Cart left without purchase | medium |
high_churn_risk | Customer showing churn signals | high |
repeat_buyer | Customer with strong purchase frequency | positive |
large_basket | Unusually large order | positive |
first_purchase | Customer's first completed order | info |
Recommendation actions
| Action | Description |
|---|---|
send_coupon | Send a discount coupon to reduce friction |
send_reward | Award loyalty points or reward |
recommend_product | Suggest related product |
trigger_campaign | Enroll in a re-engagement campaign |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION_ERROR | Missing x-tenant-id or unsupported entity type |
404 | NOT_FOUND | No story evidence for entity |
500 | INTERNAL | Story composition or intelligence scoring failed |
GET /v1/intelligence/journey/funnel
Funnel drop-off analysis across sessions.
Headers: x-tenant-id (required)
Query params:
| Param | Required | Description |
|---|---|---|
from | Yes | ISO-8601 window start |
to | Yes | ISO-8601 window end |
sessionIds | Yes | Comma-separated session IDs to analyze |
orderIds | No | Comma-separated order IDs to link to sessions |
Response 200
{
"tenantId": "pharmacy-demo",
"from": "2026-06-01T00:00:00.000Z",
"to": "2026-06-30T23:59:59.000Z",
"sessionsAnalyzed": 42,
"stages": [
{ "stage": "session_started", "count": 42, "dropOffRate": 0 },
{ "stage": "search_performed", "count": 30, "dropOffRate": 0.29 },
{ "stage": "cart_updated", "count": 12, "dropOffRate": 0.60 },
{ "stage": "order_created", "count": 8, "dropOffRate": 0.33 }
]
}Example
curl -s -G 'https://pbcp-api.pcampus.co/v1/intelligence/journey/funnel' \
-H 'x-tenant-id: pharmacy-demo' \
--data-urlencode 'from=2026-06-01T00:00:00.000Z' \
--data-urlencode 'to=2026-06-30T23:59:59.000Z' \
--data-urlencode 'sessionIds=SES-001,SES-002,SES-003'GET /v1/intelligence/journey/flow
Path analysis — common sequences customers follow before converting or dropping off.
Query params: same as funnel + segmentBy (optional)
segmentBy | Description |
|---|---|
search_query | Group paths by first search term |
channel | Group by entry channel |
customer_segment | Group by customer segment |
Response 200
{
"tenantId": "pharmacy-demo",
"flows": [
{
"path": ["session_started", "search_performed", "cart_updated", "order_created"],
"count": 8,
"conversionRate": 0.19,
"avgDurationMs": 720000
},
{
"path": ["session_started", "search_performed", "session_ended"],
"count": 18,
"conversionRate": 0,
"avgDurationMs": 180000
}
]
}Consumer rules
- Intelligence reads canonical Story output — does not access customer databases directly.
- Recommendations are channel-agnostic — the customer app selects the channel.
- Shared DTOs live in
@pbcp/contracts— do not duplicate shapes in consumer.