API Endpoint — Landing Page Suggestions

API Endpoint — Landing Page Suggestions

Purpose

The landing page suggestions endpoint provides a greeting message and curated prompt suggestions when mobile clients initially load the chat interface. Returns greeting text chunks and suggestions via Server-Sent Events (SSE) using chunk and prompt_suggestion event types.

Use Case: Help new users discover ways to interact with the AI assistant through personality-driven example queries.

---

Endpoint

POST /api/v1/landing/stream

Authentication

Required: Hybrid authentication (API Key + JWT)

• X-API-Key header — API key for service authentication
• Authorization header — JWT bearer token for user authentication
• userId header — User identifier

Request Body

{
  "latitude": 41.8781,
  "longitude": -87.6298
}

Field definitions

• latitude (float64, optional) — User’s latitude coordinate. Defaults to config value if 0.
• longitude (float64, optional) — User’s longitude coordinate. Defaults to config value if 0.

---

Event Flow

The endpoint streams multiple events in sequence:

1. chunk — One or more events containing greeting text (e.g., “Welcome to Fetch!”)
2. prompt_suggestion — One event per suggestion (typically 5 events)
3. completed — Signals end of stream

---

Event: chunk

Greeting text is streamed as one or more chunk events before suggestions:

{
  "event_type": "chunk",
  "content": "Welcome to Fetch! "
}

{
  "event_type": "chunk",
  "content": "Here are some ideas to get you started:\n\n"
}

Field definitions

• event_type (string, required) — Always chunk.
• content (string, required) — Text fragment of the greeting message.

Client behavior

• Append chunks to build complete greeting message
• Display greeting text above or alongside suggestions
• Chunks arrive before prompt_suggestion events
• May be split across multiple events

---

Event: prompt_suggestion

Each suggestion is sent as a separate event:

{
  "event_type": "prompt_suggestion",
  "version": "0.1",
  "timestamp": "2025-10-06T19:37:23.367966Z",
  "response_id": "req_landing_user-123_1759779443",
  "content": "Which store near me has the highest total points I can earn this week?"
}

Field definitions

• event_type (string, required) — Always prompt_suggestion.
• version (string, required) — Schema version (0.1).
• timestamp (string, required) — ISO-8601 timestamp when emitted.
• response_id (string, required) — Unique identifier for this request (format: req_landing_{userId}_{timestamp}).
• content (string, required) — The suggestion text (personality-driven, natural language). Character limit: 50-75 characters for optimal mobile display.

Client behavior

• Collect all prompt_suggestion events until completed arrives
• Render suggestions as tappable cards/buttons
• When tapped, submit content as user query to chat API
• Suggestions typically arrive in priority order

---

Event: completed

{
  "event_type": "completed",
  "type": "final"
}

Field definitions

• event_type (string, required) — Always completed.
• type (string, required) — Always final.

Client behavior

• Clean up any loading indicators
• Finalize UI state
• No further events will be emitted

---

Error Responses

401 Unauthorized

Missing or invalid authentication credentials.

{
  "error": "Unauthorized"
}

Client behavior: Redirect to login or re-authenticate.

---

400 Bad Request

Invalid request body (malformed JSON).

{
  "error": {
    "code": "invalid_request",
    "message": "Failed to parse request body"
  }
}

Client behavior: Log error and show generic error message.

---

405 Method Not Allowed

Wrong HTTP method used (only POST is supported).

{
  "error": {
    "code": "method_not_allowed",
    "message": "Only POST method is allowed"
  }
}

Client behavior: Use POST method for all requests.

---

SSE Wire Example

event: chunk
data: {"event_type":"chunk","content":"Welcome to Fetch! "}

event: chunk
data: {"event_type":"chunk","content":"Here are some ideas to get you started:\n\n"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.367966Z","response_id":"req_landing_user-123_1759779443","content":"Which store near me has the highest total points I can earn this week?"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368123Z","response_id":"req_landing_user-123_1759779443","content":"I drink a lot of coffee, how can I turn this into an earning habit?"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368234Z","response_id":"req_landing_user-123_1759779443","content":"Compare my list at Target, Kroger, and Walmart for points"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368345Z","response_id":"req_landing_user-123_1759779443","content":"Help me prep for a snowstorm with the best offers"}

event: prompt_suggestion
data: {"event_type":"prompt_suggestion","version":"0.1","timestamp":"2025-10-06T19:37:23.368456Z","response_id":"req_landing_user-123_1759779443","content":"Show me all the offers for Halloween candy this week"}

event: completed
data: {"event_type":"completed","type":"final"}

---

UI Guidelines

Display Strategy

• Card Layout: Display suggestions as tappable cards with icon and text
• Spacing: Adequate padding between cards for touch targets (min 44pt)
• Visual Hierarchy: Icon + text combination for scannability
• Feedback: Provide immediate visual feedback on tap (ripple effect, highlight)

Animation

• Entry: Staggered fade-in (50ms delay between cards)
• Tap: Scale animation on press (0.95 scale)
• Submit: Smooth transition from suggestions to chat input

Accessibility

• Touch Targets: Minimum 44x44pt tap areas
• Screen Readers: Full text read aloud, category as context
• High Contrast: Ensure sufficient contrast ratios (WCAG AA)

Personality & Tone

Suggestions use natural, conversational language with personality and must be 50-75 characters:

• ✅ “I drink coffee daily - how can I turn this into points?” (57 chars)
• ❌ “Find coffee offers” (too short, no context)
• ✅ “Compare my list at Target, Kroger, and Walmart for points” (59 chars)
• ❌ “Compare stores” (too short, too vague)

---

Technical Implementation Notes

Request Flow

1. Client makes authenticated POST request with optional location
2. Server validates authentication (API key + JWT)
3. Server validates and normalizes location (falls back to config defaults)
4. Server sends request to agent service to generate greeting and suggestions
5. Server generates unique request ID
6. Server streams chunk events for greeting text
7. Server streams prompt_suggestion events for each suggestion
8. Server streams completed event via SSE

Metrics

The endpoint tracks OpenTelemetry metrics:

Metric	Type	Description
prompt_suggestions_served	Counter	Total suggestions served (with source=“landing”)
landing_request_count	Counter	Total requests (success/failure boolean)
landing_request_duration	Histogram	Request latency in milliseconds

---

Compatibility

• Fields unknown to the client must be ignored
• New optional fields (e.g., title, subtitle) may be added without version bump
• New categories may be added without version bump
• Breaking changes require a version increment

---

Future Considerations

Current Capabilities

The endpoint now uses dynamic LLM generation for both greeting and suggestions, enabling:

• Location-aware: Agent considers user location when generating suggestions
• Contextual: Suggestions adapt to current context and available data

Potential Enhancements

• Personalization: User-specific suggestions based on history/preferences (requires user profile data)
• Time-based: Suggestions tailored to time of day or day of week
• A/B Testing: Support for multiple prompt strategies
• Analytics: Track which suggestions are most frequently used
• Fallback: Hard-coded suggestions on agent failure for reliability

Backward Compatibility

Any future enhancements should:

• Maintain the same event structure (chunk, prompt_suggestion, completed)
• Use the same field names and types
• Add new fields as optional
• Include fallback mechanism on errors