---
title: "Insights API reference"
canonical_url: https://zentrik.ai/docs/api/insights
markdown_url: https://zentrik.ai/docs/api/insights.md
last_reviewed: 2026-10-15
---

# Insights API reference

Insights describe patterns supported by source Evidence. Use these endpoints to read and curate patterns, review classifications, and record review without marking work complete.

- Human reference: https://zentrik.ai/docs/api/insights
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/insights/:id/review — Read review state

Operation ID: `get-insight-review`

Read or record the native review acknowledgement. Review does not approve work, resolve Evidence or validate a clinical claim. API review is attributed to the credential in the audit, without inventing a human reviewer. A reviewed Insight keeps its authored description during background Evidence-report refreshes.

Required API key scopes: `insights:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Internal UUID or workspace-scoped public ID. |

### Example request

```http
GET /external/v1/insights/INSIGHT-42/review
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Current review summary, including source/customer counts. Monetary summaries reflect linked Account values. | — |

### Example response

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "acknowledgedAt": "2026-10-12T15:00:00Z",
  "activeReports": 2
}
```

---

## PATCH /external/v1/insights/:id/review — Record completed review

Operation ID: `set-insight-review`

Read or record the native review acknowledgement. Review does not approve work, resolve Evidence or validate a clinical claim. API review is attributed to the credential in the audit, without inventing a human reviewer. A reviewed Insight keeps its authored description during background Evidence-report refreshes.

Required API key scopes: `insights:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Internal UUID or workspace-scoped public ID. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `acknowledged` | boolean | Yes | true records review; false clears the acknowledgement. |

### Example request

```http
PATCH /external/v1/insights/INSIGHT-42/review

{"acknowledged":true}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Current review summary, including source/customer counts. Monetary summaries reflect linked Account values. | — |

### Example response

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "acknowledgedAt": "2026-10-12T15:00:00Z",
  "activeReports": 2
}
```

---

## GET /external/v1/insights/:id/classifications — Read saved classifications

Operation ID: `get-insight-classifications`

Read current taxonomy values and review state, or apply the same manual review actions as the product. Use groupKey from the active taxonomy and optionIds returned by this read. Read the result after a correction; a preview or completed model run is not a review.

Required API key scopes: `insights:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Internal UUID or workspace-scoped public ID. |

### Example request

```http
GET /external/v1/insights/INSIGHT-42/classifications
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Current taxonomy version, group values and review summary. | — |

---

## PATCH /external/v1/insights/:id/classifications — Review classifications

Operation ID: `update-insight-classifications`

Read current taxonomy values and review state, or apply the same manual review actions as the product. Use groupKey from the active taxonomy and optionIds returned by this read. Read the result after a correction; a preview or completed model run is not a review.

Required API key scopes: `insights:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Internal UUID or workspace-scoped public ID. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `updates` | ClassificationUpdate[] | Yes | Exactly one update identifies groupKey or taxonomyGroupId and action: accept, reject, set_option, set_text or mark_unassigned. set_option supplies optionIds; set_text supplies textValue. Submit one group per operation so each correction has a separate receipt. |

### Example request

```http
PATCH /external/v1/insights/INSIGHT-42/classifications

{"updates":[{"groupKey":"workflow","action":"accept"}]}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Current taxonomy version, group values and review summary. | — |

---

## GET /external/v1/insights — List Insights

Operation ID: `list-insights`

Returns a bounded page of insights in your workspace. Insights are the core of discovery, representing feedback and data points collected from various sources.

Required API key scopes: `insights:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Maximum number of items to return (default: 20, maximum: 100) |
| `offset` | number | No | Number of items to skip (default: 0) |
| `include` | string | No | Comma-separated optional details. Supported values: classifications, provenance. Provenance can increase response size. |
| `sourceKey` | string | No | Exact stable source namespace to match |
| `externalId` | string | No | Exact source-record identifier to match |
| `integrationId` | uuid | No | Exact connected integration identifier to match |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/insights?limit=10 \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | A list of insights was successfully retrieved. Pagination metadata is returned in X-Total-Count, X-Limit, X-Offset, and X-Has-More headers. | Array<Insight> |

### Example response

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Users find navigation confusing",
    "description": "Initial feedback from customer interviews...",
    "status": "Validated",
    "type": "Usability friction",
    "productId": "8a1b2c3d-...",
    "createdAt": "2024-03-20T10:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z",
    "opportunityIds": [
      "uuid-1"
    ],
    "ideaIds": [
      "uuid-2"
    ],
    "tagIds": [
      "tag-1"
    ]
  }
]
```

---

## GET /external/v1/insights/:id — Get Insight

Operation ID: `get-insight`

Retrieve detailed information about a specific insight by its unique identifier.

Required API key scopes: `insights:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier of the insight |

### Example request

```curl
curl -X GET https://zentrik.ai/api/external/v1/insights/550e8400-e29b-41d4-a716-446655440000 \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The insight details were successfully retrieved. | Insight |
| 404 | Not Found | No insight found with the provided ID. | — |

### Example response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Users find navigation confusing",
  "description": "Initial feedback from customer interviews...",
  "status": "Validated",
  "type": "Usability friction",
  "productId": "8a1b2c3d-...",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "opportunityIds": [
    "uuid-1"
  ],
  "ideaIds": [
    "uuid-2"
  ],
  "tagIds": [
    "tag-1"
  ]
}
```

---

## POST /external/v1/insights — Create Insight

Operation ID: `create-insight`

Create or idempotently update a structured finding. Send sourceKey with externalId for a stable source identity. Send raw transcripts and other evidence to the Signals API so Zentrik preserves Evidence before routing findings.

Required API key scopes: `insights:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The title of the insight |
| `description` | string | Yes | Detailed summary of the observation |
| `status` | string | No | One of: New, Validated, Completed, Rejected. Default is New. |
| `type` | string | No | One of: Bug, Request, Unmet need, Usability friction, Customer workflow, Positive feedback, Tech, Sales & Procurement, Market, Business Model, Other. |
| `productId` | uuid | No | ID of the associated product |
| `sourceKey` | string | No | Stable source namespace. Use it with externalId for idempotent create-or-update behavior. |
| `externalId` | string | No | Stable record identifier within sourceKey. |
| `integrationId` | uuid | No | Connected integration identifier for integration-owned records. |
| `opportunityIds` | string[] | No | List of associated opportunity IDs |
| `ideaIds` | string[] | No | List of associated idea IDs |
| `tagIds` | string[] | No | List of associated tag IDs |
| `suggestions` | object | No | AI-generated suggestions for the insight |
| `externalLinks` | object[] | No | Array of { type, url, name } for external references |

### Example request

```json
{
  "name": "User finds the billing page confusing",
  "description": "During user interviews, 3/5 users couldn't find...",
  "status": "Validated",
  "type": "Usability friction",
  "productId": "8a1b2c3d-...",
  "sourceKey": "research-repository",
  "externalId": "finding-184",
  "tagIds": [
    "tag-1"
  ]
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The insight was successfully created. | Insight |

### Example response

```json
{
  "id": "uuid",
  "name": "User finds the billing page confusing",
  "description": "During user interviews, 3/5 users couldn't find...",
  "status": "Validated",
  "type": "Usability friction",
  "productId": "8a1b2c3d-...",
  "sourceKey": "research-repository",
  "externalId": "finding-184",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "opportunityIds": [],
  "ideaIds": [],
  "tagIds": [
    "tag-1"
  ]
}
```

---

## PATCH /external/v1/insights/:id — Update Insight

Operation ID: `update-insight`

Modify an existing insight by UUID. You can update its status, type, source identity, links, or description as the finding evolves.

Required API key scopes: `insights:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier of the insight |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Updated title |
| `description` | string | No | Updated description |
| `status` | string | No | Updated state: New, Validated, Completed, or Rejected |
| `type` | string | No | Updated type |
| `productId` | uuid \| null | No | Updated product association; null removes the product |
| `sourceKey` | string | No | Updated stable source namespace |
| `externalId` | string | No | Updated source-record identifier |
| `opportunityIds` | string[] | No | Updated list of opportunity IDs |
| `ideaIds` | string[] | No | Updated list of idea IDs |
| `tagIds` | string[] | No | Updated list of tag IDs |

### Example request

```curl
curl -X PATCH https://zentrik.ai/api/external/v1/insights/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status": "Rejected"}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated | The insight was successfully updated. | Insight |

### Example response

```json
{
  "id": "uuid",
  "name": "Users find navigation confusing",
  "description": "Initial feedback from customer interviews...",
  "status": "Rejected",
  "type": "Usability friction",
  "productId": "8a1b2c3d-...",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-21T09:00:00Z"
}
```

---

## DELETE /external/v1/insights/:id — Delete Insight

Operation ID: `delete-insight`

Permanently remove an insight from the workspace. This action cannot be undone.

Required API key scopes: `insights:delete`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | uuid | Yes | The unique identifier of the insight |

### Example request

```curl
curl -X DELETE https://zentrik.ai/api/external/v1/insights/uuid \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The insight was successfully deleted. | { message: string } |

### Example response

```json
{
  "message": "Deleted"
}
```

---

## POST /external/v1/insights/process-transcript/insights — Preview insights from text (AI)

Operation ID: `ai-extract-insights`

Preview insight candidates extracted from meeting transcripts, support tickets, or long-form feedback. This endpoint does not persist results. To create durable product records, send the source text to POST /external/v1/signals so Zentrik captures Evidence before routing or creating Insights.

Required API key scopes: `insights:write`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transcript` | string | Yes | Full transcript text to analyze for insights |
| `productId` | uuid | No | Optional product ID used to scope the preview |

### Example request

```json
{
  "transcript": "Full text of the meeting or feedback..."
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | AI preview completed successfully. No records were persisted. | Array<InsightCandidate> |
| 400 | Direct persistence disabled | createInsights=true is not supported. Create a Signal so Evidence is persisted before Insight routing. | — |

### Example response

```json
[
  {
    "title": "Navigation issue",
    "description": "Users expressed confusion about the menu layout...",
    "extracts": "I can never find the menu item I need.",
    "category": "Usability",
    "confidence": 91
  }
]
```