Insights

Overview

Insights are structured findings extracted from research sources during synthesis. They include pain points, opportunities, feature requests, and behavioral patterns -- each with supporting quotes, severity ratings, and frequency counts.

---

Create Insight

POST /api/insights

Create an insight manually or via the agent.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Target workspace
insight_type	string	Yes	Type of insight (e.g., pain_point, opportunity, feature_request, behavior)
title	string	Yes	Short insight title
description	string	Yes	Detailed description
source_ids	string[]	No	IDs of research sources this insight was derived from
quotes	object[]	No	Supporting quotes with text, source_id, speaker
frequency	integer	No	Number of sources mentioning this insight
severity	string	No	Severity level: low, medium, high, critical
impact	string	No	Impact assessment

Example Request

curl -X POST https://api.praxiomai.xyz/api/insights \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "insight_type": "pain_point",
    "title": "Slow dashboard loading times",
    "description": "Users report frustration with 5+ second load times on the main dashboard.",
    "frequency": 7,
    "severity": "high"
  }'

Response (201 Created)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "insight_type": "pain_point",
  "title": "Slow dashboard loading times",
  "description": "Users report frustration with 5+ second load times on the main dashboard.",
  "frequency": 7,
  "severity": "high",
  "is_archived": false,
  "created_at": "2026-03-27T11:00:00Z"
}

---

List Insights

GET /api/insights

List insights for a workspace with optional filters.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
insight_type	string	No	Filter by type
severity	string	No	Filter by severity
is_archived	boolean	No	Filter by archive status
min_frequency	integer	No	Minimum source mention count (>= 1)
limit	integer	No	Max results (default: 200, max: 500)
offset	integer	No	Pagination offset (default: 0)

Example Request

curl "https://api.praxiomai.xyz/api/insights?workspace_id=550e8400-...&severity=high&min_frequency=3" \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK)

{
  "insights": [ ... ],
  "total": 12
}

---

Get Insight

GET /api/insights/{insight_id}

Get a single insight by ID.

Path Parameters

Name	Type	Required	Description
insight_id	UUID	Yes	Insight ID

---

Update Insight

PATCH /api/insights/{insight_id}

Update an insight's fields (notes, rating, severity, etc.). Only provided fields are updated.

Path Parameters

Name	Type	Required	Description
insight_id	UUID	Yes	Insight ID

Request Body

All fields are optional.

Name	Type	Required	Description
title	string	No	Updated title
description	string	No	Updated description
severity	string	No	Updated severity
is_archived	boolean	No	Archive or unarchive

---

Delete Insight

DELETE /api/insights/{insight_id}

Delete an insight permanently.

Response (204 No Content)

---

Search Insights

POST /api/insights/search

Semantic search for insights using natural language queries. Uses vector embeddings (Pinecone) for relevance ranking, with fallback to database text search.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
query	string	Yes	Natural language search query
insight_type	string	No	Filter by type
severity	string	No	Filter by severity
min_frequency	integer	No	Minimum frequency
limit	integer	No	Max results (default: 10)

Example Request

curl -X POST https://api.praxiomai.xyz/api/insights/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "query": "What are the main onboarding friction points?",
    "severity": "high",
    "limit": 10
  }'

Response (200 OK)

{
  "insights": [ ... ],
  "total": 5,
  "query": "What are the main onboarding friction points?"
}

---

Batch Archive/Unarchive

POST /api/insights/batch

Batch archive or unarchive insights during triage sessions.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
insight_ids	UUID[]	Yes	List of insight IDs to process
action	string	Yes	"archive" or "unarchive"

Response (200 OK)

{
  "updated_count": 5,
  "insight_ids": ["c3d4...", "d4e5...", "e5f6...", "f6a7...", "a7b8..."]
}