Upgrade prompts API
Lookup material for upgrade prompts in Nirmata AIControls. A prompt tells an admin, in counts only, when the install would benefit from a higher plan or the Advanced Security add-on. Only admins see prompts; developers and viewers never do.
Endpoints
Every endpoint is admin-only. A viewer or developer token receives 403, and a request with missing or invalid credentials receives 401.
| Endpoint | Returns |
|---|---|
GET /api/v1/upsell/prompts | The prompts to show you now. Optional query parameters: surface (one surface from the triggers table) and subject (a policy id). |
POST /api/v1/upsell/prompts/{id}/dismiss | 204. Dismisses the prompt for you permanently. 404 when the prompt is no longer live. |
POST /api/v1/upsell/events | 202 with {"prompt": ...}, or {"prompt": null} when the event raises nothing. 400 for an unknown kind or a missing subject. |
The events endpoint takes {"kind": "<event kind>", "subject": "<policy id>"}. Only policy_enforce_attempt uses subject.
How often you see a prompt
GET /api/v1/upsell/promptsreturns a prompt to you at most once every 14 days for each trigger, and records that you saw it.- Dismissing a prompt hides it from you permanently, even if its trigger fires again later.
- The weekly admin digest email has a Plan section with at most one prompt a week. A prompt in the digest counts as seen. Viewers who receive the digest don't get the Plan section.
- A prompt only appears while you are on the plan it upgrades from. When the plan changes, its prompts are removed.
Where prompts appear
The console shows a prompt, for admins only, on the surface named in the triggers table: the policy edit dialog, the team create drawer, SSO settings, trend charts cut short by the plan's retention, session detail, the security overview, the compliance page and the integrations page. Each prompt has a Dismiss button, reachable from the keyboard, and a link to the licence page. The console posts the events listed above only when you are signed in as an admin.
Prompt fields
| Field | Description |
|---|---|
id | Prompt id. Use it to dismiss the prompt. |
trigger | The trigger that raised the prompt. See Triggers. |
planFrom, planTo | The plan the prompt upgrades from and to. |
addon | advanced_security for an add-on prompt, otherwise empty. |
subject | The policy id for rule_for_everyone, otherwise empty. |
counts | The integers the prompt is built from, for example {"teams": 3, "limit": 3}. |
surfaces | Where the UI may show the prompt. |
title, body | The prompt text. It contains counts only, never names, emails, policy names or request content. |
createdAt, expiresAt | When the prompt was raised and when it lapses. |
Triggers
Team to Business:
| Trigger | Raised when | Surfaces |
|---|---|---|
rule_for_everyone | An admin tries to set a policy to deny or redact (policy_enforce_attempt). Counts the policy's audit-mode matches in the last 30 days. | policy_mode |
shadow_mcp_found | Unapproved MCP servers are in use. | alert, mcp_inventory, digest |
fourth_team | The install uses all of the plan's teams. | team_create, group_mapping |
sso_request | An admin opens SSO settings (sso_settings_opened) and most members share one email domain. | identity_settings |
history_running_out | Trend data is within 30 days of the plan's trend retention, or an admin picks a range past it (history_range_exceeded). | charts, digest |
seat_cap_approaching | Seats in use this month reach 90% of the plan's seats. | license, owner_banner |
roi_report | An admin exports a report or opens an executive report (report_exported, executive_report_opened). | reports |
session_replay | An admin clicks replay on a session (replay_clicked). | session_detail |
Business to Advanced Security:
| Trigger | Raised when | Surfaces |
|---|---|---|
detections_piling_up | Injection, secret-read and PII detections this month exceed 30. | security_overview, digest |
day_60_findings | Once, 60 days after the first recorded traffic. Counts detections, write-capable MCP tools in use and shadow MCP servers. | notification, security_overview |
security_team_arrives | A member of a security group signs in for the first time in the last 30 days, or an admin invites a security lead (security_lead_invited). | first_sign_in |
siem_integration | An admin opens SIEM export settings (siem_settings_opened). | integrations |
compliance_request | An admin opens the compliance page or exports audit evidence (compliance_opened, audit_evidence_exported). | compliance |
high_risk_sessions | Sessions matched a high or critical attack pattern in the last 30 days. | session_detail, admin_alert |
The day-60 summary is also sent to admins as an in-app notification that links to the security posture page. It isn't sent to email, Slack, Teams, or webhooks.
AIControls checks the evaluated triggers every 6 hours. A trigger whose condition no longer holds is withdrawn. A prompt raised by an event stays for 30 days, or until the plan changes.
Usage telemetry
Where usage telemetry is on, the daily document carries upgradePrompts: for each trigger, how many prompts admins saw and dismissed this month. It carries no prompt text.