Nudge

Detect if a user needs help on a specific screen

The nudge endpoint is served by the AI service at http://localhost:8001. It is an internal service and does not require authentication.

POST /ai/nudge

Evaluates behavioral signals to determine whether the user is struggling on a given screen. Call this endpoint periodically while a user is active on a screen to decide whether to surface contextual help.

Request body

screen · string · required

Identifier for the current screen, e.g., "send-money", "login", "transfer-confirm".

num_validation_errors · integer · required

Number of form validation errors the user has encountered on this screen. Must be ≥ 0.

time_on_screen_seconds · integer · required

Number of seconds the user has spent on the current screen. Must be ≥ 0.

num_back_navigations · integer · required

Number of times the user has navigated back from this screen. Must be ≥ 0.

steps_total · integer · required

Total number of steps in the current flow. Use 1 for single-screen flows. Must be ≥ 1.

current_step · integer · required

The step the user is currently on. Must be ≥ 1.

user_id · string

Optional user identifier for logging and analytics.

session_id · string

Optional session identifier for correlating events across a session.

Response

user_id · string

Echoed user identifier from the request.

session_id · string

Echoed session identifier from the request.

screen · string · required

Screen name from the request.

model_version · string · required

Version of the nudging model that produced the result.

result · object · required

Show result properties

needs_help · boolean · required

Whether the model determined the user needs assistance.

difficulty_score · number · required

Difficulty score between 0.0 (no difficulty) and 1.0 (maximum difficulty).

recommended_nudge_type · string · required

Type of nudge to present. See nudge types below.

reason · string · required

Machine-readable reason code. See reason codes below.

Nudge types

Type	Threshold	Action
assist	difficulty_score > 0.75	Offer step-by-step help.
info	difficulty_score > 0.40	Show an informational hint.
warning	difficulty_score ≤ 0.40	Display a soft security or context warning.

Reason codes

Code	Description
high_error_rate_or_time	Many validation errors or excessive time on screen.
moderate_difficulty	Moderate difficulty signals detected.
low_difficulty	Low difficulty — user is progressing normally.

curl

curl --request POST \
  --url http://localhost:8001/ai/nudge \
  --header 'Content-Type: application/json' \
  --data '{
  "user_id": "user-123",
  "session_id": "session-456",
  "screen": "send-money",
  "num_validation_errors": 4,
  "time_on_screen_seconds": 180,
  "num_back_navigations": 2,
  "steps_total": 3,
  "current_step": 2
}'

Response

{
  "user_id": "user-123",
  "session_id": "session-456",
  "screen": "send-money",
  "model_version": "nudging-v1.0",
  "result": {
    "needs_help": true,
    "difficulty_score": 0.82,
    "recommended_nudge_type": "assist",
    "reason": "high_error_rate_or_time"
  }
}

---

Health check

GET /ai/health

Returns the current load status of the nudging model. Use this to verify the AI service is running before making predictions.

curl

curl --request GET \
  --url http://localhost:8001/ai/health