Recommendations

Overview

Recommendations are actionable product features generated from synthesized insights. Each recommendation includes an impact score, effort estimate, success metrics, and a status that follows a defined state machine:

suggested -> accepted -> in_progress -> implemented
suggested -> rejected
rejected -> suggested (re-open)

---

Create Recommendation

POST /api/recommendations

Create a recommendation manually.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
title	string	Yes	Recommendation title
description	string	Yes	Detailed description
addresses_insight_ids	UUID[]	No	Insight IDs this recommendation addresses
rationale	string	No	Why this recommendation matters
effort_estimate	string	No	Effort level: trivial, small, medium, large, xlarge
effort_weeks	float	No	Estimated weeks to implement
impact_score	float	No	Impact score (0.0 to 1.0)
success_metrics	string[]	No	How to measure success
target_repo	string	No	GitHub repo hint (org/repo, max 255 chars). Used by the agent harness and push-to-GitHub flow to route this recommendation to the right repo without asking the user. Persisted on the recommendation and echoed back on read.

Response (201 Created)

{
  "id": "d4e5f6a7-b8c9-0123-defa-456789012345",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Redesign onboarding wizard",
  "description": "Replace the current 5-step wizard with a guided interactive tour...",
  "status": "suggested",
  "impact_score": 0.85,
  "effort_estimate": "medium",
  "effort_weeks": 3.0,
  "created_at": "2026-03-27T12:00:00Z"
}

---

List Recommendations

GET /api/recommendations

List recommendations for a workspace with optional filters.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
status	string	No	Filter by status
min_impact	float	No	Minimum impact score (0.0 to 1.0)
effort_estimate	string	No	Filter by effort level
limit	integer	No	Max results (default: 200, max: 500)
offset	integer	No	Pagination offset (default: 0)

Response (200 OK)

{
  "recommendations": [ ... ],
  "total": 7
}

---

Get Recommendation

GET /api/recommendations/{recommendation_id}

Path Parameters

Name	Type	Required	Description
recommendation_id	UUID	Yes	Recommendation ID

---

Update Recommendation

PATCH /api/recommendations/{recommendation_id}

Update a recommendation's fields. Only provided fields are updated.

---

Delete Recommendation

DELETE /api/recommendations/{recommendation_id}

Response (204 No Content)

---

Update Status

PATCH /api/recommendations/{recommendation_id}/status

Update a recommendation's status with transition validation.

Request Body

Name	Type	Required	Description
status	string	Yes	Target status
user_notes	string	No	Optional notes about the status change

Valid Transitions

Current Status	Valid Next Statuses
suggested	accepted, rejected
accepted	in_progress, rejected, suggested
rejected	suggested
in_progress	implemented, accepted, suggested
implemented	suggested (re-open)

Example Request

curl -X PATCH https://api.praxiomai.xyz/api/recommendations/d4e5f6a7-.../status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted", "user_notes": "Approved for Q2 sprint"}'

---

Batch Update Status

PATCH /api/recommendations/batch/status

Batch update recommendation statuses. Invalid transitions are reported per-recommendation but do not block others.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
recommendation_ids	UUID[]	Yes	List of recommendation IDs
status	string	Yes	Target status for all
user_notes	string	No	Optional notes

Response (200 OK)

{
  "updated_count": 3,
  "failed_count": 1,
  "errors": [
    {
      "recommendation_id": "...",
      "error": "invalid_transition: suggested -> implemented",
      "valid_transitions": ["accepted", "rejected"]
    }
  ]
}

---

Generate Recommendations (AI)

POST /api/recommendations/generate

Generate feature recommendations from insights using the AI agent. The agent analyses patterns across insights and generates 3-7 buildable recommendations with impact/effort scores. Typically takes 20-60 seconds.

Requires: Active subscription.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
insight_ids	UUID[]	Yes	Insight IDs to generate from
focus_areas	string[]	No	Optional focus areas to guide generation

Example Request

curl -X POST https://api.praxiomai.xyz/api/recommendations/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "insight_ids": ["c3d4e5f6-...", "d4e5f6a7-..."],
    "focus_areas": ["onboarding", "activation"]
  }'

Response (200 OK)

{
  "recommendations": [ ... ],
  "count": 5,
  "prioritization_summary": "Generated 5 recommendations. Top priority: Redesign onboarding wizard (impact: 0.85, effort: medium)..."
}