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

# Insights API reference

Insights are the core of discovery. They represent feedback, observations, or data points collected from users and markets. Use these endpoints to manage the lifecycle of your discovery data.

- 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 — 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, Rejected. Default is New. |
| `type` | string | No | One of: Bug, Request, Usability friction, Positive feedback, Tech, 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, or Rejected |
| `type` | string | No | Updated type |
| `productId` | uuid | No | Updated product association |
| `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
  }
]
```