On this page

Recommendations

Generate, prioritize, and manage AI-powered feature recommendations from your insights.

Overview

Recommendations are the actionable output of Praxiom AI's analysis pipeline. The AI agent examines your triaged insights — their severity, frequency, themes, and user quotes — and produces 3-7 specific, buildable feature recommendations. Each recommendation comes with an impact score, effort estimate, rationale, and success metrics.

How It Works

Select insights

Choose the insights you want the agent to consider. You can filter by severity, type, or frequency first. All selected insights must belong to the same workspace and not all be archived (the endpoint rejects requests where every insight is archived with code ALL_INSIGHTS_ARCHIVED).

Generate recommendations

Call POST /api/recommendations/generate:

Field	Type	Description
`workspace_id`	UUID	Target workspace
`insight_ids`	UUID[]	Insights to base recommendations on
`focus_areas`	String[]	Optional — steer the agent toward specific product areas

The agent runs through a multi-step pipeline:

Fetches insight details and workspace context
Analyses patterns across insights (frequency, severity, themes)
Scores impact using the score_impact tool
Estimates effort using the estimate_effort tool
Saves 3-7 recommendations via save_recommendations

Generation takes 20-60 seconds. Only one generation can run per workspace at a time — concurrent requests return 409 with code GENERATION_IN_PROGRESS.

Review and prioritize

The response includes:

recommendations — Array of recommendation objects with scores
count — Total number generated
prioritization_summary — Agent's summary of the prioritization rationale

Status Management

Recommendations follow a state machine that maps to a typical product workflow:

suggested → accepted → in_progress → implemented
suggested → rejected
rejected  → suggested (re-open)
accepted  → rejected
Any       → suggested (re-open)

Update status via PATCH /api/recommendations/{id}/status:

{
  "status": "accepted",
  "user_notes": "Approved for Q2 roadmap"
}

Invalid transitions return 400 with code INVALID_STATUS_TRANSITION and list the valid next states.

Batch Status Updates

Use PATCH /api/recommendations/batch/status to update multiple recommendations at once:

{
  "workspace_id": "your-workspace-uuid",
  "recommendation_ids": ["uuid-1", "uuid-2"],
  "status": "accepted",
  "user_notes": "Batch approved"
}

Invalid transitions are reported per-recommendation but do not block others. The response includes both updated_count and any errors.

Recommendation Fields

Field	Description
`title`	Feature name or short description
`description`	Detailed explanation of what to build
`addresses_insight_ids`	Which insights this recommendation addresses
`rationale`	Why this recommendation matters, grounded in evidence
`effort_estimate`	Qualitative estimate (e.g. `small`, `medium`, `large`)
`effort_weeks`	Numeric effort in weeks
`impact_score`	0.0-1.0 score based on severity, frequency, and reach
`success_metrics`	How to measure whether this recommendation succeeded
`status`	`suggested`, `accepted`, `rejected`, `in_progress`, `implemented`
`user_notes`	PM's notes and context

CRUD Operations

Operation	Endpoint	Description
List	`GET /api/recommendations?workspace_id={id}`	Filter by `status`, `min_impact`, `effort_estimate`
Get	`GET /api/recommendations/{id}`	Single recommendation
Create	`POST /api/recommendations`	Manual creation
Update	`PATCH /api/recommendations/{id}`	Edit fields
Delete	`DELETE /api/recommendations/{id}`	Permanent removal

Usage limits apply to recommendation generation. If your plan quota is reached, the API returns 402 with USAGE_LIMIT_EXCEEDED.

What's Next

Turn accepted recommendations into polished product documents with the Documents and Editor guide.

Was this helpful?

PreviousAuthentication NextIntegrations